From c84d61561c446d5b0e4b66adccb07234ec0e81b4 Mon Sep 17 00:00:00 2001
From: Davidson Gomes <davidson.gomes@etus.com.br>
Date: Wed, 22 Apr 2026 21:11:42 -0300
Subject: [PATCH 01/12] refactor(telegram): centralize notifications in
 routines, remove from skills
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move Telegram reply() out of skill SKILL.md files into the routine .py
callers via notify_telegram=True on run_skill(). This guarantees exactly
one send per execution — the instruction is appended at the end of the
prompt after all skill steps, so the agent cannot send it early.

- runner.py: add notify_telegram param to run_skill() — reads chat_id
  from TELEGRAM_CHAT_ID env, appends explicit one-shot instruction
- Skills cleaned: prod-end-of-day, prod-good-morning, pulse-faq-sync,
  pulse-daily (custom files gitignored, updated locally)
- Routines updated: end_of_day, good_morning (custom routines gitignored)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .claude/skills/prod-end-of-day/SKILL.md   |  7 ---
 .claude/skills/prod-good-morning/SKILL.md |  7 ---
 .claude/skills/pulse-daily/SKILL.md       |  7 ---
 .claude/skills/pulse-faq-sync/SKILL.md    |  8 ---
 ADWs/routines/end_of_day.py               |  2 +-
 ADWs/routines/good_morning.py             |  2 +-
 ADWs/runner.py                            | 64 ++++++++++++++++++++++-
 7 files changed, 64 insertions(+), 33 deletions(-)

diff --git a/.claude/skills/prod-end-of-day/SKILL.md b/.claude/skills/prod-end-of-day/SKILL.md
index 88059d11..a20b80d5 100644
--- a/.claude/skills/prod-end-of-day/SKILL.md
+++ b/.claude/skills/prod-end-of-day/SKILL.md
@@ -93,10 +93,3 @@ Present a short summary:
 **Tomorrow:** {sentence about where to resume}
 ```
 
-
-### Notify via Telegram
-
-Upon completion, send a short summary via Telegram to the user:
-- Use the Telegram MCP: `reply(chat_id="YOUR_CHAT_ID", text="...")`
-- Format: emoji + routine name + main result (1-3 lines)
-- If the routine had no updates, send anyway with "no updates"
diff --git a/.claude/skills/prod-good-morning/SKILL.md b/.claude/skills/prod-good-morning/SKILL.md
index e75bc47e..915390ac 100644
--- a/.claude/skills/prod-good-morning/SKILL.md
+++ b/.claude/skills/prod-good-morning/SKILL.md
@@ -64,10 +64,3 @@ Create the `workspace/daily-logs/` directory if it does not exist.
 ## Tone
 
 Keep the morning briefing conversational and brief. The user is starting their day — they don't need a wall of text. Punchy bullets, one clear recommendation, then move into action.
-
-### Notify via Telegram
-
-Upon completion, send a short summary via Telegram to the user:
-- Use the Telegram MCP: `reply(chat_id="YOUR_CHAT_ID", text="...")`
-- Format: emoji + routine name + main result (1-3 lines)
-- If the routine had no updates, send anyway with "no updates"
diff --git a/.claude/skills/pulse-daily/SKILL.md b/.claude/skills/pulse-daily/SKILL.md
index 4457a45c..0d461c40 100644
--- a/.claude/skills/pulse-daily/SKILL.md
+++ b/.claude/skills/pulse-daily/SKILL.md
@@ -93,10 +93,3 @@ Report saved to workspace/community/reports/daily/
 - **Compare with average** — if previous reports exist in the directory, compare metrics
 - **Empty channels = OK** — if a channel had no activity, do not report as a problem
 
-
-### Notify via Telegram
-
-Upon completion, send a short summary via Telegram to the user:
-- Use the Telegram MCP: `reply(chat_id="YOUR_CHAT_ID", text="...")`
-- Format: emoji + routine name + main result (1-3 lines)
-- If the routine had no updates, send anyway with "no updates"
diff --git a/.claude/skills/pulse-faq-sync/SKILL.md b/.claude/skills/pulse-faq-sync/SKILL.md
index f1aefdb0..c484103c 100644
--- a/.claude/skills/pulse-faq-sync/SKILL.md
+++ b/.claude/skills/pulse-faq-sync/SKILL.md
@@ -203,11 +203,3 @@ The "Skipped" block is mandatory — it gives visibility on questions the commun
 - **Tags in comments** — keep HTML comment tags for easy searching
 - **Keep organized** — categories in logical order (installation -> config -> integrations -> product -> billing -> errors)
 
-
-### Notify via Telegram
-
-Upon completion, send **exactly ONE** Telegram message with the full summary:
-- Use the Telegram MCP: `reply(chat_id="YOUR_CHAT_ID", text="...")`
-- Format: emoji + routine name + main result (totals + alerts combined in one message)
-- Do NOT split into multiple messages — combine summary and alerts into a single call
-- If the routine had no updates, send anyway with "no updates"
diff --git a/ADWs/routines/end_of_day.py b/ADWs/routines/end_of_day.py
index 2fabe95e..4314c2e5 100644
--- a/ADWs/routines/end_of_day.py
+++ b/ADWs/routines/end_of_day.py
@@ -8,7 +8,7 @@
 def main():
     banner("🌙 End of Day", "Memória • Logs • Tarefas • Aprendizados | @clawdia")
     results = []
-    results.append(run_skill("prod-end-of-day", log_name="end-of-day", timeout=600, agent="clawdia-assistant"))
+    results.append(run_skill("prod-end-of-day", log_name="end-of-day", timeout=600, agent="clawdia-assistant", notify_telegram=True))
     summary(results, "End of Day")
 
 if __name__ == "__main__":
diff --git a/ADWs/routines/good_morning.py b/ADWs/routines/good_morning.py
index 5c97c088..e6dc28b4 100644
--- a/ADWs/routines/good_morning.py
+++ b/ADWs/routines/good_morning.py
@@ -8,7 +8,7 @@
 def main():
     banner("☀️  Good Morning", "Agenda • Emails • Tarefas | @clawdia")
     results = []
-    results.append(run_skill("prod-good-morning", log_name="good-morning", timeout=600, agent="clawdia-assistant"))
+    results.append(run_skill("prod-good-morning", log_name="good-morning", timeout=600, agent="clawdia-assistant", notify_telegram=True))
     summary(results, "Good Morning")
 
 if __name__ == "__main__":
diff --git a/ADWs/runner.py b/ADWs/runner.py
index 6d1533a7..c7b75fbe 100644
--- a/ADWs/runner.py
+++ b/ADWs/runner.py
@@ -291,9 +291,38 @@ def run_claude(prompt: str, log_name: str = "unnamed", timeout: int = 600, agent
         return {"success": False, "stdout": "", "stderr": str(e), "returncode": -3, "duration": duration}
 
 
-def run_skill(skill_name: str, args: str = "", log_name: str = None, timeout: int = 600, agent: str = None) -> dict:
-    """Execute a skill via CLI, optionally with an agent."""
+def run_skill(
+    skill_name: str,
+    args: str = "",
+    log_name: str = None,
+    timeout: int = 600,
+    agent: str = None,
+    notify_telegram: bool | str = False,
+) -> dict:
+    """Execute a skill via CLI, optionally with an agent.
+
+    Args:
+        notify_telegram: Controls post-skill Telegram notification.
+            False (default) — no notification (skill must NOT call reply() either).
+            True            — appends notification instruction; reads chat_id from
+                              TELEGRAM_CHAT_ID env var.
+            "<chat_id>"     — same as True but overrides the chat_id.
+    """
     prompt = f"Execute the skill /{skill_name} {args}".strip()
+    if notify_telegram:
+        chat_id = (
+            notify_telegram
+            if isinstance(notify_telegram, str)
+            else os.environ.get("TELEGRAM_CHAT_ID", "")
+        )
+        if chat_id:
+            prompt += (
+                f"\n\nAo concluir TODOS os passos acima, envie UMA única mensagem Telegram via:"
+                f'\nreply(chat_id="{chat_id}", text="...")'
+                f"\nFormato: emoji + nome da rotina + principais resultados em 2-3 linhas."
+                f"\nCRÍTICO: chame reply() EXATAMENTE UMA VEZ, somente aqui no final."
+                f" Não envie mensagens intermediárias nem de progresso."
+            )
     return run_claude(prompt, log_name or skill_name, timeout, agent=agent)
 
 
@@ -393,3 +422,34 @@ def summary(results: list, title: str = "Completed"):
         border_style="green" if failed == 0 else "yellow",
         padding=(0, 2)
     ))
+
+
+def send_telegram(text: str, chat_id: str = None) -> bool:
+    """Send a Telegram message via bot API (no MCP dependency).
+
+    Reads TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID from environment.
+    Returns True if sent successfully, False otherwise.
+    """
+    import urllib.request
+    import urllib.parse
+
+    token = os.environ.get("TELEGRAM_BOT_TOKEN", "")
+    cid = chat_id or os.environ.get("TELEGRAM_CHAT_ID", "")
+    if not token or not cid:
+        console.print("  [warning]⚠ Telegram not configured (missing BOT_TOKEN or CHAT_ID)[/warning]")
+        return False
+
+    try:
+        payload = urllib.parse.urlencode({"chat_id": cid, "text": text, "parse_mode": "HTML"}).encode()
+        url = f"https://api.telegram.org/bot{token}/sendMessage"
+        req = urllib.request.Request(url, data=payload, method="POST")
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            ok = resp.status == 200
+        if ok:
+            console.print("  [success]✓[/success] Telegram enviado")
+        else:
+            console.print(f"  [warning]⚠ Telegram status {resp.status}[/warning]")
+        return ok
+    except Exception as e:
+        console.print(f"  [warning]⚠ Telegram error: {e}[/warning]")
+        return False

From 277adb0a900910e2919448a625efbc6d549626de Mon Sep 17 00:00:00 2001
From: Davidson Gomes <davidson.gomes@etus.com.br>
Date: Sat, 25 Apr 2026 07:53:56 -0300
Subject: [PATCH 02/12] fix(telegram): remove reply() from prod-review-todoist
 skill

Telegram notification was still in the skill file, causing the agent
to call reply() multiple times per run (3x observed on 25/04 at 06:51).

Notification now controlled by notify_telegram=True in review_todoist.py
(gitignored custom routine, already updated on disk).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .claude/skills/prod-review-todoist/SKILL.md | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/.claude/skills/prod-review-todoist/SKILL.md b/.claude/skills/prod-review-todoist/SKILL.md
index 2180aab2..34a78c1d 100644
--- a/.claude/skills/prod-review-todoist/SKILL.md
+++ b/.claude/skills/prod-review-todoist/SKILL.md
@@ -124,10 +124,3 @@ If the user wants to see details of what changed, they ask.
 - **If unsure about the category**, use `[Operations]` as fallback
 - **Execute first, report after** — no intermediate report
 
-
-### Notify via Telegram
-
-Upon completion, send **exactly ONE** Telegram message — do NOT call `reply()` more than once per run:
-- Use the Telegram MCP: `reply(chat_id="YOUR_CHAT_ID", text="...")`
-- Format: emoji + routine name + main result (1-3 lines, all combined in a single message)
-- If the routine had no updates, send anyway with "no updates"

From cab896653a38d6546e5315f7d00ef1dec37c4441 Mon Sep 17 00:00:00 2001
From: Davidson Gomes <davidson.gomes@etus.com.br>
Date: Sat, 25 Apr 2026 08:40:42 -0300
Subject: [PATCH 03/12] fix(chat-bridge): resolve agent file from
 WORKSPACE_ROOT, not session cwd
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ticket threads pass workspace_path (e.g. workspace/personal/) as the
session cwd. loadAgentFile was building the path relative to that cwd,
so it looked for .claude/agents/ inside the ticket's folder instead of
the workspace root — always failing for every agent.

Fix: try WORKSPACE_ROOT/.claude/agents/{name}.md first, fall back to
cwd for custom per-directory agents.

Affected: kai-personal-assistant, flux-finance, and any ticket with
a workspace_path set.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 dashboard/terminal-server/src/chat-bridge.js | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/dashboard/terminal-server/src/chat-bridge.js b/dashboard/terminal-server/src/chat-bridge.js
index 64827bf6..caf138b1 100644
--- a/dashboard/terminal-server/src/chat-bridge.js
+++ b/dashboard/terminal-server/src/chat-bridge.js
@@ -48,7 +48,10 @@ const NEEDS_APPROVAL = new Set([
  * Extracts YAML frontmatter for metadata and the body as the prompt.
  */
 function loadAgentFile(agentName, cwd) {
-  const agentPath = path.join(cwd, '.claude', 'agents', `${agentName}.md`);
+  // Agent definitions live at the workspace root — cwd varies per ticket session.
+  const rootPath = path.join(WORKSPACE_ROOT, '.claude', 'agents', `${agentName}.md`);
+  const cwdPath = path.join(cwd, '.claude', 'agents', `${agentName}.md`);
+  const agentPath = fs.existsSync(rootPath) ? rootPath : cwdPath;
   if (!fs.existsSync(agentPath)) {
     console.warn(`[chat-bridge] Agent file not found: ${agentPath}`);
     return null;

From cc27a4abe2a47441e27feb6c6b71292a50c0e67a Mon Sep 17 00:00:00 2001
From: Davidson Gomes <davidson.gomes@etus.com.br>
Date: Sun, 26 Apr 2026 20:14:05 -0300
Subject: [PATCH 04/12] fix(telegram): eliminate duplicate notifications from
 inline reply() template
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Root cause: notify_telegram instruction showed reply(chat_id=..., text="...")
as an inline code snippet, causing the agent to execute it immediately on
reading the instruction AND again at the end — 2x per instruction.

Financial Pulse was getting 4x because the skill's Step 8 also contained
a reply() call instruction (2 instructions × 2 executions = 4 messages).

Fixes:
- runner.py: rewrite notify_telegram prompt to describe the action in
  plain text without an inline function-call template
- fin-daily-pulse SKILL.md: remove Step 8 Telegram section — notification
  is handled by the routine caller via notify_telegram=True

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .claude/skills/fin-daily-pulse/SKILL.md |  8 +++-----
 ADWs/runner.py                          | 12 +++++++-----
 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/.claude/skills/fin-daily-pulse/SKILL.md b/.claude/skills/fin-daily-pulse/SKILL.md
index 2f2a74af..1c98eba8 100644
--- a/.claude/skills/fin-daily-pulse/SKILL.md
+++ b/.claude/skills/fin-daily-pulse/SKILL.md
@@ -157,9 +157,9 @@ workspace/finance/reports/daily/[C] YYYY-MM-DD-financial-pulse.html
 
 Create the directory `workspace/finance/reports/daily/` if it does not exist.
 
-## Step 8 — Confirm and notify (ONE Telegram message only)
+## Step 8 — Confirm
 
-Output the completion summary, then send **exactly one** Telegram message. Do NOT call `reply` more than once per run.
+Output the completion summary in the terminal:
 
 ```
 ## Financial Pulse generated
@@ -171,6 +171,4 @@ Output the completion summary, then send **exactly one** Telegram message. Do NO
 **Alerts:** {N} attention points
 ```
 
-Call `reply` **once** with a short summary (do not send the full markdown above — send a compact version):
-
-- Format: `[emoji] Financial Pulse [date] | MRR: R$ X,XXX | Receita: R$ X,XXX | Churn: X% | [N] alertas`
+Do NOT send a Telegram message here — the caller handles notifications.
diff --git a/ADWs/runner.py b/ADWs/runner.py
index c7b75fbe..30c06a45 100644
--- a/ADWs/runner.py
+++ b/ADWs/runner.py
@@ -317,11 +317,13 @@ def run_skill(
         )
         if chat_id:
             prompt += (
-                f"\n\nAo concluir TODOS os passos acima, envie UMA única mensagem Telegram via:"
-                f'\nreply(chat_id="{chat_id}", text="...")'
-                f"\nFormato: emoji + nome da rotina + principais resultados em 2-3 linhas."
-                f"\nCRÍTICO: chame reply() EXATAMENTE UMA VEZ, somente aqui no final."
-                f" Não envie mensagens intermediárias nem de progresso."
+                f"\n\n---\n"
+                f"NOTIFICAÇÃO TELEGRAM — executar SOMENTE após concluir TODOS os passos acima.\n"
+                f"Use a ferramenta Telegram reply com chat_id={chat_id} e um texto compacto:\n"
+                f"  emoji + nome da rotina + data + principais resultados em 2-3 linhas.\n"
+                f"REGRA ABSOLUTA: chame a ferramenta reply UMA ÚNICA VEZ, no final de tudo.\n"
+                f"Nunca chame reply para progresso, confirmação intermediária ou teste.\n"
+                f"---"
             )
     return run_claude(prompt, log_name or skill_name, timeout, agent=agent)
 

From 7400aa1aecb99f9612031522d6a7039469156cd8 Mon Sep 17 00:00:00 2001
From: Davidson Gomes <davidson.gomes@etus.com.br>
Date: Sun, 26 Apr 2026 20:18:38 -0300
Subject: [PATCH 05/12] fix(telegram): remove all inline reply() calls from
 skill SKILL.md files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Comprehensive sweep of all 175+ skills. Root cause of all duplicate
Telegram notifications: skills contained inline reply(chat_id=...) code
examples that Claude executed immediately on reading, then called again
at the actual end-of-skill step — causing 2x (or 4x when combined with
a second instruction from notify_telegram=True in the routine).

Changes:
- Removed "Notify via Telegram" sections entirely from 10 skills that
  have a corresponding routine using notify_telegram=True:
  fin-weekly-report, gog-email-triage, prod-dashboard, prod-trends,
  pulse-monthly, pulse-weekly, sage-strategy-digest,
  fin-monthly-close-kickoff, social-analytics-report, social-youtube-report

- Rewrote Telegram instructions without inline reply() code in 4 skills
  that are called without notify_telegram (heartbeat or conditional):
  int-sync-meetings, int-github-review, int-linear-review (plain text),
  custom-getfy-sync, custom-omc-sync (plain text, local/gitignored)

The corresponding routines (gitignored) were updated locally to add
notify_telegram=True where the section was removed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../skills/fin-monthly-close-kickoff/SKILL.md    |  6 ------
 .claude/skills/fin-weekly-report/SKILL.md        |  6 ------
 .claude/skills/gog-email-triage/SKILL.md         |  8 --------
 .claude/skills/int-github-review/SKILL.md        |  7 +++----
 .claude/skills/int-linear-review/SKILL.md        |  7 +++----
 .claude/skills/int-sync-meetings/SKILL.md        | 11 ++++++-----
 .claude/skills/prod-dashboard/SKILL.md           |  7 -------
 .claude/skills/prod-trends/SKILL.md              |  8 --------
 .claude/skills/pulse-monthly/SKILL.md            |  6 ------
 .claude/skills/pulse-weekly/SKILL.md             |  8 --------
 .claude/skills/sage-strategy-digest/SKILL.md     |  8 --------
 .claude/skills/social-analytics-report/SKILL.md  | 13 -------------
 .claude/skills/social-youtube-report/SKILL.md    |  5 -----
 dashboard/terminal-server/package-lock.json      |  3 ---
 uv.lock                                          | 16 ++--------------
 15 files changed, 14 insertions(+), 105 deletions(-)

diff --git a/.claude/skills/fin-monthly-close-kickoff/SKILL.md b/.claude/skills/fin-monthly-close-kickoff/SKILL.md
index a62548f3..83a97202 100644
--- a/.claude/skills/fin-monthly-close-kickoff/SKILL.md
+++ b/.claude/skills/fin-monthly-close-kickoff/SKILL.md
@@ -182,9 +182,3 @@ Create the directory `workspace/finance/reports/monthly/` if it does not exist.
 **Checklist:** X/10 completed
 **Finance team pending items:** {N} items
 ```
-
-### Notify via Telegram
-
-Upon completion, send a short summary via Telegram to the user:
-- Use the Telegram MCP: `reply(chat_id="YOUR_CHAT_ID", text="...")`
-- Format: emoji + "Monthly Close" + month's result + pending items (2-3 lines)
diff --git a/.claude/skills/fin-weekly-report/SKILL.md b/.claude/skills/fin-weekly-report/SKILL.md
index ef3c85f2..4c344aa2 100644
--- a/.claude/skills/fin-weekly-report/SKILL.md
+++ b/.claude/skills/fin-weekly-report/SKILL.md
@@ -164,9 +164,3 @@ Create the directory `workspace/finance/reports/weekly/` if it does not exist.
 **MRR total:** R$ X,XXX (Stripe: R$ X,XXX | Evo Academy: R$ X,XXX) | **Projected 30d balance:** R$ XX,XXX
 **Alerts:** {N} overdue accounts | {N} pending invoices
 ```
-
-### Notify via Telegram
-
-Upon completion, send a short summary via Telegram to the user:
-- Use the Telegram MCP: `reply(chat_id="YOUR_CHAT_ID", text="...")`
-- Format: emoji + "Financial Weekly" + revenue vs expenses + MRR + alerts (2-3 lines)
diff --git a/.claude/skills/gog-email-triage/SKILL.md b/.claude/skills/gog-email-triage/SKILL.md
index 44cc3d45..3bda6b0f 100644
--- a/.claude/skills/gog-email-triage/SKILL.md
+++ b/.claude/skills/gog-email-triage/SKILL.md
@@ -354,11 +354,3 @@ See `skills/gog/_shared/references/testing.md` for complete test plan.
 - If email subject/sender contains obvious credentials or secrets, redact in output
 
 - For recurring newsletters, suggest creating a filter/rule rather than manual archiving
-
-
-### Notify via Telegram
-
-Upon completion, send a short summary via Telegram to the user:
-- Use the Telegram MCP: `reply(chat_id="YOUR_CHAT_ID", text="...")`
-- Format: emoji + routine name + main result (1-3 lines)
-- If the routine had no updates, send anyway with "no updates"
diff --git a/.claude/skills/int-github-review/SKILL.md b/.claude/skills/int-github-review/SKILL.md
index d9ac780a..5cf8edcc 100644
--- a/.claude/skills/int-github-review/SKILL.md
+++ b/.claude/skills/int-github-review/SKILL.md
@@ -118,7 +118,6 @@ Create directory if it does not exist.
 
 ### Notify via Telegram
 
-Upon completion, send a short summary via Telegram to the user:
-- Use the Telegram MCP: `reply(chat_id="YOUR_CHAT_ID", text="...")`
-- Format: emoji + routine name + main result (1-3 lines)
-- If the routine had no updates, send anyway with "no updates"
+Upon completion, use the Telegram reply tool to send a short summary to the user.
+Format: emoji + routine name + main result (1-3 lines).
+If the routine had no updates, send anyway with "no updates".
diff --git a/.claude/skills/int-linear-review/SKILL.md b/.claude/skills/int-linear-review/SKILL.md
index 1deb55e7..e0ce493d 100644
--- a/.claude/skills/int-linear-review/SKILL.md
+++ b/.claude/skills/int-linear-review/SKILL.md
@@ -97,7 +97,6 @@ Create the directory `workspace/projects/linear-reviews/` if it does not exist.
 
 ### Notify via Telegram
 
-Upon completion, send a short summary via Telegram to the user:
-- Use the Telegram MCP: `reply(chat_id="YOUR_CHAT_ID", text="...")`
-- Format: emoji + routine name + main result (1-3 lines)
-- If the routine had no updates, send anyway with "no updates"
+Upon completion, use the Telegram reply tool to send a short summary to the user.
+Format: emoji + routine name + main result (1-3 lines).
+If the routine had no updates, send anyway with "no updates".
diff --git a/.claude/skills/int-sync-meetings/SKILL.md b/.claude/skills/int-sync-meetings/SKILL.md
index c4b22f22..2302f85e 100644
--- a/.claude/skills/int-sync-meetings/SKILL.md
+++ b/.claude/skills/int-sync-meetings/SKILL.md
@@ -186,12 +186,13 @@ Without listing tasks one by one — just counts. If the user wants details, the
 
 ### Step 9 — Notify via Telegram
 
-Send the Step 8 summary via Telegram to the user using the `/int-telegram` skill:
-- Chat ID: `YOUR_CHAT_ID`
-- Use `reply(chat_id="YOUR_CHAT_ID", text="...")` via MCP
-- Short format: emoji + title + meeting and task count
+Only send if at least one new meeting was processed (i.e., you did NOT stop at Step 2).
 
-If there are no new meetings (stopped at Step 2), do **NOT** send any Telegram message — stay silent. Only notify when at least one new meeting was processed.
+Use the Telegram reply tool with the user's chat_id and a short summary:
+- Format: emoji + title + meeting count + task count
+- One line only
+
+If there are no new meetings (stopped at Step 2), do **NOT** send any Telegram message — stay completely silent.
 
 ## Notes
 
diff --git a/.claude/skills/prod-dashboard/SKILL.md b/.claude/skills/prod-dashboard/SKILL.md
index 56c3c84a..56da10f4 100644
--- a/.claude/skills/prod-dashboard/SKILL.md
+++ b/.claude/skills/prod-dashboard/SKILL.md
@@ -142,10 +142,3 @@ Present a short summary:
 **Health:** Product {status} | Community {status} | Financial {status} | Routines {status}
 **Alerts:** {N} attention points
 ```
-
-### Notify via Telegram
-
-Upon completion, send a short summary via Telegram to the user:
-- Use the Telegram MCP: `reply(chat_id="YOUR_CHAT_ID", text="...")`
-- Format: emoji + routine name + health status of each area (1-3 lines)
-- If there were no updates, send anyway with "no updates"
diff --git a/.claude/skills/prod-trends/SKILL.md b/.claude/skills/prod-trends/SKILL.md
index 051ce18d..062f5270 100644
--- a/.claude/skills/prod-trends/SKILL.md
+++ b/.claude/skills/prod-trends/SKILL.md
@@ -163,11 +163,3 @@ Create `memory/trends/` if it does not exist.
 - **If a source has no data, skip** — do not block due to a missing report
 - **Focus on action** — each insight should lead to a concrete recommendation
 - **Do not alarm without evidence** — red only when the metric truly indicates risk
-
-
-### Notify via Telegram
-
-Upon completion, send a short summary via Telegram to the user:
-- Use the Telegram MCP: `reply(chat_id="YOUR_CHAT_ID", text="...")`
-- Format: emoji + routine name + main result (1-3 lines)
-- If the routine had no updates, send anyway with "no updates"
diff --git a/.claude/skills/pulse-monthly/SKILL.md b/.claude/skills/pulse-monthly/SKILL.md
index c84a2439..dbe8cfb1 100644
--- a/.claude/skills/pulse-monthly/SKILL.md
+++ b/.claude/skills/pulse-monthly/SKILL.md
@@ -178,9 +178,3 @@ Create the directory `workspace/community/reports/monthly/` if it does not exist
 **Sentiment:** {trend} | **Resolution:** {X}%
 **Highlights:** {N} features, {N} bugs, {N} docs gaps
 ```
-
-### Notify via Telegram
-
-Upon completion, send a short summary via Telegram to the user:
-- Use the Telegram MCP: `reply(chat_id="YOUR_CHAT_ID", text="...")`
-- Format: emoji + "Community Monthly" + MAM + sentiment + highlights (2-3 lines)
diff --git a/.claude/skills/pulse-weekly/SKILL.md b/.claude/skills/pulse-weekly/SKILL.md
index ff41cc33..10d584fb 100644
--- a/.claude/skills/pulse-weekly/SKILL.md
+++ b/.claude/skills/pulse-weekly/SKILL.md
@@ -111,11 +111,3 @@ Report saved to workspace/community/reports/weekly/
 - **Docs gap is gold** — each question without docs becomes a backlog item
 - **Comparison is fundamental** — always show trend vs previous week
 - **Product insights** — the most valuable section, handle with care
-
-
-### Notify via Telegram
-
-Upon completion, send a short summary via Telegram to the user:
-- Use the Telegram MCP: `reply(chat_id="YOUR_CHAT_ID", text="...")`
-- Format: emoji + routine name + main result (1-3 lines)
-- If the routine had no updates, send anyway with "no updates"
diff --git a/.claude/skills/sage-strategy-digest/SKILL.md b/.claude/skills/sage-strategy-digest/SKILL.md
index ff47d1c3..f4f8135e 100644
--- a/.claude/skills/sage-strategy-digest/SKILL.md
+++ b/.claude/skills/sage-strategy-digest/SKILL.md
@@ -96,11 +96,3 @@ Present a short and direct version.
 - **Opinions flagged** — when it is opinion vs data, make it clear
 - **One recommendation** — do not give 10 suggestions, give 1 clear one
 - **Connect the dots** — the value of the digest is crossing areas, not repeating individual reports
-
-
-### Notify via Telegram
-
-Upon completion, send a short summary via Telegram to the user:
-- Use the Telegram MCP: `reply(chat_id="YOUR_CHAT_ID", text="...")`
-- Format: emoji + routine name + main result (1-3 lines)
-- If the routine had no updates, send anyway with "no updates"
diff --git a/.claude/skills/social-analytics-report/SKILL.md b/.claude/skills/social-analytics-report/SKILL.md
index ce8aec24..fdc2c2c9 100644
--- a/.claude/skills/social-analytics-report/SKILL.md
+++ b/.claude/skills/social-analytics-report/SKILL.md
@@ -137,16 +137,3 @@ workspace/social/reports/consolidated/[C] YYYY-MM-DD-social-analytics.html
 ```
 
 Create directory if it does not exist.
-
-### Step 9 — Telegram
-
-Notify: `reply(chat_id="YOUR_CHAT_ID", text="...")`
-Format:
-```
-📊 Social Analytics — {period}
-👥 Total followers: {N} ({delta})
-📹 YouTube: {subs} sub | {eng}% eng
-📸 Instagram: {followers} fol | {eng}% eng  
-💼 LinkedIn: profile connected
-🏆 Top: "{best content}" ({platform}, {eng}%)
-```
diff --git a/.claude/skills/social-youtube-report/SKILL.md b/.claude/skills/social-youtube-report/SKILL.md
index 63d2ace6..8d5c42bf 100644
--- a/.claude/skills/social-youtube-report/SKILL.md
+++ b/.claude/skills/social-youtube-report/SKILL.md
@@ -64,8 +64,3 @@ workspace/social/reports/youtube/[C] YYYY-MM-DD-youtube-{period}.html
 ```
 
 Criar diretório if it does not exist.
-
-### Step 7 — Telegram
-
-Notify: `reply(chat_id="946857210", text="...")`
-Format: emoji + canal + inscritos + delta + melhor vídeo
diff --git a/dashboard/terminal-server/package-lock.json b/dashboard/terminal-server/package-lock.json
index 1a4af597..0611b4de 100644
--- a/dashboard/terminal-server/package-lock.json
+++ b/dashboard/terminal-server/package-lock.json
@@ -858,7 +858,6 @@
       "resolved": "https://registry.npmjs.org/express/-/express-4.22.1.tgz",
       "integrity": "sha512-F2X8g9P1X7uCPZMA3MVf9wcTqlyNp7IhH5qPCI0izhaOIYXaW9L535tGA3qmjRzpH+bZczqq7hVKxTR4NWnu+g==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "accepts": "~1.3.8",
         "array-flatten": "1.1.1",
@@ -1063,7 +1062,6 @@
       "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.15.tgz",
       "integrity": "sha512-qM0jDhFEaCBb4TxoW7f53Qrpv9RBiayUHo0S52JudprkhvpjIrGoU1mnnr29Fvd1U335ZFPZQY1wlkqgfGXyLg==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=16.9.0"
       }
@@ -1765,7 +1763,6 @@
       "resolved": "https://registry.npmjs.org/zod/-/zod-4.3.6.tgz",
       "integrity": "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==",
       "license": "MIT",
-      "peer": true,
       "funding": {
         "url": "https://github.com/sponsors/colinhacks"
       }
diff --git a/uv.lock b/uv.lock
index 6d6116d7..69360e19 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1,5 +1,5 @@
 version = 1
-revision = 2
+revision = 3
 requires-python = ">=3.10"
 resolution-markers = [
     "python_full_version >= '3.14' and sys_platform == 'darwin'",
@@ -589,7 +589,7 @@ wheels = [
 
 [[package]]
 name = "evo-nexus"
-version = "0.32.3"
+version = "0.32.2"
 source = { virtual = "." }
 dependencies = [
     { name = "alembic" },
@@ -826,18 +826,14 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/0c/bc/e30e1e3d5e8860b0e0ce4d2b16b2681b77fd13542fc0d72f7e3c22d16eff/greenlet-3.4.0-cp310-cp310-macosx_11_0_universal2.whl", hash = "sha256:d18eae9a7fb0f499efcd146b8c9750a2e1f6e0e93b5a382b3481875354a430e6", size = 284315, upload-time = "2026-04-08T17:02:52.322Z" },
     { url = "https://files.pythonhosted.org/packages/5b/cc/e023ae1967d2a26737387cac083e99e47f65f58868bd155c4c80c01ec4e0/greenlet-3.4.0-cp310-cp310-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:636d2f95c309e35f650e421c23297d5011716be15d966e6328b367c9fc513a82", size = 601916, upload-time = "2026-04-08T16:24:35.533Z" },
     { url = "https://files.pythonhosted.org/packages/67/32/5be1677954b6d8810b33abe94e3eb88726311c58fa777dc97e390f7caf5a/greenlet-3.4.0-cp310-cp310-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:234582c20af9742583c3b2ddfbdbb58a756cfff803763ffaae1ac7990a9fac31", size = 616399, upload-time = "2026-04-08T16:30:54.536Z" },
-    { url = "https://files.pythonhosted.org/packages/82/0a/3a4af092b09ea02bcda30f33fd7db397619132fe52c6ece24b9363130d34/greenlet-3.4.0-cp310-cp310-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:ac6a5f618be581e1e0713aecec8e54093c235e5fa17d6d8eb7ffc487e2300508", size = 621077, upload-time = "2026-04-08T16:40:34.946Z" },
     { url = "https://files.pythonhosted.org/packages/74/bf/2d58d5ea515704f83e34699128c9072a34bea27d2b6a556e102105fe62a5/greenlet-3.4.0-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:523677e69cd4711b5a014e37bc1fb3a29947c3e3a5bb6a527e1cc50312e5a398", size = 611978, upload-time = "2026-04-08T15:56:31.335Z" },
-    { url = "https://files.pythonhosted.org/packages/8c/39/3786520a7d5e33ee87b3da2531f589a3882abf686a42a3773183a41ef010/greenlet-3.4.0-cp310-cp310-manylinux_2_39_riscv64.whl", hash = "sha256:d336d46878e486de7d9458653c722875547ac8d36a1cff9ffaf4a74a3c1f62eb", size = 416893, upload-time = "2026-04-08T16:43:02.392Z" },
     { url = "https://files.pythonhosted.org/packages/bd/69/6525049b6c179d8a923256304d8387b8bdd4acab1acf0407852463c6d514/greenlet-3.4.0-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:b45e45fe47a19051a396abb22e19e7836a59ee6c5a90f3be427343c37908d65b", size = 1571957, upload-time = "2026-04-08T16:26:17.041Z" },
     { url = "https://files.pythonhosted.org/packages/4e/6c/bbfb798b05fec736a0d24dc23e81b45bcee87f45a83cfb39db031853bddc/greenlet-3.4.0-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:5434271357be07f3ad0936c312645853b7e689e679e29310e2de09a9ea6c3adf", size = 1637223, upload-time = "2026-04-08T15:57:27.556Z" },
     { url = "https://files.pythonhosted.org/packages/b7/7d/981fe0e7c07bd9d5e7eb18decb8590a11e3955878291f7a7de2e9c668eb7/greenlet-3.4.0-cp310-cp310-win_amd64.whl", hash = "sha256:a19093fbad824ed7c0f355b5ff4214bffda5f1a7f35f29b31fcaa240cc0135ab", size = 237902, upload-time = "2026-04-08T17:03:14.16Z" },
     { url = "https://files.pythonhosted.org/packages/fb/c6/dba32cab7e3a625b011aa5647486e2d28423a48845a2998c126dd69c85e1/greenlet-3.4.0-cp311-cp311-macosx_11_0_universal2.whl", hash = "sha256:805bebb4945094acbab757d34d6e1098be6de8966009ab9ca54f06ff492def58", size = 285504, upload-time = "2026-04-08T15:52:14.071Z" },
     { url = "https://files.pythonhosted.org/packages/54/f4/7cb5c2b1feb9a1f50e038be79980dfa969aa91979e5e3a18fdbcfad2c517/greenlet-3.4.0-cp311-cp311-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:439fc2f12b9b512d9dfa681c5afe5f6b3232c708d13e6f02c845e0d9f4c2d8c6", size = 605476, upload-time = "2026-04-08T16:24:37.064Z" },
     { url = "https://files.pythonhosted.org/packages/d6/af/b66ab0b2f9a4c5a867c136bf66d9599f34f21a1bcca26a2884a29c450bd9/greenlet-3.4.0-cp311-cp311-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:a70ed1cb0295bee1df57b63bf7f46b4e56a5c93709eea769c1fec1bb23a95875", size = 618336, upload-time = "2026-04-08T16:30:56.59Z" },
-    { url = "https://files.pythonhosted.org/packages/6d/31/56c43d2b5de476f77d36ceeec436328533bff960a4cba9a07616e93063ab/greenlet-3.4.0-cp311-cp311-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:8c5696c42e6bb5cfb7c6ff4453789081c66b9b91f061e5e9367fa15792644e76", size = 625045, upload-time = "2026-04-08T16:40:37.111Z" },
     { url = "https://files.pythonhosted.org/packages/e5/5c/8c5633ece6ba611d64bf2770219a98dd439921d6424e4e8cf16b0ac74ea5/greenlet-3.4.0-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c660bce1940a1acae5f51f0a064f1bc785d07ea16efcb4bc708090afc4d69e83", size = 613515, upload-time = "2026-04-08T15:56:32.478Z" },
-    { url = "https://files.pythonhosted.org/packages/80/ca/704d4e2c90acb8bdf7ae593f5cbc95f58e82de95cc540fb75631c1054533/greenlet-3.4.0-cp311-cp311-manylinux_2_39_riscv64.whl", hash = "sha256:89995ce5ddcd2896d89615116dd39b9703bfa0c07b583b85b89bf1b5d6eddf81", size = 419745, upload-time = "2026-04-08T16:43:04.022Z" },
     { url = "https://files.pythonhosted.org/packages/a9/df/950d15bca0d90a0e7395eb777903060504cdb509b7b705631e8fb69ff415/greenlet-3.4.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:ee407d4d1ca9dc632265aee1c8732c4a2d60adff848057cdebfe5fe94eb2c8a2", size = 1574623, upload-time = "2026-04-08T16:26:18.596Z" },
     { url = "https://files.pythonhosted.org/packages/1a/e7/0839afab829fcb7333c9ff6d80c040949510055d2d4d63251f0d1c7c804e/greenlet-3.4.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:956215d5e355fffa7c021d168728321fd4d31fd730ac609b1653b450f6a4bc71", size = 1639579, upload-time = "2026-04-08T15:57:29.231Z" },
     { url = "https://files.pythonhosted.org/packages/d9/2b/b4482401e9bcaf9f5c97f67ead38db89c19520ff6d0d6699979c6efcc200/greenlet-3.4.0-cp311-cp311-win_amd64.whl", hash = "sha256:5cb614ace7c27571270354e9c9f696554d073f8aa9319079dcba466bbdead711", size = 238233, upload-time = "2026-04-08T17:02:54.286Z" },
@@ -845,9 +841,7 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/65/8b/3669ad3b3f247a791b2b4aceb3aa5a31f5f6817bf547e4e1ff712338145a/greenlet-3.4.0-cp312-cp312-macosx_11_0_universal2.whl", hash = "sha256:1a54a921561dd9518d31d2d3db4d7f80e589083063ab4d3e2e950756ef809e1a", size = 286902, upload-time = "2026-04-08T15:52:12.138Z" },
     { url = "https://files.pythonhosted.org/packages/38/3e/3c0e19b82900873e2d8469b590a6c4b3dfd2b316d0591f1c26b38a4879a5/greenlet-3.4.0-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:16dec271460a9a2b154e3b1c2fa1050ce6280878430320e85e08c166772e3f97", size = 606099, upload-time = "2026-04-08T16:24:38.408Z" },
     { url = "https://files.pythonhosted.org/packages/b5/33/99fef65e7754fc76a4ed14794074c38c9ed3394a5bd129d7f61b705f3168/greenlet-3.4.0-cp312-cp312-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:90036ce224ed6fe75508c1907a77e4540176dcf0744473627785dd519c6f9996", size = 618837, upload-time = "2026-04-08T16:30:58.298Z" },
-    { url = "https://files.pythonhosted.org/packages/44/57/eae2cac10421feae6c0987e3dc106c6d86262b1cb379e171b017aba893a6/greenlet-3.4.0-cp312-cp312-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:6f0def07ec9a71d72315cf26c061aceee53b306c36ed38c35caba952ea1b319d", size = 624901, upload-time = "2026-04-08T16:40:38.981Z" },
     { url = "https://files.pythonhosted.org/packages/36/f7/229f3aed6948faa20e0616a0b8568da22e365ede6a54d7d369058b128afd/greenlet-3.4.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a1c4f6b453006efb8310affb2d132832e9bbb4fc01ce6df6b70d810d38f1f6dc", size = 615062, upload-time = "2026-04-08T15:56:33.766Z" },
-    { url = "https://files.pythonhosted.org/packages/6a/8a/0e73c9b94f31d1cc257fe79a0eff621674141cdae7d6d00f40de378a1e42/greenlet-3.4.0-cp312-cp312-manylinux_2_39_riscv64.whl", hash = "sha256:0e1254cf0cbaa17b04320c3a78575f29f3c161ef38f59c977108f19ffddaf077", size = 423927, upload-time = "2026-04-08T16:43:05.293Z" },
     { url = "https://files.pythonhosted.org/packages/08/97/d988180011aa40135c46cd0d0cf01dd97f7162bae14139b4a3ef54889ba5/greenlet-3.4.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:9b2d9a138ffa0e306d0e2b72976d2fb10b97e690d40ab36a472acaab0838e2de", size = 1573511, upload-time = "2026-04-08T16:26:20.058Z" },
     { url = "https://files.pythonhosted.org/packages/d4/0f/a5a26fe152fb3d12e6a474181f6e9848283504d0afd095f353d85726374b/greenlet-3.4.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:8424683caf46eb0eb6f626cb95e008e8cc30d0cb675bdfa48200925c79b38a08", size = 1640396, upload-time = "2026-04-08T15:57:30.88Z" },
     { url = "https://files.pythonhosted.org/packages/42/cf/bb2c32d9a100e36ee9f6e38fad6b1e082b8184010cb06259b49e1266ca01/greenlet-3.4.0-cp312-cp312-win_amd64.whl", hash = "sha256:a0a53fb071531d003b075c444014ff8f8b1a9898d36bb88abd9ac7b3524648a2", size = 238892, upload-time = "2026-04-08T17:03:10.094Z" },
@@ -855,9 +849,7 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/7a/75/7e9cd1126a1e1f0cd67b0eda02e5221b28488d352684704a78ed505bd719/greenlet-3.4.0-cp313-cp313-macosx_11_0_universal2.whl", hash = "sha256:43748988b097f9c6f09364f260741aa73c80747f63389824435c7a50bfdfd5c1", size = 285856, upload-time = "2026-04-08T15:52:45.82Z" },
     { url = "https://files.pythonhosted.org/packages/9d/c4/3e2df392e5cb199527c4d9dbcaa75c14edcc394b45040f0189f649631e3c/greenlet-3.4.0-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5566e4e2cd7a880e8c27618e3eab20f3494452d12fd5129edef7b2f7aa9a36d1", size = 610208, upload-time = "2026-04-08T16:24:39.674Z" },
     { url = "https://files.pythonhosted.org/packages/da/af/750cdfda1d1bd30a6c28080245be8d0346e669a98fdbae7f4102aa95fff3/greenlet-3.4.0-cp313-cp313-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:1054c5a3c78e2ab599d452f23f7adafef55062a783a8e241d24f3b633ba6ff82", size = 621269, upload-time = "2026-04-08T16:30:59.767Z" },
-    { url = "https://files.pythonhosted.org/packages/e0/93/c8c508d68ba93232784bbc1b5474d92371f2897dfc6bc281b419f2e0d492/greenlet-3.4.0-cp313-cp313-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:98eedd1803353daf1cd9ef23eef23eda5a4d22f99b1f998d273a8b78b70dd47f", size = 628455, upload-time = "2026-04-08T16:40:40.698Z" },
     { url = "https://files.pythonhosted.org/packages/54/78/0cbc693622cd54ebe25207efbb3a0eb07c2639cb8594f6e3aaaa0bb077a8/greenlet-3.4.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:f82cb6cddc27dd81c96b1506f4aa7def15070c3b2a67d4e46fd19016aacce6cf", size = 617549, upload-time = "2026-04-08T15:56:34.893Z" },
-    { url = "https://files.pythonhosted.org/packages/7f/46/cfaaa0ade435a60550fd83d07dfd5c41f873a01da17ede5c4cade0b9bab8/greenlet-3.4.0-cp313-cp313-manylinux_2_39_riscv64.whl", hash = "sha256:b7857e2202aae67bc5725e0c1f6403c20a8ff46094ece015e7d474f5f7020b55", size = 426238, upload-time = "2026-04-08T16:43:06.865Z" },
     { url = "https://files.pythonhosted.org/packages/ba/c0/8966767de01343c1ff47e8b855dc78e7d1a8ed2b7b9c83576a57e289f81d/greenlet-3.4.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:227a46251ecba4ff46ae742bc5ce95c91d5aceb4b02f885487aff269c127a729", size = 1575310, upload-time = "2026-04-08T16:26:21.671Z" },
     { url = "https://files.pythonhosted.org/packages/b8/38/bcdc71ba05e9a5fda87f63ffc2abcd1f15693b659346df994a48c968003d/greenlet-3.4.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:5b99e87be7eba788dd5b75ba1cde5639edffdec5f91fe0d734a249535ec3408c", size = 1640435, upload-time = "2026-04-08T15:57:32.572Z" },
     { url = "https://files.pythonhosted.org/packages/a1/c2/19b664b7173b9e4ef5f77e8cef9f14c20ec7fce7920dc1ccd7afd955d093/greenlet-3.4.0-cp313-cp313-win_amd64.whl", hash = "sha256:849f8bc17acd6295fcb5de8e46d55cc0e52381c56eaf50a2afd258e97bc65940", size = 238760, upload-time = "2026-04-08T17:04:03.878Z" },
@@ -865,9 +857,7 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/78/02/bde66806e8f169cf90b14d02c500c44cdbe02c8e224c9c67bafd1b8cadd1/greenlet-3.4.0-cp314-cp314-macosx_11_0_universal2.whl", hash = "sha256:10a07aca6babdd18c16a3f4f8880acfffc2b88dfe431ad6aa5f5740759d7d75e", size = 286291, upload-time = "2026-04-08T17:09:34.307Z" },
     { url = "https://files.pythonhosted.org/packages/05/1f/39da1c336a87d47c58352fb8a78541ce63d63ae57c5b9dae1fe02801bbc2/greenlet-3.4.0-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:076e21040b3a917d3ce4ad68fb5c3c6b32f1405616c4a57aa83120979649bd3d", size = 656749, upload-time = "2026-04-08T16:24:41.721Z" },
     { url = "https://files.pythonhosted.org/packages/d3/6c/90ee29a4ee27af7aa2e2ec408799eeb69ee3fcc5abcecac6ddd07a5cd0f2/greenlet-3.4.0-cp314-cp314-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e82689eea4a237e530bb5cb41b180ef81fa2160e1f89422a67be7d90da67f615", size = 669084, upload-time = "2026-04-08T16:31:01.372Z" },
-    { url = "https://files.pythonhosted.org/packages/d2/4a/74078d3936712cff6d3c91a930016f476ce4198d84e224fe6d81d3e02880/greenlet-3.4.0-cp314-cp314-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:06c2d3b89e0c62ba50bd7adf491b14f39da9e7e701647cb7b9ff4c99bee04b19", size = 673405, upload-time = "2026-04-08T16:40:42.527Z" },
     { url = "https://files.pythonhosted.org/packages/07/49/d4cad6e5381a50947bb973d2f6cf6592621451b09368b8c20d9b8af49c5b/greenlet-3.4.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4df3b0b2289ec686d3c821a5fee44259c05cfe824dd5e6e12c8e5f5df23085cf", size = 665621, upload-time = "2026-04-08T15:56:35.995Z" },
-    { url = "https://files.pythonhosted.org/packages/79/3e/df8a83ab894751bc31e1106fdfaa80ca9753222f106b04de93faaa55feb7/greenlet-3.4.0-cp314-cp314-manylinux_2_39_riscv64.whl", hash = "sha256:070b8bac2ff3b4d9e0ff36a0d19e42103331d9737e8504747cd1e659f76297bd", size = 471670, upload-time = "2026-04-08T16:43:08.512Z" },
     { url = "https://files.pythonhosted.org/packages/37/31/d1edd54f424761b5d47718822f506b435b6aab2f3f93b465441143ea5119/greenlet-3.4.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:8bff29d586ea415688f4cec96a591fcc3bf762d046a796cdadc1fdb6e7f2d5bf", size = 1622259, upload-time = "2026-04-08T16:26:23.201Z" },
     { url = "https://files.pythonhosted.org/packages/b0/c6/6d3f9cdcb21c4e12a79cb332579f1c6aa1af78eb68059c5a957c7812d95e/greenlet-3.4.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:8a569c2fb840c53c13a2b8967c63621fafbd1a0e015b9c82f408c33d626a2fda", size = 1686916, upload-time = "2026-04-08T15:57:34.282Z" },
     { url = "https://files.pythonhosted.org/packages/63/45/c1ca4a1ad975de4727e52d3ffe641ae23e1d7a8ffaa8ff7a0477e1827b92/greenlet-3.4.0-cp314-cp314-win_amd64.whl", hash = "sha256:207ba5b97ea8b0b60eb43ffcacf26969dd83726095161d676aac03ff913ee50d", size = 239821, upload-time = "2026-04-08T17:03:48.423Z" },
@@ -875,9 +865,7 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d4/8f/18d72b629783f5e8d045a76f5325c1e938e659a9e4da79c7dcd10169a48d/greenlet-3.4.0-cp314-cp314t-macosx_11_0_universal2.whl", hash = "sha256:d70012e51df2dbbccfaf63a40aaf9b40c8bed37c3e3a38751c926301ce538ece", size = 294681, upload-time = "2026-04-08T15:52:35.778Z" },
     { url = "https://files.pythonhosted.org/packages/9e/ad/5fa86ec46769c4153820d58a04062285b3b9e10ba3d461ee257b68dcbf53/greenlet-3.4.0-cp314-cp314t-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a58bec0751f43068cd40cff31bb3ca02ad6000b3a51ca81367af4eb5abc480c8", size = 658899, upload-time = "2026-04-08T16:24:43.32Z" },
     { url = "https://files.pythonhosted.org/packages/43/f0/4e8174ca0e87ae748c409f055a1ba161038c43cc0a5a6f1433a26ac2e5bf/greenlet-3.4.0-cp314-cp314t-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:05fa0803561028f4b2e3b490ee41216a842eaee11aed004cc343a996d9523aa2", size = 665284, upload-time = "2026-04-08T16:31:02.833Z" },
-    { url = "https://files.pythonhosted.org/packages/ef/92/466b0d9afd44b8af623139a3599d651c7564fa4152f25f117e1ee5949ffb/greenlet-3.4.0-cp314-cp314t-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:c4cd56a9eb7a6444edbc19062f7b6fbc8f287c663b946e3171d899693b1c19fa", size = 665872, upload-time = "2026-04-08T16:40:43.912Z" },
     { url = "https://files.pythonhosted.org/packages/19/da/991cf7cd33662e2df92a1274b7eb4d61769294d38a1bba8a45f31364845e/greenlet-3.4.0-cp314-cp314t-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e60d38719cb80b3ab5e85f9f1aed4960acfde09868af6762ccb27b260d68f4ed", size = 661861, upload-time = "2026-04-08T15:56:37.269Z" },
-    { url = "https://files.pythonhosted.org/packages/0d/14/3395a7ef3e260de0325152ddfe19dffb3e49fe10873b94654352b53ad48e/greenlet-3.4.0-cp314-cp314t-manylinux_2_39_riscv64.whl", hash = "sha256:1f85f204c4d54134ae850d401fa435c89cd667d5ce9dc567571776b45941af72", size = 489237, upload-time = "2026-04-08T16:43:09.993Z" },
     { url = "https://files.pythonhosted.org/packages/36/c5/6c2c708e14db3d9caea4b459d8464f58c32047451142fe2cfd90e7458f41/greenlet-3.4.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:7f50c804733b43eded05ae694691c9aa68bca7d0a867d67d4a3f514742a2d53f", size = 1622182, upload-time = "2026-04-08T16:26:24.777Z" },
     { url = "https://files.pythonhosted.org/packages/7a/4c/50c5fed19378e11a29fabab1f6be39ea95358f4a0a07e115a51ca93385d8/greenlet-3.4.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:2d4f0635dc4aa638cda4b2f5a07ae9a2cff9280327b581a3fcb6f317b4fbc38a", size = 1685050, upload-time = "2026-04-08T15:57:36.453Z" },
     { url = "https://files.pythonhosted.org/packages/db/72/85ae954d734703ab48e622c59d4ce35d77ce840c265814af9c078cacc7aa/greenlet-3.4.0-cp314-cp314t-win_amd64.whl", hash = "sha256:1a4a48f24681300c640f143ba7c404270e1ebbbcf34331d7104a4ff40f8ea705", size = 245554, upload-time = "2026-04-08T17:03:50.044Z" },

From 3cfeed2292b08f7447f2907dd2b12ff6c568cd1c Mon Sep 17 00:00:00 2001
From: jbmendonca <jbmendonca@users.noreply.github.com>
Date: Mon, 27 Apr 2026 15:13:17 -0400
Subject: [PATCH 06/12] feat: merge v0.33.0 upstream with TKR security
 hardening and failover routing

- Base: upstream main (v0.33.0) with all official updates
- Added: TKR security headers (X-Content-Type-Options, X-Frame-Options, Referrer-Policy)
- Added: CORS CSRF token support (X-CSRF-Token headers)
- Added: Provider failover chain (getProviderCandidates, resolveProviderChain)
- Added: Platform observability, cache, queue, and metrics modules
- Added: Runtime config, structured logging, request/session security
- Added: Frontend: CommandPalette, ThemeContext, Observability page, SecurityTab
- Preserved: upstream OpenRouter Smart Router native integration
- Adapted: Provider-config.js enhanced with routing and default_model support
---
 .github/workflows/ci.yml                      |    4 +-
 .pre-commit-config.yaml                       |   23 +
 ROADMAP.md                                    |  283 +++--
 config/plugin-registry.json                   |   40 +
 dashboard/backend/app.py                      |   52 +-
 dashboard/backend/blueprint_registry.py       |   62 +
 dashboard/backend/db_compat.py                |  195 ++++
 dashboard/backend/db_migrations.py            |   48 +
 dashboard/backend/migrations/alembic.ini      |    3 +
 dashboard/backend/migrations/env.py           |   50 +
 .../versions/0001_bootstrap_schema.py         |   24 +
 dashboard/backend/platform_cache.py           |  135 +++
 dashboard/backend/platform_metrics.py         |   87 ++
 dashboard/backend/platform_observability.py   |   90 ++
 dashboard/backend/platform_plugins.py         |  193 ++++
 dashboard/backend/platform_queue.py           |   62 +
 dashboard/backend/platform_support.py         |   75 ++
 dashboard/backend/request_security.py         |   41 +
 dashboard/backend/routes/platform.py          |  135 +++
 dashboard/backend/runtime_config.py           |  122 ++
 dashboard/backend/schema_migrations.py        |  291 +++++
 dashboard/backend/session_security.py         |   82 ++
 dashboard/backend/structured_logging.py       |   60 +
 dashboard/backend/totp_security.py            |   78 ++
 dashboard/frontend/playwright.config.ts       |   26 +
 .../frontend/public/manifest.webmanifest      |   29 +
 dashboard/frontend/public/sw.js               |   65 ++
 .../frontend/scripts/start-e2e-server.mjs     |   48 +
 .../src/components/CommandPalette.tsx         |  341 ++++++
 .../src/components/agent-chat/ChatBlocks.tsx  |  303 +++++
 .../frontend/src/context/ThemeContext.tsx     |   52 +
 dashboard/frontend/src/lib/navigation.ts      |  136 +++
 dashboard/frontend/src/lib/pwa.ts             |   18 +
 dashboard/frontend/src/lib/theme.ts           |   44 +
 .../frontend/src/pages/Observability.tsx      |  243 ++++
 .../src/pages/SettingsSecurityTab.tsx         |  257 +++++
 .../integrations/CustomIntegrationModal.tsx   |  300 +++++
 .../src/pages/integrations/DatabasesTab.tsx   |  552 +++++++++
 .../pages/integrations/IntegrationCard.tsx    |  150 +++
 .../pages/integrations/SocialAccountsTab.tsx  |  118 ++
 .../frontend/src/pages/integrations/types.ts  |  226 ++++
 .../frontend/test-results/.last-run.json      |    4 +
 .../frontend/tests/e2e/setup-login.spec.ts    |   37 +
 .../terminal-server/src/claude-bridge.js      |   12 +-
 dashboard/terminal-server/src/http-routes.js  |  276 +++++
 .../src/platform-event-broker.js              |  100 ++
 .../terminal-server/src/platform-metrics.js   |   31 +
 .../terminal-server/src/platform-support.js   |   41 +
 .../terminal-server/src/provider-config.js    |  167 ++-
 .../terminal-server/src/runtime-config.js     |   41 +
 .../src/terminal-server-runtime.js            | 1025 +++++++++++++++++
 .../src/utils/structured-logger.js            |   77 ++
 .../src/utils/terminal-audit-log.js           |   32 +
 .../test/platform-event-broker.test.js        |   44 +
 .../test/provider-config.test.js              |   85 ++
 .../test/runtime-config.test.js               |   50 +
 tests/backend/test_auth_security.py           |   66 +-
 tests/backend/test_health_routes.py           |   88 +-
 tests/backend/test_provider_routing.py        |   31 +
 tests/backend/test_runtime_config.py          |   90 ++
 60 files changed, 7254 insertions(+), 186 deletions(-)
 create mode 100644 .pre-commit-config.yaml
 create mode 100644 config/plugin-registry.json
 create mode 100644 dashboard/backend/blueprint_registry.py
 create mode 100644 dashboard/backend/db_compat.py
 create mode 100644 dashboard/backend/db_migrations.py
 create mode 100644 dashboard/backend/migrations/alembic.ini
 create mode 100644 dashboard/backend/migrations/env.py
 create mode 100644 dashboard/backend/migrations/versions/0001_bootstrap_schema.py
 create mode 100644 dashboard/backend/platform_cache.py
 create mode 100644 dashboard/backend/platform_metrics.py
 create mode 100644 dashboard/backend/platform_observability.py
 create mode 100644 dashboard/backend/platform_plugins.py
 create mode 100644 dashboard/backend/platform_queue.py
 create mode 100644 dashboard/backend/platform_support.py
 create mode 100644 dashboard/backend/request_security.py
 create mode 100644 dashboard/backend/routes/platform.py
 create mode 100644 dashboard/backend/runtime_config.py
 create mode 100644 dashboard/backend/schema_migrations.py
 create mode 100644 dashboard/backend/session_security.py
 create mode 100644 dashboard/backend/structured_logging.py
 create mode 100644 dashboard/backend/totp_security.py
 create mode 100644 dashboard/frontend/playwright.config.ts
 create mode 100644 dashboard/frontend/public/manifest.webmanifest
 create mode 100644 dashboard/frontend/public/sw.js
 create mode 100644 dashboard/frontend/scripts/start-e2e-server.mjs
 create mode 100644 dashboard/frontend/src/components/CommandPalette.tsx
 create mode 100644 dashboard/frontend/src/components/agent-chat/ChatBlocks.tsx
 create mode 100644 dashboard/frontend/src/context/ThemeContext.tsx
 create mode 100644 dashboard/frontend/src/lib/navigation.ts
 create mode 100644 dashboard/frontend/src/lib/pwa.ts
 create mode 100644 dashboard/frontend/src/lib/theme.ts
 create mode 100644 dashboard/frontend/src/pages/Observability.tsx
 create mode 100644 dashboard/frontend/src/pages/SettingsSecurityTab.tsx
 create mode 100644 dashboard/frontend/src/pages/integrations/CustomIntegrationModal.tsx
 create mode 100644 dashboard/frontend/src/pages/integrations/DatabasesTab.tsx
 create mode 100644 dashboard/frontend/src/pages/integrations/IntegrationCard.tsx
 create mode 100644 dashboard/frontend/src/pages/integrations/SocialAccountsTab.tsx
 create mode 100644 dashboard/frontend/src/pages/integrations/types.ts
 create mode 100644 dashboard/frontend/test-results/.last-run.json
 create mode 100644 dashboard/frontend/tests/e2e/setup-login.spec.ts
 create mode 100644 dashboard/terminal-server/src/http-routes.js
 create mode 100644 dashboard/terminal-server/src/platform-event-broker.js
 create mode 100644 dashboard/terminal-server/src/platform-metrics.js
 create mode 100644 dashboard/terminal-server/src/platform-support.js
 create mode 100644 dashboard/terminal-server/src/runtime-config.js
 create mode 100644 dashboard/terminal-server/src/terminal-server-runtime.js
 create mode 100644 dashboard/terminal-server/src/utils/structured-logger.js
 create mode 100644 dashboard/terminal-server/src/utils/terminal-audit-log.js
 create mode 100644 dashboard/terminal-server/test/platform-event-broker.test.js
 create mode 100644 dashboard/terminal-server/test/provider-config.test.js
 create mode 100644 dashboard/terminal-server/test/runtime-config.test.js
 create mode 100644 tests/backend/test_provider_routing.py
 create mode 100644 tests/backend/test_runtime_config.py

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ea50f213..660a47ad 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -2,7 +2,7 @@ name: CI
 
 on:
   pull_request:
-    branches: [develop, main]
+    branches: [main]
     paths:
       - "dashboard/**"
       - "tests/**"
@@ -10,7 +10,7 @@ on:
       - "uv.lock"
       - ".github/workflows/ci.yml"
   push:
-    branches: [develop, main]
+    branches: [main]
     paths:
       - "dashboard/**"
       - "tests/**"
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
new file mode 100644
index 00000000..50cde338
--- /dev/null
+++ b/.pre-commit-config.yaml
@@ -0,0 +1,23 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.11
+    hooks:
+      - id: ruff-check
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v3.1.0
+    hooks:
+      - id: prettier
+        files: ^dashboard/frontend/.*\.(ts|tsx|js|jsx|json|css|md|html|yaml|yml)$
+
+  - repo: local
+    hooks:
+      - id: frontend-typecheck
+        name: frontend type-check
+        entry: npm --prefix dashboard/frontend run build
+        language: system
+        files: ^dashboard/frontend/
+        pass_filenames: false
+        always_run: true
diff --git a/ROADMAP.md b/ROADMAP.md
index df015adf..381c7550 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -1,135 +1,254 @@
 # EvoNexus Roadmap
 
-> Unofficial toolkit for Claude Code — AI-powered business operating system.
->
-> This roadmap is updated regularly. Want to vote or suggest? [Open a discussion](https://github.com/EvolutionAPI/evo-nexus/discussions) or [create an issue](https://github.com/EvolutionAPI/evo-nexus/issues).
+> Execution roadmap derived from the PRD review and current branch state.
+> Last updated: 2026-04-24
 
 ---
 
-## Legend
+## How To Read This
 
-| Symbol | Meaning |
-|--------|---------|
-| `[ ]` | Not started |
-| `[x]` | Done |
-| `⚠️` | Breaking change |
-| `🔥` | High priority |
-| `💡` | Needs design discussion first |
+- `Done` means implemented and validated locally.
+- `Partial` means a scaffold or mitigation exists, but the item is not closed.
+- `Next` means highest priority pending work.
+- `Later` means important work that is gated by dependencies.
 
 ---
 
-## v0.4 — Foundation & Stability
+## Project Snapshot
 
-> Fix, secure, and improve what already exists before growing.
+- Delivered: the security hardening pass, backend maintainability work, frontend scaling work, and the phase 4 platform layer are in place.
+- Open: env normalization edge cases in the last offline tooling paths.
+- Focus now: close the remaining partial items before adding new feature surface area.
 
-### Skills
+---
 
-- [x] 🔥 **Evolution product skills** — `int-evolution-api` (33 commands), `int-evolution-go` (24 commands), `int-evo-crm` (48 commands) for managing instances, messages, contacts, conversations, pipelines via REST API.
-- [x] **Version indicator & update alerts** — show current version in dashboard sidebar, alert when new GitHub releases are available.
+## Current Baseline
 
-### Developer Experience
+| Area | Status | Notes |
+|---|---|---|
+| Security | Done | Login hardening, password policy, configurable CORS, env-first secret key handling, CSRF token plumbing, session token rotation, and 2FA/TOTP are in place. |
+| Reliability | Done | Session GC, heartbeat timeout handling, health endpoints, backup hooks, restart supervision, and readiness/liveness probe split are in place. |
+| Architecture | Partial | Alembic bootstrap, lazy blueprint loading, structured logs, terminal-server modularization, and restart supervision are in place. Remaining work: the last env normalization edge cases. |
+| Frontend | Done | Route splitting, section-level error boundaries, theme toggle, PWA support, command palette, and mobile chat improvements are done. |
+| Testing / CI | Done | Auth tests, terminal-server tests, CI, pre-commit hooks, and Playwright E2E coverage exist. |
+| Platform | Done | Queue/cache abstractions, provider failover, observability, plugins, a shared platform broker, and PostgreSQL rollout wiring are in place. |
 
-- [x] 🔥 **CLI installer** — `npx @evoapi/evo-nexus` — clones repo, installs deps, runs interactive setup wizard.
-- [x] **Full Docker install** — `docker compose up dashboard` with multi-stage Dockerfile + GitHub Actions CI pushing to GHCR.
-- [x] **Update checker** — dashboard checks GitHub releases and shows upgrade notification.
-- [x] **settings.json** — project-level permissions (allow/deny), hooks configuration, thinking mode enabled.
-- [x] **CLAUDE.md split** — reduced from 263 to 128 lines. Detailed config moved to `.claude/rules/` (agents, integrations, routines, skills).
-- [x] **Inner-loop commands** — `/status` (workspace status) and `/review` (recent changes + next actions).
+---
 
-### Dashboard UX
+## Shipped So Far
+
+- Rate limiting on login
+- Strong password policy
+- Configurable CORS
+- Env-first secret key handling
+- Runtime config aliases for `DATABASE_URL` and `PORT`
+- CSRF token plumbing for mutating requests
+- Per-session token rotation and CSRF refresh on auth changes
+- TOTP / 2FA enrollment, login, and disable flows for admins
+- Readiness / liveness health endpoints
+- Pre-commit hooks for backend lint, frontend format, and frontend type-check
+- Pre-migration backup hook for SQLite
+- Alembic-backed schema bootstrap
+- Session GC in the terminal server
+- Heartbeat, summary, and goal workers now follow the shared DB resolver
+- WebSocket heartbeat timeout handling
+- Terminal-server audit log
+- Structured JSON logs for backend and terminal server
+- Health and deep-health endpoints
+- Healthcheck wiring in compose / swarm
+- Session save debounce in the terminal server
+- Lazy blueprint loading
+- Terminal-server restart supervision
+- Terminal-server runtime split into a wrapper plus dedicated runtime module
+- Shared platform event broker between Flask and terminal-server
+- Hot-path cache invalidation on platform events
+- Frontend route splitting
+- Section-level error boundaries
+- Global theme toggle
+- Command palette with Ctrl+K
+- PWA manifest and service worker
+- Mobile chat layout improvements
+- AgentChat transcript shell extraction
+- AgentChat block extraction into focused components
+- Integrations page decomposition into focused modules
+- Shared `PageSkeleton` loading states across major pages
+- Provider failover routing and preflight selection
+- Observability dashboard
+- Plugin registry and install / uninstall flow
+- PostgreSQL-ready runtime and DB adapters
+- Compose and Swarm PostgreSQL rollout wiring
+- CI workflow for backend, terminal server, and frontend build
+- Playwright E2E coverage for setup, login, and protected-route navigation
 
-- [x] **Sidebar reorganization** — 5 collapsible groups (Main, Operations, Data, System, Admin) with localStorage persistence.
-- [x] **Active agent visualization** — Claude Code hooks track agent launches via `PreToolUse` events, writing to `agent-status.json`. Dashboard polls `/api/agents/active` and shows "RUNNING" badges with pulse animation on agent cards and overview.
-- [x] **Agents page redesign** — unique icons and accent colors per agent, status dots, slash command badges, memory count pills, hover glow effects.
-- [x] **Overview page redesign** — stat cards with icons and trend indicators, active agents bar, quick actions row, improved reports and routines tables.
+---
 
-### Agent Generalization
+## Delivery Roadmap
 
-- [x] **Agent prompts generalized** — all 9 agent prompts cleaned of hardcoded personal references. User-specific context preserved in `_improvements.md` per agent memory folder.
+### Phase 1 - Close Remaining Risk
 
----
+Goal: make the current stack safe enough for sensitive data and stable deployments.
+
+| Item | Priority | Status | Exit Criterion |
+|---|---|---|---|
+| D6 Backup before migrations | P0 | Done | Automatic backup runs before any schema change. |
+| S4 CSRF tokens for mutations | P1 | Done | Mutating requests now require the XHR header plus a per-session CSRF token. |
+| S5 Audit log for terminal server | P1 | Done | Sensitive actions are recorded with actor, timestamp, and target. |
+| P5 WebSocket heartbeat timeout | P1 | Done | Dead connections are detected and closed automatically. |
+| T2 Terminal-server integration tests | P1 | Done | WebSocket session lifecycle is covered by automated tests. |
+| D1 / D2 Health checks and probes | P1 | Done | Separate readiness and liveness endpoints are exposed and the deploy healthchecks use the live probe. |
+
+Exit criterion: no remaining P0 security gaps, and unhealthy processes are detected automatically.
+
+### Phase 2 - Backend Maintainability
+
+Goal: reduce startup coupling and make migrations and runtime behavior explicit.
 
-## v0.5 — Extensibility & Ecosystem
+| Item | Priority | Status | Exit Criterion |
+|---|---|---|---|
+| A1 Alembic extraction | P1 | Done | Schema changes are versioned and reversible. |
+| A2 Split `server.js` | P2 | Done | `server.js` now delegates to a dedicated runtime module and platform event broker. |
+| D3 Structured logs | P2 | Done | Logs are JSON and searchable across services. |
+| D4 Env-based config | P1 | Partial | Most runtime config is env-driven; `DATABASE_URL` and `PORT` aliases are supported, and the heartbeat, summary, and goal workers now follow the shared DB resolver, but a few offline tools still keep local-path fallbacks. |
+| D5 Isolated process restart | P1 | Done | Terminal-server failure no longer brings down the dashboard. |
+| P3 Debounce `saveSessionsToDisk` | P2 | Done | Disk writes are batched and bounded. |
+| P4 Lazy blueprint loading | P2 | Done | Backend startup avoids eager loading every route. |
 
-> Make EvoNexus composable and self-extending.
+Exit criterion: backend startup is faster, migrations are explicit, and service boundaries are clearer.
 
-### Agent System
+### Phase 3 - Frontend Scale And UX
 
-- [x] 🔥 **Generalize existing agents** — all 9 agent prompts generalized. User-specific context preserved in `_improvements.md` per agent memory folder. Adapter patterns documented as future work.
-- [x] 🔥 **New business agents** — expand functional coverage:
-  - [x] **Marketing Agent** — orchestrate existing `mkt-*` skills, attribution, budget, full funnel
-  - [x] **HR / People Agent** — onboarding, 1:1s, performance reviews, hiring pipeline
-  - [x] **Customer Success Agent** — health score, churn prediction, NPS/CSAT, client onboarding
-  - [x] **Legal / Compliance Agent** — contracts, renewals, GDPR/LGPD, compliance checklists
-  - [x] **Product Agent** — discovery, feature prioritization (RICE/ICE), PLG metrics, feedback loop
-  - [x] **Data / BI Agent** — cross-area consolidated dashboard, unified KPIs, alerts, trend analysis
-- [x] **Custom agents** — `custom-` prefix, gitignored, auto-discovered by dashboard (core/custom badges), `create-agent` skill, `create-command` skill
-- [x] **Help agent (Oracle)** — `/oracle` answers questions about the workspace by reading the actual docs. No RAG needed — reads `docs/llms-full.txt` and source files directly
+Goal: keep the dashboard maintainable as pages and workflows grow.
 
-### Routines & Scheduling
+| Item | Priority | Status | Exit Criterion |
+|---|---|---|---|
+| U1 Decompose `AgentChat.tsx` | P2 | Done | Core chat blocks and the transcript shell are split into focused components. |
+| U2 Decompose `Integrations.tsx` | P2 | Done | Provider-specific logic, social accounts, and database flows are split into focused modules. |
+| U3 Theme toggle | P3 | Done | Light and dark preference is user-controlled. |
+| U4 PWA support | P3 | Done | Dashboard has a manifest and service worker. |
+| U5 Skeleton states everywhere | P2 | Done | Every major page now uses the shared `PageSkeleton` loading surface. |
+| U7 Command palette | P3 | Done | Keyboard-driven navigation is available. |
+| 4.4 Mobile responsive chat | P2 | Done | Chat works on narrow screens without layout breakage. |
 
-- [x] 🔥 **Trigger registry** — define and manage named triggers (webhook, cron, event-based) that invoke skills or routines
-- [x] **Non-recurrent scheduled actions** — one-off scheduled tasks (e.g., "post this on LinkedIn Friday at 10am") without creating a full routine
-- [x] **Systematic routines** — pure Python routines via `run_script()` — no AI, no tokens, no cost. `create-routine` skill generates the code
+Exit criterion: the dashboard can absorb new pages without becoming a monolith.
 
-### Integrations
+### Phase 4 - Platform Expansion
 
-- [ ] **Complete Obsidian integration** — finish `obs-*` skills: bidirectional sync, canvas, bases, CLI
+Goal: unlock multi-provider, observability, and enterprise deployment paths.
 
-### Import / Export
+| Item | Priority | Status | Exit Criterion |
+|---|---|---|---|
+| A3 Message queue | P2 | Done | Queue events now flow through a shared broker between Flask and terminal server. |
+| A4 Redis cache | P3 | Done | Provider, observability, and queue hot paths now use cache-backed reads with event-driven invalidation. |
+| A5 PostgreSQL option | P2 | Done | Compose and Swarm now wire `DATABASE_URL` to a PostgreSQL service. |
+| 4.1 Native provider failover | P2 | Done | Routing is configurable and the terminal server now preflights and falls back through ready providers. |
+| 4.2 Observability dashboard | P2 | Done | Tokens, latency, queue, cache, and plugin state are visible in one place. |
+| 4.3 Plugin system | P2 | Done | Third-party agent packs can be registered, installed, and removed safely. |
+| 4.5 PostgreSQL backend | P2 | Done | DB adapter and migrations work across SQLite and PostgreSQL. |
 
-- [x] **Backup system** — export workspace state as ZIP (agents, skills, routines, memory, config); import to restore. Support local, git, and cloud bucket targets.
+Exit criterion: the platform can scale across load, providers, and deployment models.
 
 ---
 
-## v0.12 — Engineering Layer
+## Priority Backlog
+
+### Security
+
+- No open Phase 1 security items remain.
+
+### Reliability
+
+- No open Phase 1 reliability items remain.
+
+### Architecture
+
+- D4 Config normalization
+
+### Testing / CI
 
-> Add a complete software development team alongside the business agents.
 
-### Engineering Layer (delivered)
+No open Testing / CI items remain.
 
-- [x] 🔥 **19 engineering agents** — complete dev team derived from [oh-my-claudecode](https://github.com/yeachan-heo/oh-my-claudecode) (MIT, Yeachan Heo). Reasoning tier (opus): apex-architect, echo-analyst, compass-planner, raven-critic, lens-reviewer, zen-simplifier, vault-security. Execution tier (sonnet): bolt-executor, hawk-debugger, grid-tester, probe-qa, oath-verifier, trail-tracer, flow-git, scroll-docs, canvas-designer, prism-scientist. Speed tier (haiku): scout-explorer, quill-writer.
-- [x] 🔥 **25 `dev-*` skills** — Tier 1 orchestration (15): `dev-autopilot`, `dev-plan`, `dev-ralplan`, `dev-deep-interview`, `dev-deep-dive`, `dev-external-context`, `dev-trace`, `dev-verify`, `dev-ultraqa`, `dev-visual-verdict`, `dev-ai-slop-cleaner`, `dev-sciomc`, `dev-team`, `dev-ccg`, `dev-ralph`. Tier 2 setup (5): `dev-mcp-setup`, `dev-deepinit`, `dev-project-session-manager`, `dev-configure-notifications`, `dev-release`. Tier 3 utilities (5): `dev-cancel`, `dev-remember`, `dev-ask`, `dev-learner`, `dev-skillify`.
-- [x] **15 dev templates** — `.claude/templates/dev-*.md` for each agent's primary output (architecture-decision, work-plan, code-review, bug-report, verification-report, deep-interview-spec, security-audit, test-strategy, trace-report, explore-report, design-spec, analysis-report, research-brief, critique, simplification-report).
-- [x] **`workspace/development/` folder** — 7 subfolders (architecture, plans, specs, reviews, debug, verifications, research) for engineering layer artifacts. Distinct from `workspace/projects/` (active git repos).
-- [x] **Two-layer architecture documented** — `.claude/rules/agents.md`, `CLAUDE.md`, `docs/agents/overview.md`, `docs/agents/engineering-layer.md`, `docs/architecture.md`, `docs/introduction.md`, site `Home.tsx`.
-- [x] **Open source attribution** — `NOTICE.md` at repo root with full MIT license, version pinned (v4.11.4), modifications listed. Credits in `README.md`.
-- [x] **Pattern compliance** — all 19 engineering agents follow the EvoNexus standard: rich frontmatter (Examples + commentary), Workspace Context, Shared Knowledge Base, Working Folder, Identity, Anti-patterns, Domain, How You Work, Skills You Can Use, Handoffs, Output Format, Continuity. Verified by `@lens-reviewer` (3 fixes applied: oath-verifier disallowedTools, raven-critic and trail-tracer Skills section).
+### Frontend / UX
 
-### Cross-layer pipelines (now possible)
+- No open Phase 3 frontend items remain.
 
-- [x] **End-to-end implementation** — `dev-autopilot` orchestrates spec → plan → code → QA → validation across multiple engineering agents.
-- [x] **High-stakes consensus planning** — `dev-ralplan` runs Planner/Architect/Critic consensus loop with RALPLAN-DR structured deliberation.
-- [x] **Bug investigation** — `@trail-tracer` (multi-hypothesis) → `@hawk-debugger` (root cause + minimal fix) → `@oath-verifier` (regression check).
-- [x] **Pre-merge gate** — `@lens-reviewer` (code quality) → `@vault-security` (OWASP audit) → `dev-ultraqa` (build/test/fix loop) → `@oath-verifier` (acceptance criteria).
+### Platform Expansion
+
+- No open Platform Expansion items remain.
 
 ---
 
-## v1.0 — Community & Growth
+## Sprint Execution Plan
+
+Priority inside each sprint runs top to bottom. The `Depends On` column lists hard blockers only; the sprint order itself also reflects risk reduction and release sequencing.
+
+Implementation status: Sprint 1 is complete, Sprint 2 is partially complete, Sprint 3 is complete, and Sprint 4 is complete.
+
+### Sprint 1 - Security And Deploy Gates
+
+Goal: close the items that reduce blast radius and make production checks reliable.
+
+| Item | Priority | Depends On | Why It Is Here |
+|---|---|---|---|
+| S4 CSRF tokens for mutations | P1 | None | Must land before any new write-heavy surface area expands. |
+| D1 / D2 health checks and probes | P1 | None | Separate readiness and liveness before more rollout work. |
+| S6 session key rotation | P2 | None | Completes the auth hardening pass while the auth path is already being touched. |
+
+### Sprint 2 - Config And Auth Hardening
 
-> Community adoption, discoverability, and self-sustaining ecosystem.
+Goal: normalize runtime configuration and finish the remaining auth hardening.
 
-### Community & Docs
+| Item | Priority | Depends On | Why It Is Here |
+|---|---|---|---|
+| D4 config normalization | P1 | None | Remove the last hardcoded runtime assumptions before deeper refactors. |
+| S7 2FA / TOTP for admins | P2 | S4 + S6 | Builds on the hardened login and session flow. |
+| A2 `server.js` modularization | P2 | D4 | Refactor after the config surface is stable. |
+| T5 pre-commit hooks | P2 | Done | Lint, format, and frontend type-check gates run before commits. |
 
-- [x] 🔥 **Public roadmap** — this file. Community input welcome via [discussions](https://github.com/EvolutionAPI/evo-nexus/discussions).
-- [x] **Telegram & Discord channels** — activate community channels, document in README and docs site.
-- [ ] **In-app tutorials** — contextual tutorials surfaced inside the dashboard, not just external docs.
-- [x] **Resume Claude sessions in chat** — list active/resumable Claude sessions in dashboard chat with `--resume` support.
+### Sprint 3 - Verification And Scale Prep
 
-### Development
+Goal: prove the stable flows end to end and prepare the platform layer for scale.
 
-- [ ] **Testing framework** — define and implement test strategy for skills, routines, and agent behaviors; prevent regressions.
+| Item | Priority | Depends On | Why It Is Here |
+|---|---|---|---|
+| T3 Playwright E2E | P2 | Done | Validates the core user journeys after the config and auth work settle. |
+| A3 Message queue | P2 | Done | Async coordination is now handled by the shared platform broker. |
+| A4 Redis cache | P3 | Done | Hot-path caching is now active with invalidation on platform events. |
+
+### Sprint 4 - Production Rollout
+
+Goal: finish the remaining deployment wiring for PostgreSQL-backed production use.
+
+| Item | Priority | Depends On | Why It Is Here |
+|---|---|---|---|
+| A5 PostgreSQL option | P2 | Done | PostgreSQL rollout wiring is now present in both Compose and the Swarm stack. |
 
 ---
 
-## Contributing
+## Dependency Rules
 
-Want to help? Pick any `[ ]` item and:
+- S4 should land before any new write-heavy surfaces.
+- P5 should land before more WebSocket features are built.
+- 4.1 should reuse the current Smart Router instead of duplicating provider loading logic.
+- D4 remains the only partially open configuration cleanup item.
 
-1. Check [open issues](https://github.com/EvolutionAPI/evo-nexus/issues)
-2. Read [CONTRIBUTING.md](CONTRIBUTING.md)
-3. For `💡` items, open a [discussion](https://github.com/EvolutionAPI/evo-nexus/discussions) first — design is still open
+---
+
+## Success Metrics
+
+| Metric | Target |
+|---|---|
+| First Contentful Paint | < 1.5s |
+| Bundle size gzipped | < 400KB |
+| Auth coverage | >= 80% |
+| Terminal server WebSocket coverage | >= 70% |
+| Login brute-force attempts | Bounded by lockout policy |
+| Session GC lag | <= 24h idle |
+| Backend startup time | < 2s |
 
 ---
 
-*Last updated: 2026-04-10 — [Evolution Foundation](https://evolutionfoundation.com.br)*
+## Notes
+
+- This file replaces the old v0.4-v1.0 milestone list.
+- The next concrete delivery gate is D4 cleanup, which should be treated as the current execution queue.
diff --git a/config/plugin-registry.json b/config/plugin-registry.json
new file mode 100644
index 00000000..9a9390b4
--- /dev/null
+++ b/config/plugin-registry.json
@@ -0,0 +1,40 @@
+{
+  "plugins": [
+    {
+      "id": "observability-scout",
+      "name": "Observability Scout",
+      "version": "1.0.0",
+      "category": "observability",
+      "description": "Installs a read-only agent pack for platform telemetry and incident triage.",
+      "agents": [
+        {
+          "name": "observability-scout",
+          "description": "Read-only observability analyst for EvoNexus. Uses metrics, health, costs, and provider routing data to identify regressions.",
+          "model": "haiku",
+          "color": "cyan",
+          "memory": "project",
+          "disallowedTools": ["Write", "Edit", "Bash", "NotebookEdit"],
+          "prompt": "You are Observability Scout.\nAnalyze EvoNexus platform health, provider routing, queue/cache status, and cost trends.\nRecommend concrete fixes with clear severity. Do not edit files."
+        }
+      ]
+    },
+    {
+      "id": "provider-router",
+      "name": "Provider Router",
+      "version": "1.0.0",
+      "category": "platform",
+      "description": "Installs a read-only agent pack for provider failover and routing audits.",
+      "agents": [
+        {
+          "name": "provider-router",
+          "description": "Read-only provider routing specialist for EvoNexus. Reviews failover order, provider health, and selected model mode.",
+          "model": "haiku",
+          "color": "violet",
+          "memory": "project",
+          "disallowedTools": ["Write", "Edit", "Bash", "NotebookEdit"],
+          "prompt": "You are Provider Router.\nAudit provider health, failover order, and model compatibility.\nRecommend a safe routing chain and explain why a fallback should or should not be activated."
+        }
+      ]
+    }
+  ]
+}
diff --git a/dashboard/backend/app.py b/dashboard/backend/app.py
index 2dccb597..bfb192d0 100644
--- a/dashboard/backend/app.py
+++ b/dashboard/backend/app.py
@@ -8,10 +8,29 @@
 from datetime import timedelta
 
 from dotenv import load_dotenv
-from flask import Flask, send_from_directory, request, jsonify
+from flask import Flask, send_from_directory, request, jsonify, abort
 from flask_cors import CORS
 from flask_login import LoginManager, current_user, login_user
 
+# TKR Security Hardening imports
+try:
+    from runtime_config import load_dashboard_runtime_config
+    _runtime_config = load_dashboard_runtime_config
+except ImportError:
+    _runtime_config = None
+try:
+    from structured_logging import install_request_logging
+except ImportError:
+    install_request_logging = None
+try:
+    from request_security import require_xhr
+except ImportError:
+    require_xhr = None
+try:
+    from session_security import attach_session_token
+except ImportError:
+    attach_session_token = None
+
 # Workspace root: two levels up from backend/
 WORKSPACE = Path(__file__).resolve().parent.parent.parent
 
@@ -91,7 +110,13 @@ def _cors_allowed_origins():
     # Flask <2.2 exposed this through app.config; keep compatibility.
     app.config["JSON_AS_ASCII"] = False
 
-CORS(app, origins=_cors_allowed_origins(), supports_credentials=True)
+CORS(
+    app,
+    origins=_cors_allowed_origins(),
+    supports_credentials=True,
+    allow_headers=["Content-Type", "X-Requested-With", "X-CSRF-Token", "Authorization"],
+    expose_headers=["X-CSRF-Token"],
+)
 
 # --------------- Database ---------------
 from models import db, User, BrainRepoConfig, needs_setup, seed_roles, seed_systems
@@ -743,6 +768,7 @@ def unauthorized():
     "/api/auth/login",
     "/api/auth/needs-setup",
     "/api/auth/setup",
+    "/api/auth/csrf",
     "/api/health",
     "/api/auth/needs-onboarding",
     "/api/config/workspace-status",
@@ -815,6 +841,21 @@ def auth_middleware():
     if not current_user.is_authenticated:
         return jsonify({"error": "Authentication required"}), 401
 
+# --------------- TKR Security Headers ---------------
+@app.after_request
+def attach_security_headers(response):
+    """Attach security-related headers to every response."""
+    response.headers.setdefault("X-Content-Type-Options", "nosniff")
+    response.headers.setdefault("X-Frame-Options", "DENY")
+    response.headers.setdefault("Referrer-Policy", "strict-origin-when-cross-origin")
+    # Attach session token if module available
+    if attach_session_token is not None:
+        try:
+            attach_session_token(response)
+        except Exception:
+            pass
+    return response
+
 # --------------- Register blueprints ---------------
 from routes.overview import bp as overview_bp
 from routes.workspace import bp as workspace_bp
@@ -923,6 +964,13 @@ def auth_middleware():
 app.register_blueprint(plugins_bp)
 app.register_blueprint(mcp_servers_bp)
 
+# TKR Platform routes (observability, cache, queue)
+try:
+    from routes.platform import bp as platform_bp
+    app.register_blueprint(platform_bp)
+except ImportError:
+    pass  # Platform module not available
+
 # --------------- Social Auth blueprints ---------------
 from auth.youtube import bp as youtube_auth_bp
 from auth.instagram import bp as instagram_auth_bp
diff --git a/dashboard/backend/blueprint_registry.py b/dashboard/backend/blueprint_registry.py
new file mode 100644
index 00000000..2ed22c83
--- /dev/null
+++ b/dashboard/backend/blueprint_registry.py
@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from importlib import import_module
+
+
+BLUEPRINT_MODULES = [
+    "routes.overview",
+    "routes.workspace",
+    "routes.agents",
+    "routes.routines",
+    "routes.skills",
+    "routes.templates_routes",
+    "routes.memory",
+    "routes.costs",
+    "routes.config",
+    "routes.integrations",
+    "routes.scheduler",
+    "routes.services",
+    "routes.auth_routes",
+    "routes.systems",
+    "routes.docs",
+    "routes.mempalace",
+    "routes.tasks",
+    "routes.triggers",
+    "routes.backups",
+    "routes.providers",
+    "routes.settings",
+    "routes.shares",
+    "routes.heartbeats",
+    "routes.goals",
+    "routes.tickets",
+    "routes.platform",
+    "routes.health",
+    "routes.knowledge",
+    "routes.knowledge_public",
+    "routes.knowledge_proxy",
+    "routes.knowledge_v1",
+    "routes.databases",
+]
+
+SOCIAL_BLUEPRINT_MODULES = [
+    "auth.youtube",
+    "auth.instagram",
+    "auth.linkedin",
+    "auth.twitter",
+    "auth.tiktok",
+    "auth.twitch",
+]
+
+
+def _register_modules(app, module_names):
+    for module_name in module_names:
+        module = import_module(module_name)
+        blueprint = getattr(module, "bp", None)
+        if blueprint is None:
+            raise RuntimeError(f"Blueprint module {module_name} does not expose bp")
+        app.register_blueprint(blueprint)
+
+
+def register_blueprints(app) -> None:
+    _register_modules(app, BLUEPRINT_MODULES)
+    _register_modules(app, SOCIAL_BLUEPRINT_MODULES)
diff --git a/dashboard/backend/db_compat.py b/dashboard/backend/db_compat.py
new file mode 100644
index 00000000..414edd23
--- /dev/null
+++ b/dashboard/backend/db_compat.py
@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Iterable
+
+from sqlalchemy import create_engine, text
+
+from runtime_config import database_backend, database_uri, sqlite_path_from_uri
+
+
+@dataclass
+class CompatRow:
+    keys_list: list[str]
+    values_list: list[Any]
+
+    def __getitem__(self, item: int | str) -> Any:
+        if isinstance(item, int):
+            return self.values_list[item]
+        idx = self.keys_list.index(item)
+        return self.values_list[idx]
+
+    def keys(self) -> list[str]:
+        return list(self.keys_list)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        try:
+            return self[key]
+        except Exception:
+            return default
+
+    def items(self):
+        return list(zip(self.keys_list, self.values_list))
+
+    def __iter__(self):
+        return iter(self.items())
+
+    def __len__(self) -> int:
+        return len(self.values_list)
+
+    def as_dict(self) -> dict[str, Any]:
+        return dict(self.items())
+
+
+def _translate_qmark_sql(sql: str, params: Iterable[Any] | dict[str, Any] | None) -> tuple[str, dict[str, Any] | tuple[Any, ...]]:
+    if params is None:
+        return sql, {}
+    if isinstance(params, dict):
+        return sql, params
+
+    values = list(params)
+    if "?" not in sql:
+        return sql, tuple(values)
+
+    chunks = sql.split("?")
+    translated: list[str] = [chunks[0]]
+    bind: dict[str, Any] = {}
+    for idx, chunk in enumerate(chunks[1:]):
+        key = f"p{idx}"
+        translated.append(f":{key}")
+        translated.append(chunk)
+        if idx < len(values):
+            bind[key] = values[idx]
+    return "".join(translated), bind
+
+
+@lru_cache(maxsize=8)
+def _engine_for(database_url: str):
+    return create_engine(database_url, pool_pre_ping=True, future=True)
+
+
+class CompatCursor:
+    def __init__(self, connection: "CompatConnection"):
+        self._connection = connection
+        self._rows: list[CompatRow] = []
+        self._index = 0
+        self.rowcount = -1
+        self._last_result = None
+
+    def execute(self, sql: str, params: Iterable[Any] | dict[str, Any] | None = None):
+        if self._connection.backend == "sqlite":
+            bind = params if isinstance(params, dict) else tuple(params or ())  # type: ignore[arg-type]
+            cursor = self._connection._raw.execute(sql, bind)
+            keys = [desc[0] for desc in cursor.description] if cursor.description else []
+            self._rows = [CompatRow(keys, list(row)) for row in cursor.fetchall()] if keys else []
+            self.rowcount = cursor.rowcount
+            self._index = 0
+            self._last_result = cursor
+            return self
+
+        translated_sql, bind = _translate_qmark_sql(sql, params)
+        result = self._connection._conn.execute(text(translated_sql), bind)  # type: ignore[arg-type]
+        keys = list(result.keys()) if result.returns_rows else []
+        self._rows = [CompatRow(keys, list(row)) for row in result.fetchall()] if keys else []
+        self.rowcount = result.rowcount
+        self._index = 0
+        self._last_result = result
+        return self
+
+    def fetchone(self) -> CompatRow | None:
+        if self._index >= len(self._rows):
+            return None
+        row = self._rows[self._index]
+        self._index += 1
+        return row
+
+    def fetchall(self) -> list[CompatRow]:
+        if self._index >= len(self._rows):
+            return []
+        remaining = self._rows[self._index :]
+        self._index = len(self._rows)
+        return remaining
+
+
+class CompatConnection:
+    def __init__(self, database_url: str | None = None, timeout: int = 30):
+        self.database_url = database_url or database_uri()
+        self.backend = database_backend(self.database_url)
+        self._raw = None
+        self._engine = None
+        self._conn = None
+        self._transaction = None
+
+        if self.backend == "sqlite":
+            sqlite_path = sqlite_path_from_uri(self.database_url)
+            if sqlite_path is None:
+                sqlite_path = Path(self.database_url.removeprefix("sqlite:///"))
+            self._raw = sqlite3.connect(str(sqlite_path), timeout=timeout)
+        else:
+            self._engine = _engine_for(self.database_url)
+            self._conn = self._engine.connect()
+            self._transaction = self._conn.begin()
+
+    def cursor(self) -> CompatCursor:
+        return CompatCursor(self)
+
+    def execute(self, sql: str, params: Iterable[Any] | dict[str, Any] | None = None):
+        return self.cursor().execute(sql, params)
+
+    def executescript(self, script: str):
+        statements = [statement.strip() for statement in script.split(";") if statement.strip()]
+        for statement in statements:
+            self.execute(statement)
+        return self
+
+    def commit(self) -> None:
+        if self.backend == "sqlite":
+            assert self._raw is not None
+            self._raw.commit()
+            return
+        if self._conn is not None and self._transaction is not None:
+            self._transaction.commit()
+            self._transaction = self._conn.begin()
+
+    def rollback(self) -> None:
+        if self.backend == "sqlite":
+            assert self._raw is not None
+            self._raw.rollback()
+            return
+        if self._conn is not None and self._transaction is not None:
+            self._transaction.rollback()
+            self._transaction = self._conn.begin()
+
+    def close(self) -> None:
+        if self.backend == "sqlite":
+            if self._raw is not None:
+                self._raw.close()
+            return
+        if self._transaction is not None:
+            try:
+                self._transaction.commit()
+            except Exception:
+                try:
+                    self._transaction.rollback()
+                except Exception:
+                    pass
+        if self._conn is not None:
+            self._conn.close()
+
+    def __enter__(self) -> "CompatConnection":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        if exc_type is None:
+            self.commit()
+        else:
+            self.rollback()
+        self.close()
+        return False
+
+
+def connect_dashboard_db(database_url: str | None = None, timeout: int = 30) -> CompatConnection:
+    return CompatConnection(database_url=database_url, timeout=timeout)
diff --git a/dashboard/backend/db_migrations.py b/dashboard/backend/db_migrations.py
new file mode 100644
index 00000000..5684184d
--- /dev/null
+++ b/dashboard/backend/db_migrations.py
@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from pathlib import Path
+from urllib.parse import urlparse
+
+from alembic import command
+from alembic.config import Config
+
+from structured_logging import emit_json_log
+
+
+MIGRATIONS_DIR = Path(__file__).resolve().parent / "migrations"
+
+
+def build_alembic_config(database_uri: str) -> Config:
+    config = Config(str(MIGRATIONS_DIR / "alembic.ini"))
+    config.set_main_option("script_location", str(MIGRATIONS_DIR))
+    config.set_main_option("sqlalchemy.url", database_uri)
+    return config
+
+
+def run_database_migrations(database_uri: str) -> None:
+    scheme = urlparse(database_uri).scheme or "unknown"
+    emit_json_log(
+        "info",
+        "database_migration_start",
+        service="dashboard",
+        database_scheme=scheme,
+        script_location=str(MIGRATIONS_DIR),
+    )
+    try:
+        command.upgrade(build_alembic_config(database_uri), "head")
+    except Exception as exc:
+        emit_json_log(
+            "error",
+            "database_migration_failed",
+            service="dashboard",
+            database_scheme=scheme,
+            error=str(exc),
+        )
+        raise
+    emit_json_log(
+        "info",
+        "database_migration_complete",
+        service="dashboard",
+        database_scheme=scheme,
+        revision="head",
+    )
diff --git a/dashboard/backend/migrations/alembic.ini b/dashboard/backend/migrations/alembic.ini
new file mode 100644
index 00000000..9e959190
--- /dev/null
+++ b/dashboard/backend/migrations/alembic.ini
@@ -0,0 +1,3 @@
+[alembic]
+script_location = migrations
+sqlalchemy.url = sqlite:///evonexus.db
diff --git a/dashboard/backend/migrations/env.py b/dashboard/backend/migrations/env.py
new file mode 100644
index 00000000..d0f37575
--- /dev/null
+++ b/dashboard/backend/migrations/env.py
@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+BASE_DIR = Path(__file__).resolve().parents[1]
+if str(BASE_DIR) not in sys.path:
+    sys.path.insert(0, str(BASE_DIR))
+
+config = context.config
+
+db_url = os.environ.get("EVONEXUS_DATABASE_URL", "").strip()
+if db_url:
+    config.set_main_option("sqlalchemy.url", db_url)
+
+target_metadata = None
+
+
+def run_migrations_offline() -> None:
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    with connectable.connect() as connection:
+        context.configure(connection=connection, target_metadata=target_metadata)
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()
diff --git a/dashboard/backend/migrations/versions/0001_bootstrap_schema.py b/dashboard/backend/migrations/versions/0001_bootstrap_schema.py
new file mode 100644
index 00000000..42de0d66
--- /dev/null
+++ b/dashboard/backend/migrations/versions/0001_bootstrap_schema.py
@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from alembic import op
+
+from models import db
+from schema_migrations import downgrade_app_schema, upgrade_app_schema
+
+
+revision = "0001_bootstrap_schema"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    bind = op.get_bind()
+    db.metadata.create_all(bind=bind)
+    upgrade_app_schema(bind)
+
+
+def downgrade() -> None:
+    bind = op.get_bind()
+    downgrade_app_schema(bind)
+    db.metadata.drop_all(bind=bind)
diff --git a/dashboard/backend/platform_cache.py b/dashboard/backend/platform_cache.py
new file mode 100644
index 00000000..8033e0d0
--- /dev/null
+++ b/dashboard/backend/platform_cache.py
@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+from dataclasses import dataclass
+from functools import lru_cache
+from typing import Any, Callable
+
+
+_lock = threading.Lock()
+_memory_cache: dict[str, tuple[float | None, Any]] = {}
+
+
+@dataclass(frozen=True)
+class CacheStatus:
+    backend: str
+    available: bool
+    detail: str | None = None
+
+
+class _MemoryCacheBackend:
+    backend = "memory"
+
+    def get(self, key: str) -> Any:
+        now = time.time()
+        with _lock:
+            item = _memory_cache.get(key)
+            if not item:
+                return None
+            expires_at, value = item
+            if expires_at is not None and expires_at < now:
+                _memory_cache.pop(key, None)
+                return None
+            return value
+
+    def set(self, key: str, value: Any, ttl: int | None = None) -> None:
+        expires_at = (time.time() + ttl) if ttl else None
+        with _lock:
+            _memory_cache[key] = (expires_at, value)
+
+    def delete(self, key: str) -> None:
+        with _lock:
+            _memory_cache.pop(key, None)
+
+    def clear(self) -> None:
+        with _lock:
+            _memory_cache.clear()
+
+    def status(self) -> CacheStatus:
+        with _lock:
+            size = len(_memory_cache)
+        return CacheStatus(backend="memory", available=True, detail=f"{size} entries")
+
+
+class _RedisCacheBackend:
+    backend = "redis"
+
+    def __init__(self, url: str):
+        import redis  # type: ignore
+
+        self._redis = redis.Redis.from_url(url, decode_responses=True)
+        self._prefix = "evonexus:platform:cache:"
+        self._redis.ping()
+
+    def _key(self, key: str) -> str:
+        return f"{self._prefix}{key}"
+
+    def get(self, key: str) -> Any:
+        raw = self._redis.get(self._key(key))
+        return None if raw is None else json.loads(raw)
+
+    def set(self, key: str, value: Any, ttl: int | None = None) -> None:
+        payload = json.dumps(value, ensure_ascii=False)
+        if ttl:
+            self._redis.setex(self._key(key), ttl, payload)
+        else:
+            self._redis.set(self._key(key), payload)
+
+    def delete(self, key: str) -> None:
+        self._redis.delete(self._key(key))
+
+    def clear(self) -> None:
+        for key in self._redis.scan_iter(match=f"{self._prefix}*"):
+            self._redis.delete(key)
+
+    def status(self) -> CacheStatus:
+        try:
+            pong = self._redis.ping()
+            return CacheStatus(backend="redis", available=bool(pong), detail=os.environ.get("REDIS_URL"))
+        except Exception as exc:
+            return CacheStatus(backend="redis", available=False, detail=str(exc)[:200])
+
+
+@lru_cache(maxsize=1)
+def _get_backend() -> Any:
+    redis_url = os.environ.get("REDIS_URL", "").strip()
+    if redis_url:
+        try:
+            return _RedisCacheBackend(redis_url)
+        except Exception:
+            pass
+    return _MemoryCacheBackend()
+
+
+def cache_get(key: str) -> Any:
+    return _get_backend().get(key)
+
+
+def cache_set(key: str, value: Any, ttl: int | None = None) -> None:
+    _get_backend().set(key, value, ttl)
+
+
+def cache_delete(key: str) -> None:
+    _get_backend().delete(key)
+
+
+def cache_get_or_set(key: str, loader: Callable[[], Any], ttl: int | None = None) -> Any:
+    cached = cache_get(key)
+    if cached is not None:
+        return cached
+    value = loader()
+    cache_set(key, value, ttl=ttl)
+    return value
+
+
+def cache_status() -> dict[str, Any]:
+    status = _get_backend().status()
+    return {
+        "backend": status.backend,
+        "available": status.available,
+        "detail": status.detail,
+    }
+
diff --git a/dashboard/backend/platform_metrics.py b/dashboard/backend/platform_metrics.py
new file mode 100644
index 00000000..5e64e0a8
--- /dev/null
+++ b/dashboard/backend/platform_metrics.py
@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from statistics import mean
+from typing import Any
+
+from platform_support import PROVIDER_METRICS_PATH, append_jsonl, read_jsonl
+
+
+def record_provider_event(
+    *,
+    provider_id: str,
+    event: str,
+    model: str | None = None,
+    latency_ms: float | None = None,
+    success: bool | None = None,
+    detail: str | None = None,
+    mode: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "provider_id": provider_id,
+        "event": event,
+        "model": model,
+        "latency_ms": latency_ms,
+        "success": success,
+        "detail": detail,
+        "mode": mode,
+        "metadata": metadata or {},
+    }
+    return append_jsonl(PROVIDER_METRICS_PATH, payload)
+
+
+def load_provider_events(limit: int = 500) -> list[dict[str, Any]]:
+    return read_jsonl(PROVIDER_METRICS_PATH, limit=limit)
+
+
+def summarize_provider_events(limit: int = 500) -> dict[str, Any]:
+    events = load_provider_events(limit=limit)
+    by_provider: dict[str, dict[str, Any]] = defaultdict(lambda: {
+        "events": 0,
+        "successes": 0,
+        "failures": 0,
+        "latencies": [],
+        "models": defaultdict(lambda: {"events": 0, "successes": 0, "failures": 0, "latencies": []}),
+        "last_event": None,
+    })
+
+    for event in events:
+        provider_id = event.get("provider_id") or "unknown"
+        provider_bucket = by_provider[provider_id]
+        provider_bucket["events"] += 1
+        provider_bucket["last_event"] = event
+        model = event.get("model") or "unknown"
+        model_bucket = provider_bucket["models"][model]
+        model_bucket["events"] += 1
+        if event.get("success") is True:
+            provider_bucket["successes"] += 1
+            model_bucket["successes"] += 1
+        elif event.get("success") is False:
+            provider_bucket["failures"] += 1
+            model_bucket["failures"] += 1
+        latency = event.get("latency_ms")
+        if isinstance(latency, (int, float)):
+            provider_bucket["latencies"].append(float(latency))
+            model_bucket["latencies"].append(float(latency))
+
+    summary = []
+    for provider_id, bucket in by_provider.items():
+        latencies = bucket.pop("latencies")
+        models = []
+        for model_id, model_bucket in bucket.pop("models").items():
+            model_latencies = model_bucket.pop("latencies")
+            model_bucket["avg_latency_ms"] = round(mean(model_latencies), 2) if model_latencies else None
+            models.append({"model": model_id, **model_bucket})
+        bucket["avg_latency_ms"] = round(mean(latencies), 2) if latencies else None
+        bucket["success_rate"] = round((bucket["successes"] / bucket["events"]) * 100, 1) if bucket["events"] else None
+        bucket["models"] = sorted(models, key=lambda row: (-row["events"], row["model"]))
+        summary.append({"provider_id": provider_id, **bucket})
+
+    summary.sort(key=lambda row: (-row["events"], row["provider_id"]))
+    return {
+        "events": events[-100:],
+        "providers": summary,
+        "total_events": len(events),
+    }
+
diff --git a/dashboard/backend/platform_observability.py b/dashboard/backend/platform_observability.py
new file mode 100644
index 00000000..1be6dcd5
--- /dev/null
+++ b/dashboard/backend/platform_observability.py
@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+import requests
+from flask import current_app
+
+from platform_cache import cache_get_or_set, cache_status
+from platform_metrics import summarize_provider_events
+from platform_plugins import list_plugins, load_installed_plugins, load_plugin_registry
+from platform_queue import list_events, queue_status
+from platform_support import WORKSPACE, database_scheme, read_json
+
+
+def _load_provider_config() -> dict[str, Any]:
+    config_path = WORKSPACE / "config" / "providers.json"
+    fallback_path = WORKSPACE / "config" / "providers.example.json"
+    config = read_json(config_path, read_json(fallback_path, {}))
+    return config if isinstance(config, dict) else {}
+
+
+def _terminal_server_snapshot() -> dict[str, Any]:
+    import os
+
+    url = os.environ.get("TERMINAL_SERVER_URL", "http://127.0.0.1:32352").rstrip("/")
+    try:
+        resp = requests.get(f"{url}/api/health/deep", timeout=3)
+        data = resp.json()
+        return {
+            "status": data.get("status", "warning") if resp.ok else "error",
+            "reachable": resp.ok,
+            "http_status": resp.status_code,
+            "url": url,
+            "snapshot": data,
+        }
+    except Exception as exc:
+        return {
+            "status": "warning",
+            "reachable": False,
+            "http_status": None,
+            "url": url,
+            "error": str(exc)[:200],
+        }
+
+
+def _build_observability_summary() -> dict[str, Any]:
+    from routes.health import _build_report
+    from routes.costs import costs_summary
+
+    backend_health = _build_report(deep=True)
+    terminal = _terminal_server_snapshot()
+    costs_resp = costs_summary()
+    costs = costs_resp.get_json(silent=True) if hasattr(costs_resp, "get_json") else None
+    provider_config = _load_provider_config()
+    registry = load_plugin_registry()
+    installed = load_installed_plugins()
+
+    provider_metrics = summarize_provider_events(limit=500)
+    plugin_list = list_plugins()
+    events = list_events(limit=25)
+
+    try:
+        database_uri = current_app.config.get("SQLALCHEMY_DATABASE_URI")
+    except RuntimeError:
+        from runtime_config import database_uri as resolve_database_uri
+
+        database_uri = resolve_database_uri()
+
+    return {
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "backend": backend_health,
+        "terminal_server": terminal,
+        "costs": costs or {},
+        "provider_config": provider_config,
+        "provider_metrics": provider_metrics,
+        "cache": cache_status(),
+        "queue": queue_status(),
+        "plugins": {
+            "registry_count": len(registry.get("plugins", [])),
+            "installed_count": len(installed.get("plugins", {})),
+            "items": plugin_list,
+        },
+        "recent_events": events,
+        "database_backend": database_scheme(database_uri),
+    }
+
+
+def build_observability_summary() -> dict[str, Any]:
+    return cache_get_or_set("observability:summary", _build_observability_summary, ttl=30)
diff --git a/dashboard/backend/platform_plugins.py b/dashboard/backend/platform_plugins.py
new file mode 100644
index 00000000..85efc482
--- /dev/null
+++ b/dashboard/backend/platform_plugins.py
@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from platform_queue import publish_event
+from platform_support import INSTALLED_PLUGINS_PATH, PLUGIN_REGISTRY_PATH, WORKSPACE, ensure_platform_data_dir, read_json, write_json
+
+
+_SAFE_PLUGIN_ID = re.compile(r"^[a-z0-9][a-z0-9_-]*$")
+_AGENTS_DIR = WORKSPACE / ".claude" / "agents"
+
+
+DEFAULT_PLUGIN_REGISTRY = {
+    "plugins": [
+        {
+            "id": "observability-scout",
+            "name": "Observability Scout",
+            "version": "1.0.0",
+            "category": "observability",
+            "description": "Installs a read-only agent pack for platform telemetry and incident triage.",
+            "agents": [
+                {
+                    "name": "observability-scout",
+                    "description": "Read-only observability analyst for EvoNexus. Uses metrics, health, costs, and provider routing data to identify regressions.",
+                    "model": "haiku",
+                    "color": "cyan",
+                    "memory": "project",
+                    "disallowedTools": ["Write", "Edit", "Bash", "NotebookEdit"],
+                    "prompt": (
+                        "You are Observability Scout.\n"
+                        "Analyze EvoNexus platform health, provider routing, queue/cache status, and cost trends.\n"
+                        "Recommend concrete fixes with clear severity. Do not edit files."
+                    ),
+                }
+            ],
+        },
+        {
+            "id": "provider-router",
+            "name": "Provider Router",
+            "version": "1.0.0",
+            "category": "platform",
+            "description": "Installs a read-only agent pack for provider failover and routing audits.",
+            "agents": [
+                {
+                    "name": "provider-router",
+                    "description": "Read-only provider routing specialist for EvoNexus. Reviews failover order, provider health, and selected model mode.",
+                    "model": "haiku",
+                    "color": "violet",
+                    "memory": "project",
+                    "disallowedTools": ["Write", "Edit", "Bash", "NotebookEdit"],
+                    "prompt": (
+                        "You are Provider Router.\n"
+                        "Audit provider health, failover order, and model compatibility.\n"
+                        "Recommend a safe routing chain and explain why a fallback should or should not be activated."
+                    ),
+                }
+            ],
+        },
+    ]
+}
+
+
+def _safe_plugin_id(plugin_id: str) -> str:
+    plugin_id = (plugin_id or "").strip().lower()
+    if not _SAFE_PLUGIN_ID.match(plugin_id):
+        raise ValueError("Invalid plugin id")
+    return plugin_id
+
+
+def load_plugin_registry() -> dict[str, Any]:
+    registry = read_json(PLUGIN_REGISTRY_PATH, DEFAULT_PLUGIN_REGISTRY)
+    if not isinstance(registry, dict) or "plugins" not in registry:
+        return DEFAULT_PLUGIN_REGISTRY
+    plugins = registry.get("plugins")
+    if not isinstance(plugins, list):
+        return DEFAULT_PLUGIN_REGISTRY
+    return registry
+
+
+def load_installed_plugins() -> dict[str, Any]:
+    payload = read_json(INSTALLED_PLUGINS_PATH, {"plugins": {}})
+    if not isinstance(payload, dict):
+        return {"plugins": {}}
+    if not isinstance(payload.get("plugins"), dict):
+        payload["plugins"] = {}
+    return payload
+
+
+def _save_installed_plugins(payload: dict[str, Any]) -> None:
+    ensure_platform_data_dir()
+    write_json(INSTALLED_PLUGINS_PATH, payload)
+
+
+def _render_agent(agent: dict[str, Any], plugin_id: str) -> str:
+    frontmatter: dict[str, Any] = {
+        "name": agent["name"],
+        "description": agent["description"],
+        "model": agent.get("model", "haiku"),
+        "color": agent.get("color", "cyan"),
+        "memory": agent.get("memory", "project"),
+        "plugin": plugin_id,
+        "disallowedTools": agent.get("disallowedTools", ["Write", "Edit", "Bash", "NotebookEdit"]),
+    }
+    prompt = agent.get("prompt", "").strip()
+    return "---\n" + yaml.safe_dump(frontmatter, sort_keys=False, allow_unicode=True).strip() + "\n---\n\n" + prompt + "\n"
+
+
+def _installed_files_for(plugin: dict[str, Any]) -> list[dict[str, str]]:
+    files: list[dict[str, str]] = []
+    for agent in plugin.get("agents", []) or []:
+        files.append({
+            "type": "agent",
+            "name": agent["name"],
+            "path": f".claude/agents/{agent['name']}.md",
+        })
+    return files
+
+
+def list_plugins() -> list[dict[str, Any]]:
+    registry = load_plugin_registry()
+    installed = load_installed_plugins().get("plugins", {})
+    result = []
+    for plugin in registry.get("plugins", []):
+        plugin_id = plugin.get("id")
+        if not plugin_id:
+            continue
+        state = installed.get(plugin_id, {})
+        result.append({
+            **plugin,
+            "installed": bool(state),
+            "installed_at": state.get("installed_at"),
+            "installed_files": state.get("files", []),
+        })
+    return result
+
+
+def install_plugin(plugin_id: str, workspace: Path = WORKSPACE) -> dict[str, Any]:
+    plugin_key = _safe_plugin_id(plugin_id)
+    registry = load_plugin_registry()
+    plugin = next((item for item in registry.get("plugins", []) if item.get("id") == plugin_key), None)
+    if not plugin:
+        raise KeyError(f"Unknown plugin: {plugin_key}")
+
+    installed = load_installed_plugins()
+    if plugin_key in installed.get("plugins", {}):
+        return installed["plugins"][plugin_key]
+
+    _AGENTS_DIR.mkdir(parents=True, exist_ok=True)
+
+    written_files: list[str] = []
+    for agent in plugin.get("agents", []) or []:
+        target = workspace / ".claude" / "agents" / f"{agent['name']}.md"
+        if target.exists():
+            raise FileExistsError(f"Agent file already exists: {target.name}")
+        target.write_text(_render_agent(agent, plugin_key), encoding="utf-8")
+        written_files.append(str(target.relative_to(workspace)).replace("\\", "/"))
+
+    state = {
+        "id": plugin_key,
+        "name": plugin.get("name", plugin_key),
+        "version": plugin.get("version", "1.0.0"),
+        "installed_at": datetime.now(timezone.utc).isoformat(),
+        "files": written_files,
+    }
+    installed.setdefault("plugins", {})[plugin_key] = state
+    _save_installed_plugins(installed)
+    publish_event("plugin-installed", {"plugin_id": plugin_key, "files": written_files})
+    return state
+
+
+def uninstall_plugin(plugin_id: str, workspace: Path = WORKSPACE) -> dict[str, Any]:
+    plugin_key = _safe_plugin_id(plugin_id)
+    installed = load_installed_plugins()
+    state = installed.get("plugins", {}).get(plugin_key)
+    if not state:
+        raise KeyError(f"Plugin not installed: {plugin_key}")
+
+    removed: list[str] = []
+    for rel_path in state.get("files", []):
+        target = workspace / rel_path
+        if target.exists():
+            target.unlink()
+            removed.append(rel_path)
+
+    installed["plugins"].pop(plugin_key, None)
+    _save_installed_plugins(installed)
+    publish_event("plugin-uninstalled", {"plugin_id": plugin_key, "files": removed})
+    return {"id": plugin_key, "removed_files": removed}
diff --git a/dashboard/backend/platform_queue.py b/dashboard/backend/platform_queue.py
new file mode 100644
index 00000000..a495e4d1
--- /dev/null
+++ b/dashboard/backend/platform_queue.py
@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import json
+
+from platform_cache import cache_delete
+from platform_support import PLATFORM_EVENTS_PATH, append_jsonl, ensure_platform_data_dir, read_jsonl
+
+
+def publish_event(topic: str, payload: dict[str, Any], source: str = "dashboard") -> dict[str, Any]:
+    ensure_platform_data_dir()
+    event = append_jsonl(PLATFORM_EVENTS_PATH, {
+        "topic": topic,
+        "source": source,
+        "payload": payload,
+    })
+
+    redis_url = os.environ.get("REDIS_URL", "").strip()
+    if redis_url:
+        try:
+            import redis  # type: ignore
+
+            redis.Redis.from_url(redis_url, decode_responses=True).publish(
+                "evonexus:platform",
+                json.dumps(event, ensure_ascii=False),
+            )
+        except Exception:
+            pass
+
+    for cache_key in (
+        "providers:list",
+        "observability:summary",
+        "observability:providers",
+        "platform:queue:50",
+    ):
+        try:
+            cache_delete(cache_key)
+        except Exception:
+            pass
+
+    return event
+
+
+def list_events(limit: int = 100, topics: list[str] | None = None) -> list[dict[str, Any]]:
+    events = read_jsonl(PLATFORM_EVENTS_PATH, limit=limit)
+    if topics:
+        allowed = set(topics)
+        events = [event for event in events if event.get("topic") in allowed]
+    return events
+
+
+def queue_status() -> dict[str, Any]:
+    events = read_jsonl(PLATFORM_EVENTS_PATH, limit=200)
+    latest = events[-1] if events else None
+    return {
+        "backend": "file",
+        "path": str(PLATFORM_EVENTS_PATH),
+        "event_count": len(events),
+        "latest_event": latest,
+    }
diff --git a/dashboard/backend/platform_support.py b/dashboard/backend/platform_support.py
new file mode 100644
index 00000000..29ee13d4
--- /dev/null
+++ b/dashboard/backend/platform_support.py
@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+WORKSPACE = Path(__file__).resolve().parent.parent.parent
+PLATFORM_DATA_DIR = WORKSPACE / "dashboard" / "data" / "platform"
+PLATFORM_EVENTS_PATH = PLATFORM_DATA_DIR / "events.jsonl"
+PROVIDER_METRICS_PATH = PLATFORM_DATA_DIR / "provider-metrics.jsonl"
+INSTALLED_PLUGINS_PATH = PLATFORM_DATA_DIR / "installed-plugins.json"
+PLUGIN_REGISTRY_PATH = WORKSPACE / "config" / "plugin-registry.json"
+
+
+def ensure_platform_data_dir() -> Path:
+    PLATFORM_DATA_DIR.mkdir(parents=True, exist_ok=True)
+    return PLATFORM_DATA_DIR
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def read_json(path: Path, default: Any) -> Any:
+    try:
+        if not path.exists():
+            return default
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return default
+
+
+def write_json(path: Path, payload: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def append_jsonl(path: Path, payload: dict[str, Any]) -> dict[str, Any]:
+    ensure_platform_data_dir()
+    event = {"ts": _now_iso(), **payload}
+    with path.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(event, ensure_ascii=False) + "\n")
+    return event
+
+
+def read_jsonl(path: Path, limit: int | None = None) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    rows: list[dict[str, Any]] = []
+    try:
+        for raw_line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+            line = raw_line.strip()
+            if not line:
+                continue
+            try:
+                row = json.loads(line)
+            except Exception:
+                continue
+            if isinstance(row, dict):
+                rows.append(row)
+    except Exception:
+        return []
+    if limit is not None and limit >= 0:
+        return rows[-limit:]
+    return rows
+
+
+def database_scheme(database_uri: str | None) -> str:
+    if not database_uri:
+        return "sqlite"
+    if "://" not in database_uri:
+        return "sqlite"
+    return database_uri.split(":", 1)[0].lower()
diff --git a/dashboard/backend/request_security.py b/dashboard/backend/request_security.py
new file mode 100644
index 00000000..c1e356d8
--- /dev/null
+++ b/dashboard/backend/request_security.py
@@ -0,0 +1,41 @@
+"""HTTP request security helpers shared by Flask blueprints."""
+
+from __future__ import annotations
+
+from flask import abort, request
+
+from session_security import CSRF_HEADER_NAME, XHR_HEADER_NAME, XHR_HEADER_VALUE, issue_session_token
+
+MUTATING_METHODS = {"POST", "PUT", "PATCH", "DELETE"}
+
+XHR_EXEMPT_PREFIXES = (
+    "/api/knowledge/v1/",
+    "/api/triggers/webhook/",
+)
+
+
+def should_require_xhr(path: str, method: str, authorization_header: str = "") -> bool:
+    """Return True when a mutating API request must carry the XHR header."""
+
+    if method.upper() not in MUTATING_METHODS:
+        return False
+    if not path.startswith("/api/"):
+        return False
+    if (authorization_header or "").strip().startswith("Bearer "):
+        return False
+    for prefix in XHR_EXEMPT_PREFIXES:
+        if path.startswith(prefix):
+            return False
+    return True
+
+
+def require_xhr(req=request) -> None:
+    """Abort with 403 if a mutating request lacks the XHR and CSRF headers."""
+
+    if not should_require_xhr(req.path, req.method, req.headers.get("Authorization", "")):
+        return
+    if req.headers.get(XHR_HEADER_NAME) != XHR_HEADER_VALUE:
+        abort(403, description="CSRF check failed: X-Requested-With header missing.")
+    expected = issue_session_token(force=False)
+    if req.headers.get(CSRF_HEADER_NAME, "").strip() != expected:
+        abort(403, description="CSRF check failed: invalid or missing CSRF token.")
diff --git a/dashboard/backend/routes/platform.py b/dashboard/backend/routes/platform.py
new file mode 100644
index 00000000..c13c3e3f
--- /dev/null
+++ b/dashboard/backend/routes/platform.py
@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+from flask import Blueprint, jsonify, request
+from flask_login import login_required
+
+from models import has_permission
+from platform_cache import cache_delete, cache_get, cache_get_or_set
+from platform_observability import build_observability_summary
+from platform_plugins import install_plugin, list_plugins, uninstall_plugin
+from platform_queue import list_events, queue_status
+
+bp = Blueprint("platform", __name__)
+
+
+def _require(resource: str, action: str):
+    from flask_login import current_user
+
+    if not has_permission(current_user.role, resource, action):
+        return jsonify({"error": "Forbidden"}), 403
+    return None
+
+
+@bp.route("/api/observability/summary")
+@login_required
+def observability_summary():
+    denied = _require("systems", "view")
+    if denied:
+        return denied
+    return jsonify(build_observability_summary())
+
+
+@bp.route("/api/observability/providers")
+@login_required
+def observability_providers():
+    denied = _require("systems", "view")
+    if denied:
+        return denied
+    def _load_snapshot():
+        summary = build_observability_summary()
+        return {
+            "provider_metrics": summary.get("provider_metrics", {}),
+            "provider_config": summary.get("provider_config", {}),
+        }
+
+    return jsonify(cache_get_or_set("observability:providers", _load_snapshot, ttl=30))
+
+
+@bp.route("/api/platform/cache")
+@login_required
+def platform_cache():
+    denied = _require("systems", "view")
+    if denied:
+        return denied
+    return jsonify({
+        "cached_provider_list": cache_get("providers:list"),
+        "cached_observability": cache_get("observability:summary"),
+        "cached_observability_providers": cache_get("observability:providers"),
+        "cached_platform_queue": cache_get("platform:queue:50"),
+    })
+
+
+@bp.route("/api/platform/cache/clear", methods=["POST"])
+@login_required
+def platform_cache_clear():
+    denied = _require("config", "manage")
+    if denied:
+        return denied
+    cache_delete("providers:list")
+    cache_delete("observability:summary")
+    cache_delete("observability:providers")
+    cache_delete("platform:queue:50")
+    return jsonify({"status": "ok"})
+
+
+@bp.route("/api/platform/queue")
+@login_required
+def platform_queue():
+    denied = _require("systems", "view")
+    if denied:
+        return denied
+    return jsonify(cache_get_or_set(
+        "platform:queue:50",
+        lambda: {
+            "status": queue_status(),
+            "events": list_events(limit=50),
+        },
+        ttl=10,
+    ))
+
+
+@bp.route("/api/platform/plugins")
+@login_required
+def plugins_list():
+    denied = _require("systems", "view")
+    if denied:
+        return denied
+    return jsonify({"plugins": list_plugins()})
+
+
+@bp.route("/api/platform/plugins/install", methods=["POST"])
+@login_required
+def plugins_install():
+    denied = _require("config", "manage")
+    if denied:
+        return denied
+    data = request.get_json(silent=True) or {}
+    plugin_id = (data.get("plugin_id") or "").strip()
+    if not plugin_id:
+        return jsonify({"error": "plugin_id is required"}), 400
+    try:
+        result = install_plugin(plugin_id)
+    except KeyError as exc:
+        return jsonify({"error": str(exc)}), 404
+    except FileExistsError as exc:
+        return jsonify({"error": str(exc)}), 409
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 400
+    cache_delete("observability:summary")
+    return jsonify({"status": "ok", "plugin": result})
+
+
+@bp.route("/api/platform/plugins/<plugin_id>/uninstall", methods=["POST"])
+@login_required
+def plugins_uninstall(plugin_id: str):
+    denied = _require("config", "manage")
+    if denied:
+        return denied
+    try:
+        result = uninstall_plugin(plugin_id)
+    except KeyError as exc:
+        return jsonify({"error": str(exc)}), 404
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 400
+    cache_delete("observability:summary")
+    return jsonify({"status": "ok", "plugin": result})
diff --git a/dashboard/backend/runtime_config.py b/dashboard/backend/runtime_config.py
new file mode 100644
index 00000000..da1266ec
--- /dev/null
+++ b/dashboard/backend/runtime_config.py
@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import os
+import re
+import secrets
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+
+WORKSPACE = Path(__file__).resolve().parent.parent.parent
+
+
+def is_production() -> bool:
+    env = (
+        os.environ.get("EVONEXUS_ENV")
+        or os.environ.get("FLASK_ENV")
+        or os.environ.get("ENV")
+        or ""
+    ).strip().lower()
+    return env in {"production", "prod"}
+
+
+def cors_allowed_origins() -> list[str] | str:
+    raw = os.environ.get("CORS_ALLOWED_ORIGINS", "").strip()
+    if raw:
+        if raw == "*":
+            return "*"
+        origins = [origin.strip() for origin in re.split(r"[,\s]+", raw) if origin.strip()]
+        return origins or "*"
+    return "*" if not is_production() else []
+
+
+def database_uri(workspace: Path = WORKSPACE) -> str:
+    for key in ("SQLALCHEMY_DATABASE_URI", "EVONEXUS_DATABASE_URL", "DATABASE_URL"):
+        raw = os.environ.get(key, "").strip()
+        if raw:
+            return raw
+    return f"sqlite:///{workspace / 'dashboard' / 'data' / 'evonexus.db'}"
+
+
+def database_backend(database_uri_value: str) -> str:
+    if "://" not in database_uri_value:
+        return "sqlite"
+    return (database_uri_value.split(":", 1)[0] or "sqlite").lower()
+
+
+def sqlite_path_from_uri(database_uri_value: str) -> Path | None:
+    prefix = "sqlite:///"
+    if not database_uri_value.startswith(prefix):
+        return None
+    return Path(database_uri_value.removeprefix(prefix))
+
+
+def dashboard_port(workspace: Path = WORKSPACE) -> int:
+    for key in ("EVONEXUS_PORT", "DASHBOARD_PORT", "PORT"):
+        raw = os.environ.get(key, "").strip()
+        if raw:
+            try:
+                port = int(raw)
+                if 1 <= port <= 65535:
+                    return port
+            except ValueError:
+                pass
+
+    config_path = workspace / "config" / "workspace.yaml"
+    if config_path.is_file():
+        try:
+            cfg = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+            dashboard_cfg = cfg.get("dashboard", {}) if isinstance(cfg, dict) else {}
+            for candidate in (dashboard_cfg.get("port"), cfg.get("port") if isinstance(cfg, dict) else None):
+                if candidate is None:
+                    continue
+                port = int(candidate)
+                if 1 <= port <= 65535:
+                    return port
+        except Exception:
+            pass
+
+    return 8080
+
+
+def resolve_secret_key(workspace: Path = WORKSPACE) -> str:
+    """Resolve the dashboard secret key from env or the local fallback file."""
+
+    secret_key = os.environ.get("EVONEXUS_SECRET_KEY", "").strip()
+    if secret_key:
+        return secret_key
+
+    if is_production():
+        raise RuntimeError("EVONEXUS_SECRET_KEY must be set in production")
+
+    key_file = workspace / "dashboard" / "data" / ".secret_key"
+    key_file.parent.mkdir(parents=True, exist_ok=True)
+    if key_file.exists():
+        return key_file.read_text(encoding="utf-8").strip()
+
+    secret_key = secrets.token_hex(32)
+    key_file.write_text(secret_key, encoding="utf-8")
+    key_file.chmod(0o600)
+    return secret_key
+
+
+@dataclass(frozen=True)
+class DashboardRuntimeConfig:
+    secret_key: str
+    database_uri: str
+    database_backend: str
+    cors_allowed_origins: list[str] | str
+    dashboard_port: int
+
+
+def load_dashboard_runtime_config(workspace: Path = WORKSPACE) -> DashboardRuntimeConfig:
+    db_uri = database_uri(workspace)
+    return DashboardRuntimeConfig(
+        secret_key=resolve_secret_key(workspace),
+        database_uri=db_uri,
+        database_backend=database_backend(db_uri),
+        cors_allowed_origins=cors_allowed_origins(),
+        dashboard_port=dashboard_port(workspace),
+    )
diff --git a/dashboard/backend/schema_migrations.py b/dashboard/backend/schema_migrations.py
new file mode 100644
index 00000000..5c46a280
--- /dev/null
+++ b/dashboard/backend/schema_migrations.py
@@ -0,0 +1,291 @@
+from __future__ import annotations
+
+from sqlalchemy import inspect
+
+
+def _table_names(connection) -> set[str]:
+    return set(inspect(connection).get_table_names())
+
+
+def _column_names(connection, table_name: str) -> set[str]:
+    if table_name not in _table_names(connection):
+        return set()
+    return {column["name"] for column in inspect(connection).get_columns(table_name)}
+
+
+def _scalar(connection, sql: str, params: tuple | dict | None = None):
+    result = connection.exec_driver_sql(sql, params or ())
+    row = result.fetchone()
+    return row[0] if row else None
+
+
+def _execute(connection, sql: str, params: tuple | dict | None = None) -> None:
+    connection.exec_driver_sql(sql, params or ())
+
+
+def upgrade_app_schema(connection) -> None:
+    """Apply the schema drift fixes that used to live inline in app.py."""
+
+    tables = _table_names(connection)
+    dialect_name = getattr(getattr(connection, "dialect", None), "name", "sqlite")
+    is_postgres = dialect_name == "postgresql"
+    current_ts = "CURRENT_TIMESTAMP" if is_postgres else "datetime('now')"
+
+    if "roles" in tables:
+        role_cols = _column_names(connection, "roles")
+        if "agent_access_json" not in role_cols:
+            _execute(connection, "ALTER TABLE roles ADD COLUMN agent_access_json TEXT DEFAULT '{\"mode\": \"all\"}'")
+        if "workspace_folders_json" not in role_cols:
+            _execute(connection, "ALTER TABLE roles ADD COLUMN workspace_folders_json TEXT DEFAULT '{\"mode\": \"all\"}'")
+
+    # Goal cascade helpers: keep the view and trigger available on every boot.
+    if "goals" in tables and "goal_tasks" in tables:
+        _execute(
+            connection,
+            """
+            CREATE VIEW IF NOT EXISTS goal_progress_v AS
+            SELECT g.id as goal_id, g.slug, g.target_value,
+                   COUNT(t.id) as total_tasks,
+                   COUNT(CASE WHEN t.status='done' THEN 1 END) as done_tasks,
+                   CASE WHEN COUNT(t.id) > 0
+                        THEN CAST(COUNT(CASE WHEN t.status='done' THEN 1 END) AS REAL) / COUNT(t.id) * 100.0
+                        ELSE 0 END as pct_complete
+            FROM goals g LEFT JOIN goal_tasks t ON t.goal_id = g.id
+            GROUP BY g.id;
+            """,
+        )
+        if is_postgres:
+            _execute(
+                connection,
+                """
+                CREATE OR REPLACE FUNCTION trg_task_done_updates_goal_fn()
+                RETURNS trigger AS $$
+                BEGIN
+                  IF NEW.goal_id IS NOT NULL AND NEW.status = 'done' AND OLD.status <> 'done' THEN
+                    UPDATE goals
+                    SET current_value = current_value + 1, updated_at = CURRENT_TIMESTAMP
+                    WHERE id = NEW.goal_id;
+                    UPDATE goals
+                    SET status = 'achieved'
+                    WHERE id = NEW.goal_id AND current_value >= target_value AND status = 'active';
+                  END IF;
+                  RETURN NEW;
+                END;
+                $$ LANGUAGE plpgsql;
+                """,
+            )
+            _execute(
+                connection,
+                """
+                CREATE TRIGGER trg_task_done_updates_goal
+                AFTER UPDATE OF status ON goal_tasks
+                FOR EACH ROW
+                EXECUTE FUNCTION trg_task_done_updates_goal_fn();
+                """,
+            )
+        else:
+            _execute(
+                connection,
+                """
+                CREATE TRIGGER IF NOT EXISTS trg_task_done_updates_goal
+                AFTER UPDATE OF status ON goal_tasks
+                WHEN NEW.goal_id IS NOT NULL AND NEW.status = 'done' AND OLD.status != 'done'
+                BEGIN
+                  UPDATE goals SET current_value = current_value + 1, updated_at = datetime('now') WHERE id = NEW.goal_id;
+                  UPDATE goals SET status = 'achieved' WHERE id = NEW.goal_id AND current_value >= target_value AND status = 'active';
+                END;
+                """,
+            )
+
+        mission_count = _scalar(connection, "SELECT COUNT(*) FROM missions")
+        if mission_count == 0:
+            _now_seed = "2026-04-14T00:00:00.000000Z"
+            _execute(
+                connection,
+                """
+                INSERT INTO missions (slug, title, description, target_metric, target_value, current_value, due_date, status, created_at, updated_at)
+                VALUES ('evo-revenue-1m-q4-2026', 'Evolution Revenue $1M Q4 2026',
+                        'Atingir $1M de receita anual até o Q4 2026',
+                        'revenue_usd', 1000000, 0, '2026-12-31', 'active', ?, ?)
+                """,
+                (_now_seed, _now_seed),
+            )
+            mission_id = _scalar(connection, "SELECT id FROM missions WHERE slug = 'evo-revenue-1m-q4-2026'")
+            for slug, title, description in [
+                ("evo-ai", "Evo AI", "CRM + AI agents — produto principal"),
+                ("evo-summit", "Evolution Summit", "Evento de lançamento (14-16 Abr 2026)"),
+                ("evo-academy", "Evo Academy", "Plataforma de cursos"),
+            ]:
+                _execute(
+                    connection,
+                    """
+                    INSERT INTO projects (slug, mission_id, title, description, status, created_at, updated_at)
+                    VALUES (?, ?, ?, ?, 'active', ?, ?)
+                    """,
+                    (slug, mission_id, title, description, _now_seed, _now_seed),
+                )
+
+            project_ids = {
+                "evo-ai": _scalar(connection, "SELECT id FROM projects WHERE slug = 'evo-ai'"),
+                "evo-summit": _scalar(connection, "SELECT id FROM projects WHERE slug = 'evo-summit'"),
+                "evo-academy": _scalar(connection, "SELECT id FROM projects WHERE slug = 'evo-academy'"),
+            }
+            goals_seed = [
+                ("evo-ai-100-customers", project_ids["evo-ai"], "100 paying customers by Jun 30", "customers", "count", 100, "2026-06-30"),
+                ("evo-ai-billing-v2", project_ids["evo-ai"], "Ship billing v2", "shipped", "boolean", 1, "2026-05-31"),
+                ("evo-summit-200-tickets", project_ids["evo-summit"], "Sell 200 tickets", "tickets_sold", "count", 200, "2026-04-13"),
+                ("evo-summit-3-sponsors", project_ids["evo-summit"], "Close 3 sponsors", "sponsors", "count", 3, "2026-04-10"),
+                ("evo-academy-50-students", project_ids["evo-academy"], "50 beta students", "students", "count", 50, "2026-06-30"),
+            ]
+            for slug, project_id, title, target_metric, metric_type, target_value, due_date in goals_seed:
+                _execute(
+                    connection,
+                    """
+                    INSERT INTO goals (slug, project_id, title, target_metric, metric_type, target_value, current_value, status, created_at, updated_at, due_date)
+                    VALUES (?, ?, ?, ?, ?, ?, 0, 'active', ?, ?, ?)
+                    """,
+                    (slug, project_id, title, target_metric, metric_type, target_value, _now_seed, _now_seed, due_date),
+                )
+
+    if "tickets" in tables:
+        ticket_cols = _column_names(connection, "tickets")
+        for column_name, ddl in [
+            ("source_agent", "ALTER TABLE tickets ADD COLUMN source_agent TEXT"),
+            ("source_session_id", "ALTER TABLE tickets ADD COLUMN source_session_id TEXT"),
+            ("workspace_path", "ALTER TABLE tickets ADD COLUMN workspace_path TEXT"),
+            ("memory_md_path", "ALTER TABLE tickets ADD COLUMN memory_md_path TEXT"),
+            ("thread_session_id", "ALTER TABLE tickets ADD COLUMN thread_session_id TEXT"),
+            ("message_count", "ALTER TABLE tickets ADD COLUMN message_count INTEGER NOT NULL DEFAULT 0"),
+            ("last_summary_at_message", "ALTER TABLE tickets ADD COLUMN last_summary_at_message INTEGER NOT NULL DEFAULT 0"),
+        ]:
+            if column_name not in ticket_cols:
+                _execute(connection, ddl)
+                ticket_cols.add(column_name)
+
+    if "users" in tables:
+        user_cols = _column_names(connection, "users")
+        if "totp_secret" not in user_cols:
+            _execute(connection, "ALTER TABLE users ADD COLUMN totp_secret TEXT")
+        if "totp_enabled" not in user_cols:
+            _execute(
+                connection,
+                "ALTER TABLE users ADD COLUMN totp_enabled BOOLEAN NOT NULL DEFAULT FALSE" if is_postgres else "ALTER TABLE users ADD COLUMN totp_enabled INTEGER NOT NULL DEFAULT 0",
+            )
+        if "totp_last_used_step" not in user_cols:
+            _execute(connection, "ALTER TABLE users ADD COLUMN totp_last_used_step INTEGER")
+        if "totp_confirmed_at" not in user_cols:
+            _execute(connection, "ALTER TABLE users ADD COLUMN totp_confirmed_at TIMESTAMP" if is_postgres else "ALTER TABLE users ADD COLUMN totp_confirmed_at TEXT")
+
+    # Knowledge tables are managed outside SQLAlchemy models, so keep them here.
+    if "knowledge_connections" not in tables:
+        _execute(
+            connection,
+            """
+            CREATE TABLE IF NOT EXISTS knowledge_connections (
+                id TEXT PRIMARY KEY,
+                slug TEXT UNIQUE NOT NULL,
+                name TEXT NOT NULL,
+                connection_string_encrypted BLOB,
+                host TEXT,
+                port INTEGER,
+                database_name TEXT,
+                username TEXT,
+                ssl_mode TEXT,
+                status TEXT DEFAULT 'disconnected',
+                schema_version TEXT,
+                pgvector_version TEXT,
+                postgres_version TEXT,
+                last_health_check TIMESTAMP,
+                last_error TEXT,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            );
+            """,
+        )
+        _execute(
+            connection,
+            """
+            CREATE TABLE IF NOT EXISTS knowledge_connection_events (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                connection_id TEXT REFERENCES knowledge_connections(id) ON DELETE CASCADE,
+                event_type TEXT,
+                details TEXT,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            );
+            """,
+        )
+        _execute(connection, "CREATE INDEX IF NOT EXISTS idx_kconn_status ON knowledge_connections(status)")
+        _execute(
+            connection,
+            "CREATE INDEX IF NOT EXISTS idx_kconn_events_conn ON knowledge_connection_events(connection_id, created_at)",
+        )
+
+    if "knowledge_api_keys" not in tables:
+        _execute(
+            connection,
+            """
+            CREATE TABLE IF NOT EXISTS knowledge_api_keys (
+                id TEXT PRIMARY KEY,
+                name TEXT,
+                prefix TEXT NOT NULL,
+                token_hash TEXT NOT NULL,
+                connection_id TEXT NOT NULL,
+                space_ids TEXT NOT NULL DEFAULT '[]',
+                scopes TEXT NOT NULL DEFAULT '["read"]',
+                rate_limit_per_min INTEGER NOT NULL DEFAULT 60,
+                rate_limit_per_day INTEGER NOT NULL DEFAULT 10000,
+                created_at TEXT NOT NULL,
+                last_used_at TEXT,
+                expires_at TEXT
+            );
+            """,
+        )
+        _execute(connection, "CREATE INDEX IF NOT EXISTS idx_kak_prefix ON knowledge_api_keys(prefix)")
+
+    # Fix corrupted datetime columns that can crash SQLAlchemy on load.
+    for table_name, column_name in [("roles", "created_at"), ("users", "created_at"), ("users", "last_login")]:
+        try:
+            if column_name in _column_names(connection, table_name):
+                _execute(
+                    connection,
+                    f"UPDATE {table_name} SET {column_name} = {current_ts} WHERE {column_name} IS NOT NULL AND typeof({column_name}) != 'text'" if not is_postgres else f"UPDATE {table_name} SET {column_name} = CURRENT_TIMESTAMP WHERE {column_name} IS NOT NULL",
+                )
+                _execute(
+                    connection,
+                    f"UPDATE {table_name} SET {column_name} = {current_ts} WHERE {column_name} IS NOT NULL AND {column_name} != '' AND {column_name} NOT LIKE '____-__-__%'" if not is_postgres else f"UPDATE {table_name} SET {column_name} = CURRENT_TIMESTAMP WHERE {column_name} IS NOT NULL",
+                )
+        except Exception:
+            pass
+
+
+def downgrade_app_schema(connection) -> None:
+    """Drop the schema additions managed by upgrade_app_schema."""
+
+    dialect_name = getattr(getattr(connection, "dialect", None), "name", "sqlite")
+    is_postgres = dialect_name == "postgresql"
+
+    if is_postgres:
+        for sql in [
+            "DROP TRIGGER IF EXISTS trg_task_done_updates_goal ON goal_tasks",
+            "DROP FUNCTION IF EXISTS trg_task_done_updates_goal_fn()",
+            "DROP VIEW IF EXISTS goal_progress_v",
+            "DROP TABLE IF EXISTS knowledge_api_keys",
+            "DROP TABLE IF EXISTS knowledge_connection_events",
+            "DROP TABLE IF EXISTS knowledge_connections",
+        ]:
+            try:
+                _execute(connection, sql)
+            except Exception:
+                pass
+        return
+
+    for sql in [
+        "DROP TRIGGER IF EXISTS trg_task_done_updates_goal",
+        "DROP VIEW IF EXISTS goal_progress_v",
+        "DROP TABLE IF EXISTS knowledge_api_keys",
+        "DROP TABLE IF EXISTS knowledge_connection_events",
+        "DROP TABLE IF EXISTS knowledge_connections",
+    ]:
+        try:
+            _execute(connection, sql)
+        except Exception:
+            pass
diff --git a/dashboard/backend/session_security.py b/dashboard/backend/session_security.py
new file mode 100644
index 00000000..3205f133
--- /dev/null
+++ b/dashboard/backend/session_security.py
@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import os
+import secrets
+from datetime import datetime, timezone
+
+from flask import abort, request, session
+
+
+CSRF_SESSION_KEY = "_evonexus_csrf_token"
+CSRF_ISSUED_AT_KEY = "_evonexus_csrf_issued_at"
+CSRF_HEADER_NAME = "X-CSRF-Token"
+XHR_HEADER_NAME = "X-Requested-With"
+XHR_HEADER_VALUE = "XMLHttpRequest"
+
+
+def _rotation_minutes() -> int:
+    raw = os.environ.get("EVONEXUS_SESSION_KEY_ROTATION_MINUTES", "").strip()
+    try:
+        value = int(raw)
+    except (TypeError, ValueError):
+        value = 24 * 60
+    return value if value > 0 else 24 * 60
+
+
+def _parse_issued_at(raw: object) -> datetime | None:
+    if not raw:
+        return None
+    if isinstance(raw, datetime):
+        return raw.astimezone(timezone.utc) if raw.tzinfo else raw.replace(tzinfo=timezone.utc)
+    text = str(raw).strip()
+    if not text:
+        return None
+    try:
+        parsed = datetime.fromisoformat(text.replace("Z", "+00:00"))
+        return parsed.astimezone(timezone.utc) if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
+    except ValueError:
+        return None
+
+
+def issue_session_token(force: bool = False) -> str:
+    """Return the current per-session CSRF token, rotating it when needed."""
+
+    token = session.get(CSRF_SESSION_KEY)
+    issued_at = _parse_issued_at(session.get(CSRF_ISSUED_AT_KEY))
+    age_minutes = None
+    if issued_at is not None:
+        age_minutes = (datetime.now(timezone.utc) - issued_at).total_seconds() / 60.0
+
+    if force or not token or age_minutes is None or age_minutes >= _rotation_minutes():
+        token = secrets.token_urlsafe(32)
+        session[CSRF_SESSION_KEY] = token
+        session[CSRF_ISSUED_AT_KEY] = datetime.now(timezone.utc).isoformat()
+
+    return str(token)
+
+
+def current_session_token() -> str | None:
+    token = session.get(CSRF_SESSION_KEY)
+    return str(token) if token else None
+
+
+def attach_session_token(response):
+    token = issue_session_token(force=False)
+    response.headers[CSRF_HEADER_NAME] = token
+    expose = response.headers.get("Access-Control-Expose-Headers", "")
+    exposed = [item.strip() for item in expose.split(",") if item.strip()]
+    if CSRF_HEADER_NAME not in exposed:
+        exposed.append(CSRF_HEADER_NAME)
+    response.headers["Access-Control-Expose-Headers"] = ", ".join(exposed)
+    return response
+
+
+def require_csrf_token(req=request) -> None:
+    expected = issue_session_token(force=False)
+    provided = req.headers.get(CSRF_HEADER_NAME, "").strip()
+    if not provided or provided != expected:
+        abort(403, description="CSRF check failed: invalid or missing CSRF token.")
+
+
+def force_rotate_session_token() -> str:
+    return issue_session_token(force=True)
diff --git a/dashboard/backend/structured_logging.py b/dashboard/backend/structured_logging.py
new file mode 100644
index 00000000..d7bac813
--- /dev/null
+++ b/dashboard/backend/structured_logging.py
@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import json
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from flask import g, request
+
+
+def _json_default(value: Any):
+    if isinstance(value, Path):
+        return str(value)
+    if hasattr(value, "isoformat"):
+        try:
+            return value.isoformat()
+        except Exception:
+            pass
+    return str(value)
+
+
+def emit_json_log(level: str, event: str, **fields: Any) -> None:
+    payload = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "level": level,
+        "event": event,
+        **fields,
+    }
+    stream = sys.stderr if level.lower() in {"warning", "error", "critical"} else sys.stdout
+    print(json.dumps(payload, ensure_ascii=False, default=_json_default), file=stream, flush=True)
+
+
+def install_request_logging(app, service: str = "dashboard") -> None:
+    """Emit one structured JSON record for every API/WebSocket request."""
+
+    @app.before_request
+    def _start_request_timer():
+        if request.path.startswith("/api/") or request.path.startswith("/ws/"):
+            g._structured_started_at = time.perf_counter()
+
+    @app.after_request
+    def _log_request(response):
+        if request.path.startswith("/api/") or request.path.startswith("/ws/"):
+            started_at = getattr(g, "_structured_started_at", None)
+            duration_ms = None
+            if started_at is not None:
+                duration_ms = round((time.perf_counter() - started_at) * 1000, 1)
+            emit_json_log(
+                "info",
+                "http_request",
+                service=service,
+                method=request.method,
+                path=request.path,
+                status=response.status_code,
+                duration_ms=duration_ms,
+                remote_addr=request.headers.get("X-Forwarded-For", request.remote_addr),
+            )
+        return response
diff --git a/dashboard/backend/totp_security.py b/dashboard/backend/totp_security.py
new file mode 100644
index 00000000..4e61aee1
--- /dev/null
+++ b/dashboard/backend/totp_security.py
@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import re
+import secrets
+import struct
+import time
+import urllib.parse
+
+
+TOTP_ISSUER = "EvoNexus"
+
+
+def generate_totp_secret() -> str:
+    return base64.b32encode(secrets.token_bytes(20)).decode("ascii").rstrip("=")
+
+
+def provisioning_uri(secret: str, account_name: str, issuer: str = TOTP_ISSUER) -> str:
+    label = urllib.parse.quote(f"{issuer}:{account_name}")
+    params = urllib.parse.urlencode({
+        "secret": secret,
+        "issuer": issuer,
+        "algorithm": "SHA1",
+        "digits": 6,
+        "period": 30,
+    })
+    return f"otpauth://totp/{label}?{params}"
+
+
+def normalize_totp_code(code: str | None) -> str:
+    return re.sub(r"\s+", "", str(code or "")).strip()
+
+
+def _decode_secret(secret: str) -> bytes:
+    normalized = re.sub(r"\s+", "", secret or "").strip().upper()
+    padding = "=" * ((8 - len(normalized) % 8) % 8)
+    return base64.b32decode(normalized + padding, casefold=True)
+
+
+def _hotp(secret: str, counter: int, digits: int = 6) -> str:
+    key = _decode_secret(secret)
+    msg = struct.pack(">Q", counter)
+    digest = hmac.new(key, msg, hashlib.sha1).digest()
+    offset = digest[-1] & 0x0F
+    binary = struct.unpack(">I", digest[offset:offset + 4])[0] & 0x7FFFFFFF
+    return str(binary % (10 ** digits)).zfill(digits)
+
+
+def generate_totp_code(secret: str, *, interval: int = 30, digits: int = 6, for_time: float | None = None) -> str:
+    now = for_time if for_time is not None else time.time()
+    counter = int(now // interval)
+    return _hotp(secret, counter, digits=digits)
+
+
+def verify_totp_code(
+    secret: str,
+    code: str | None,
+    *,
+    interval: int = 30,
+    digits: int = 6,
+    window: int = 1,
+    last_used_step: int | None = None,
+    for_time: float | None = None,
+) -> dict[str, object]:
+    normalized = normalize_totp_code(code)
+    if not normalized.isdigit() or len(normalized) != digits:
+        return {"valid": False, "step": None}
+
+    now = for_time if for_time is not None else time.time()
+    current_step = int(now // interval)
+    for step in range(current_step - window, current_step + window + 1):
+        if last_used_step is not None and step <= last_used_step:
+            continue
+        if _hotp(secret, step, digits=digits) == normalized:
+            return {"valid": True, "step": step}
+    return {"valid": False, "step": None}
diff --git a/dashboard/frontend/playwright.config.ts b/dashboard/frontend/playwright.config.ts
new file mode 100644
index 00000000..bcc05795
--- /dev/null
+++ b/dashboard/frontend/playwright.config.ts
@@ -0,0 +1,26 @@
+import { defineConfig } from '@playwright/test'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const frontendRoot = path.dirname(fileURLToPath(import.meta.url))
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  timeout: 60_000,
+  expect: { timeout: 10_000 },
+  use: {
+    baseURL: 'http://127.0.0.1:8080',
+    trace: 'on-first-retry',
+  },
+  webServer: {
+    command: 'node scripts/start-e2e-server.mjs',
+    cwd: frontendRoot,
+    url: 'http://127.0.0.1:8080',
+    timeout: 180_000,
+    reuseExistingServer: false,
+    env: {
+      ...process.env,
+      EVONEXUS_PORT: '8080',
+    },
+  },
+})
diff --git a/dashboard/frontend/public/manifest.webmanifest b/dashboard/frontend/public/manifest.webmanifest
new file mode 100644
index 00000000..f4d40ccd
--- /dev/null
+++ b/dashboard/frontend/public/manifest.webmanifest
@@ -0,0 +1,29 @@
+{
+  "name": "Evo Workspace",
+  "short_name": "EvoNexus",
+  "start_url": "/",
+  "scope": "/",
+  "display": "standalone",
+  "background_color": "#0C111D",
+  "theme_color": "#0C111D",
+  "description": "EvoNexus dashboard and agent workspace.",
+  "icons": [
+    {
+      "src": "/favicon.png",
+      "sizes": "192x192",
+      "type": "image/png"
+    },
+    {
+      "src": "/favicon.png",
+      "sizes": "512x512",
+      "type": "image/png"
+    },
+    {
+      "src": "/EVO_NEXUS.webp",
+      "sizes": "512x512",
+      "type": "image/webp",
+      "purpose": "any"
+    }
+  ]
+}
+
diff --git a/dashboard/frontend/public/sw.js b/dashboard/frontend/public/sw.js
new file mode 100644
index 00000000..0ea13939
--- /dev/null
+++ b/dashboard/frontend/public/sw.js
@@ -0,0 +1,65 @@
+const CACHE_NAME = 'evonexus-shell-v1'
+const PRECACHE_URLS = [
+  '/',
+  '/index.html',
+  '/favicon.png',
+  '/EVO_NEXUS.webp',
+  '/manifest.webmanifest',
+]
+
+self.addEventListener('install', (event) => {
+  event.waitUntil(
+    caches.open(CACHE_NAME).then((cache) => cache.addAll(PRECACHE_URLS)).then(() => self.skipWaiting()),
+  )
+})
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil(
+    caches.keys().then((keys) =>
+      Promise.all(keys.map((key) => (key === CACHE_NAME ? null : caches.delete(key)))).then(() => self.clients.claim()),
+    ),
+  )
+})
+
+async function cacheFirst(request) {
+  const cache = await caches.open(CACHE_NAME)
+  const cached = await cache.match(request)
+  if (cached) return cached
+
+  const response = await fetch(request)
+  if (response && response.ok) {
+    cache.put(request, response.clone())
+  }
+  return response
+}
+
+async function networkFirstNavigation(request) {
+  const cache = await caches.open(CACHE_NAME)
+  try {
+    const response = await fetch(request)
+    if (response && response.ok) {
+      cache.put('/index.html', response.clone())
+    }
+    return response
+  } catch {
+    const cachedIndex = await cache.match('/index.html')
+    return cachedIndex || cache.match('/')
+  }
+}
+
+self.addEventListener('fetch', (event) => {
+  const request = event.request
+  if (request.method !== 'GET') return
+
+  const url = new URL(request.url)
+  if (url.origin !== self.location.origin) return
+  if (url.pathname.startsWith('/api/') || url.pathname.startsWith('/terminal/')) return
+
+  if (request.mode === 'navigate') {
+    event.respondWith(networkFirstNavigation(request))
+    return
+  }
+
+  event.respondWith(cacheFirst(request))
+})
+
diff --git a/dashboard/frontend/scripts/start-e2e-server.mjs b/dashboard/frontend/scripts/start-e2e-server.mjs
new file mode 100644
index 00000000..2f4a4dfc
--- /dev/null
+++ b/dashboard/frontend/scripts/start-e2e-server.mjs
@@ -0,0 +1,48 @@
+import { execFileSync, spawn } from 'node:child_process'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url))
+const frontendRoot = path.resolve(scriptDir, '..')
+const repoRoot = path.resolve(frontendRoot, '..', '..')
+
+function sqliteUrl(filePath) {
+  return `sqlite:///${path.resolve(filePath).replace(/\\/g, '/')}`
+}
+
+const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'evonexus-e2e-'))
+const databasePath = path.join(tempDir, 'dashboard.db')
+
+execFileSync('npm', ['run', 'build'], {
+  cwd: frontendRoot,
+  stdio: 'inherit',
+  env: process.env,
+  shell: true,
+})
+
+const child = spawn(process.platform === 'win32' ? 'python' : 'python3', ['dashboard/backend/app.py'], {
+  cwd: repoRoot,
+  stdio: 'inherit',
+  env: {
+    ...process.env,
+    SQLALCHEMY_DATABASE_URI: sqliteUrl(databasePath),
+    EVONEXUS_SECRET_KEY: process.env.EVONEXUS_SECRET_KEY || 'e2e-secret-key',
+    EVONEXUS_PORT: process.env.EVONEXUS_PORT || '8080',
+    CORS_ALLOWED_ORIGINS: 'http://127.0.0.1:8080',
+    EVONEXUS_ENV: 'development',
+  },
+})
+
+const shutdown = () => {
+  if (!child.killed) {
+    child.kill('SIGTERM')
+  }
+}
+
+process.on('SIGINT', shutdown)
+process.on('SIGTERM', shutdown)
+child.on('exit', (code, signal) => {
+  process.exit(code ?? (signal ? 1 : 0))
+})
diff --git a/dashboard/frontend/src/components/CommandPalette.tsx b/dashboard/frontend/src/components/CommandPalette.tsx
new file mode 100644
index 00000000..35187155
--- /dev/null
+++ b/dashboard/frontend/src/components/CommandPalette.tsx
@@ -0,0 +1,341 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type ReactNode,
+} from 'react'
+import { useLocation, useNavigate, type NavigateFunction } from 'react-router-dom'
+import { useTranslation } from 'react-i18next'
+import { Moon, RefreshCw, Search, Sun, X, type LucideIcon } from 'lucide-react'
+import { useAuth } from '../context/AuthContext'
+import { useTheme } from '../context/ThemeContext'
+import { DOCS_NAV_ITEM, getVisibleNavGroups, NAV_GROUPS, type NavItem } from '../lib/navigation'
+
+interface CommandPaletteContextValue {
+  isOpen: boolean
+  openCommandPalette: () => void
+  closeCommandPalette: () => void
+  toggleCommandPalette: () => void
+}
+
+interface PaletteCommand {
+  id: string
+  label: string
+  description: string
+  group: string
+  icon: LucideIcon
+  action: () => void
+  keywords: string[]
+}
+
+const CommandPaletteContext = createContext<CommandPaletteContextValue | null>(null)
+
+export function useCommandPalette() {
+  const ctx = useContext(CommandPaletteContext)
+  if (!ctx) {
+    throw new Error('useCommandPalette must be used within <CommandPaletteProvider>')
+  }
+  return ctx
+}
+
+function commandLabel(item: NavItem, t: (key: string) => string) {
+  return t(`nav.${item.labelKey}`)
+}
+
+function buildRouteCommands(
+  hasPermission: (resource: string, action: string) => boolean,
+  t: (key: string) => string,
+  navigate: NavigateFunction,
+  close: () => void,
+): PaletteCommand[] {
+  const visibleGroups = getVisibleNavGroups(hasPermission)
+  const byKey = new Map(visibleGroups.map((group) => [group.key, group]))
+  const commands: PaletteCommand[] = []
+
+  for (const group of NAV_GROUPS) {
+    const visible = byKey.get(group.key)
+    if (!visible) continue
+
+    for (const item of visible.items) {
+      commands.push({
+        id: `route:${item.to}`,
+        label: commandLabel(item, t),
+        description: item.to === '/' ? 'Go to the main dashboard' : item.to,
+        group: t(`nav.groups.${group.key}`),
+        icon: item.icon,
+        keywords: [item.to, group.key, commandLabel(item, t), t(`nav.groups.${group.key}`)],
+        action: () => {
+          close()
+          navigate(item.to)
+        },
+      })
+    }
+  }
+
+  commands.push({
+    id: `route:${DOCS_NAV_ITEM.to}`,
+    label: t('nav.docs'),
+    description: 'Open the public documentation view',
+    group: 'Public',
+    icon: DOCS_NAV_ITEM.icon,
+    keywords: [DOCS_NAV_ITEM.to, 'docs', 'documentation'],
+    action: () => {
+      close()
+      navigate(DOCS_NAV_ITEM.to)
+    },
+  })
+
+  return commands
+}
+
+export function CommandPaletteProvider({ children }: { children: ReactNode }) {
+  const [isOpen, setIsOpen] = useState(false)
+
+  const openCommandPalette = useCallback(() => setIsOpen(true), [])
+  const closeCommandPalette = useCallback(() => setIsOpen(false), [])
+  const toggleCommandPalette = useCallback(() => setIsOpen((prev) => !prev), [])
+
+  useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent) => {
+      const key = event.key.toLowerCase()
+      if ((event.metaKey || event.ctrlKey) && key === 'k') {
+        event.preventDefault()
+        setIsOpen(true)
+      }
+      if (event.key === 'Escape') {
+        setIsOpen(false)
+      }
+    }
+
+    window.addEventListener('keydown', onKeyDown)
+    return () => window.removeEventListener('keydown', onKeyDown)
+  }, [])
+
+  return (
+    <CommandPaletteContext.Provider
+      value={{
+        isOpen,
+        openCommandPalette,
+        closeCommandPalette,
+        toggleCommandPalette,
+      }}
+    >
+      {children}
+      <CommandPaletteDialog />
+    </CommandPaletteContext.Provider>
+  )
+}
+
+function CommandPaletteDialog() {
+  const { isOpen, closeCommandPalette } = useCommandPalette()
+  const { theme, toggleTheme } = useTheme()
+  const { hasPermission } = useAuth()
+  const { t } = useTranslation()
+  const navigate = useNavigate()
+  const location = useLocation()
+  const inputRef = useRef<HTMLInputElement>(null)
+  const [query, setQuery] = useState('')
+  const [selectedIndex, setSelectedIndex] = useState(0)
+
+  useEffect(() => {
+    if (!isOpen) {
+      setQuery('')
+      setSelectedIndex(0)
+      return
+    }
+
+    const prevOverflow = document.body.style.overflow
+    document.body.style.overflow = 'hidden'
+
+    const timer = window.setTimeout(() => {
+      inputRef.current?.focus()
+      inputRef.current?.select()
+    }, 0)
+
+    return () => {
+      window.clearTimeout(timer)
+      document.body.style.overflow = prevOverflow
+    }
+  }, [isOpen])
+
+  const commands = useMemo(() => {
+    const routeCommands = buildRouteCommands(hasPermission, t, navigate, closeCommandPalette)
+    const actionCommands: PaletteCommand[] = [
+      {
+        id: 'action:theme',
+        label: theme === 'dark' ? 'Switch to light theme' : 'Switch to dark theme',
+        description: 'Toggle the dashboard appearance',
+        group: 'Shell',
+        icon: theme === 'dark' ? Sun : Moon,
+        keywords: ['theme', 'dark', 'light', 'appearance'],
+        action: () => {
+          toggleTheme()
+          closeCommandPalette()
+        },
+      },
+      {
+        id: 'action:reload',
+        label: 'Reload app',
+        description: 'Refresh the current page',
+        group: 'Shell',
+        icon: RefreshCw,
+        keywords: ['reload', 'refresh', 'restart'],
+        action: () => window.location.reload(),
+      },
+    ]
+
+    return [...actionCommands, ...routeCommands]
+  }, [closeCommandPalette, hasPermission, navigate, t, theme, toggleTheme])
+
+  const filteredCommands = useMemo(() => {
+    const term = query.trim().toLowerCase()
+    if (!term) return commands
+    return commands.filter((command) => {
+      const haystack = [command.label, command.description, command.group, ...command.keywords].join(' ').toLowerCase()
+      return haystack.includes(term)
+    })
+  }, [commands, query])
+
+  useEffect(() => {
+    setSelectedIndex((current) => {
+      if (filteredCommands.length === 0) return 0
+      return Math.min(current, filteredCommands.length - 1)
+    })
+  }, [filteredCommands.length])
+
+  if (!isOpen) return null
+
+  const grouped = filteredCommands.reduce<Record<string, PaletteCommand[]>>((acc, command) => {
+    const bucket = acc[command.group] ?? []
+    bucket.push(command)
+    acc[command.group] = bucket
+    return acc
+  }, {})
+
+  const groupOrder = Object.keys(grouped)
+  const flatCommands = groupOrder.flatMap((group) => grouped[group])
+
+  const runSelected = () => {
+    const command = flatCommands[selectedIndex]
+    if (!command) return
+    command.action()
+  }
+
+  const handleKeyDown = (event: ReactKeyboardEvent<HTMLInputElement>) => {
+    if (event.key === 'ArrowDown') {
+      event.preventDefault()
+      setSelectedIndex((current) => (flatCommands.length === 0 ? 0 : (current + 1) % flatCommands.length))
+      return
+    }
+
+    if (event.key === 'ArrowUp') {
+      event.preventDefault()
+      setSelectedIndex((current) => (flatCommands.length === 0 ? 0 : (current - 1 + flatCommands.length) % flatCommands.length))
+      return
+    }
+
+    if (event.key === 'Enter') {
+      event.preventDefault()
+      runSelected()
+      return
+    }
+
+    if (event.key === 'Escape') {
+      event.preventDefault()
+      closeCommandPalette()
+    }
+  }
+
+  return (
+    <div className="fixed inset-0 z-[120] flex items-start justify-center bg-black/55 px-4 py-10 backdrop-blur-sm">
+      <button
+        type="button"
+        aria-label="Close command palette"
+        className="absolute inset-0 cursor-default"
+        onClick={closeCommandPalette}
+      />
+
+      <div className="relative z-[121] w-full max-w-2xl overflow-hidden rounded-3xl border border-white/10 bg-[color:var(--bg-card)] shadow-[0_24px_80px_rgba(0,0,0,0.5)]">
+        <div className="flex items-center gap-3 border-b border-[color:var(--border)] px-4 py-4">
+          <Search size={16} className="shrink-0 text-[color:var(--text-muted)]" />
+          <input
+            ref={inputRef}
+            value={query}
+            onChange={(event) => {
+              setQuery(event.target.value)
+              setSelectedIndex(0)
+            }}
+            onKeyDown={handleKeyDown}
+            placeholder={`Search current page, routes, or actions... (${location.pathname})`}
+            className="w-full bg-transparent text-sm text-[color:var(--text-primary)] outline-none placeholder:text-[color:var(--text-muted)]"
+          />
+          <button
+            type="button"
+            onClick={closeCommandPalette}
+            className="inline-flex h-8 w-8 items-center justify-center rounded-lg text-[color:var(--text-muted)] transition-colors hover:bg-white/5 hover:text-[color:var(--text-primary)]"
+            aria-label="Close"
+          >
+            <X size={16} />
+          </button>
+        </div>
+
+        <div className="max-h-[60vh] overflow-y-auto p-2">
+          {flatCommands.length === 0 ? (
+            <div className="px-4 py-10 text-center text-sm text-[color:var(--text-muted)]">
+              No matches found
+            </div>
+          ) : (
+            groupOrder.map((group) => (
+              <div key={group} className="mb-3 last:mb-0">
+                <div className="px-3 pb-2 text-[10px] font-semibold uppercase tracking-[0.18em] text-[color:var(--text-muted)]">
+                  {group}
+                </div>
+                <div className="space-y-1">
+                  {grouped[group].map((command) => {
+                    const index = flatCommands.findIndex((item) => item.id === command.id)
+                    const active = index === selectedIndex
+
+                    return (
+                      <button
+                        key={command.id}
+                        type="button"
+                        onMouseEnter={() => setSelectedIndex(index)}
+                        onClick={command.action}
+                        className={`flex w-full items-center gap-3 rounded-2xl border px-3 py-3 text-left transition-colors ${
+                          active
+                            ? 'border-[color:var(--border-accent)] bg-[color:var(--surface-active)]'
+                            : 'border-transparent hover:bg-white/5'
+                        }`}
+                      >
+                        <span className="flex h-10 w-10 shrink-0 items-center justify-center rounded-xl bg-[color:var(--surface-hover)] text-[color:var(--border-accent)]">
+                          <command.icon size={16} />
+                        </span>
+                        <span className="min-w-0 flex-1">
+                          <span className="block truncate text-sm font-medium text-[color:var(--text-primary)]">
+                            {command.label}
+                          </span>
+                          <span className="block truncate text-xs text-[color:var(--text-muted)]">
+                            {command.description}
+                          </span>
+                        </span>
+                        <span className="text-[10px] uppercase tracking-[0.16em] text-[color:var(--text-muted)]">
+                          {active ? 'Selected' : command.group}
+                        </span>
+                      </button>
+                    )
+                  })}
+                </div>
+              </div>
+            ))
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
+
diff --git a/dashboard/frontend/src/components/agent-chat/ChatBlocks.tsx b/dashboard/frontend/src/components/agent-chat/ChatBlocks.tsx
new file mode 100644
index 00000000..7ca3050c
--- /dev/null
+++ b/dashboard/frontend/src/components/agent-chat/ChatBlocks.tsx
@@ -0,0 +1,303 @@
+import { useState } from 'react'
+import {
+  Ban,
+  Check,
+  CheckCircle2,
+  ChevronDown,
+  ChevronRight,
+  Edit2,
+  FileCode,
+  FileText,
+  ShieldAlert,
+  Terminal as TermIcon,
+} from 'lucide-react'
+import { AgentAvatar } from '../AgentAvatar'
+
+export function TypingIndicator({ accentColor, isThinking }: { accentColor: string; isThinking?: boolean }) {
+  return (
+    <div className="flex items-center gap-2 py-1">
+      <div className="flex items-center gap-1">
+        {[0, 1, 2].map((i) => (
+          <span
+            key={i}
+            className="inline-block h-1.5 w-1.5 rounded-full"
+            style={{
+              backgroundColor: accentColor,
+              animation: 'chat-bounce 1.4s ease-in-out infinite',
+              animationDelay: `${i * 0.16}s`,
+            }}
+          />
+        ))}
+      </div>
+      <span className="text-[10px] text-[#667085]" style={{ animation: 'chat-pulse 2s ease-in-out infinite' }}>
+        {isThinking ? 'Thinking...' : 'Typing...'}
+      </span>
+    </div>
+  )
+}
+
+export function AgentInputToggle({ parsedInput, rawInput }: { parsedInput: any; rawInput: string }) {
+  const [showInput, setShowInput] = useState(false)
+  return (
+    <div className="border-t border-[#21262d]/50">
+      <button
+        onClick={() => setShowInput((value) => !value)}
+        className="flex w-full items-center gap-1.5 px-3 py-1.5 text-[10px] text-[#667085] transition-colors hover:text-[#8b949e]"
+      >
+        {showInput ? <ChevronDown size={10} /> : <ChevronRight size={10} />}
+        View input
+      </button>
+      {showInput && (
+        <pre className="max-h-48 overflow-y-auto px-3 pb-2 font-mono text-[11px] whitespace-pre-wrap break-all text-[#8b949e]">
+          {parsedInput ? JSON.stringify(parsedInput, null, 2) : rawInput}
+        </pre>
+      )}
+    </div>
+  )
+}
+
+export function TypingIndicatorMini({ accentColor }: { accentColor: string }) {
+  return (
+    <span className="flex items-center gap-0.5">
+      {[0, 1, 2].map((i) => (
+        <span
+          key={i}
+          className="inline-block h-1 w-1 rounded-full"
+          style={{
+            backgroundColor: accentColor,
+            opacity: 0.7,
+            animation: 'chat-bounce 1.4s ease-in-out infinite',
+            animationDelay: `${i * 0.16}s`,
+          }}
+        />
+      ))}
+    </span>
+  )
+}
+
+export function ToolCard({ block, accentColor }: { block: any; accentColor: string }) {
+  const [open, setOpen] = useState(false)
+
+  let parsedInput: any = null
+  try {
+    parsedInput = JSON.parse(block.input)
+  } catch {}
+
+  const isAgentTool = block.toolName === 'Agent' || block.toolName === 'SendMessage'
+  const subagentName = parsedInput?.subagent_type || parsedInput?.name || parsedInput?.to || ''
+  const subagentDesc = parsedInput?.description || parsedInput?.summary || block.subagentType || ''
+
+  if (isAgentTool) {
+    const isRunning = block.subagentStatus === 'running'
+    const isDone = block.done || block.subagentStatus === 'completed' || block.subagentStatus === 'failed'
+    const subagentTools = block.subagentTools || []
+    const toolCount = subagentTools.length
+
+    const getToolIcon = (toolName: string) => {
+      if (toolName === 'Bash') return <TermIcon size={11} className="flex-shrink-0 text-[#667085]" />
+      if (toolName === 'Read') return <FileText size={11} className="flex-shrink-0 text-[#667085]" />
+      if (toolName === 'Edit' || toolName === 'Write') return <Edit2 size={11} className="flex-shrink-0 text-[#667085]" />
+      return <FileCode size={11} className="flex-shrink-0 text-[#667085]" />
+    }
+
+    return (
+      <div className="overflow-hidden rounded-lg border border-[#21262d]">
+        <button
+          onClick={() => setOpen((value) => !value)}
+          className="flex w-full items-center gap-2.5 bg-[#161b22] px-3 py-2.5 text-[12px] transition-colors hover:bg-[#1c2333]"
+        >
+          {open ? <ChevronDown size={12} className="text-[#667085]" /> : <ChevronRight size={12} className="text-[#667085]" />}
+
+          {(() => {
+            const isUuid = /^[0-9a-f]{8,}$/i.test(subagentName)
+            const displayName = isUuid ? '' : subagentName
+            return displayName ? (
+              <AgentAvatar name={displayName.replace('custom-', '')} size={20} />
+            ) : (
+              <FileCode size={13} style={{ color: accentColor }} />
+            )
+          })()}
+
+          <span className="font-medium text-[#e6edf3]">
+            {(() => {
+              const isUuid = /^[0-9a-f]{8,}$/i.test(subagentName)
+              return isUuid ? (block.toolName === 'SendMessage' ? 'SendMessage' : 'Agent') : subagentName ? `@${subagentName}` : block.toolName
+            })()}
+          </span>
+
+          {subagentDesc && <span className="max-w-[300px] truncate text-[11px] text-[#8b949e]">{subagentDesc}</span>}
+
+          <span className="ml-auto flex items-center gap-2 flex-shrink-0">
+            {toolCount > 0 && (
+              <span className="text-[10px] tabular-nums text-[#667085]">
+                {toolCount} {toolCount === 1 ? 'tool' : 'tools'}
+              </span>
+            )}
+            {isRunning && block.subagentSummary && (
+              <span className="max-w-[200px] truncate text-[10px] text-[#667085]" style={{ animation: 'chat-pulse 2s ease-in-out infinite' }}>
+                {block.subagentSummary}
+              </span>
+            )}
+            {isDone ? (
+              <CheckCircle2 size={13} className={block.subagentStatus === 'failed' ? 'text-[#ef4444]' : 'text-[#22C55E]'} />
+            ) : (
+              <TypingIndicatorMini accentColor={accentColor} />
+            )}
+          </span>
+        </button>
+
+        {open && (
+          <div className="border-t border-[#21262d] bg-[#0d1117]">
+            <div className="max-h-80 overflow-y-auto">
+              {subagentTools.length === 0 ? (
+                <div className="px-3 py-2 text-[11px] text-[#667085]">No tools yet</div>
+              ) : (
+                subagentTools.map((tool: any, index: number) => {
+                  let inputPreview = ''
+                  try {
+                    const parsed = JSON.parse(tool.input)
+                    inputPreview = (parsed.command || parsed.file_path || parsed.path || parsed.pattern || parsed.description || tool.input).slice(0, 60)
+                  } catch {
+                    inputPreview = tool.input.slice(0, 60)
+                  }
+
+                  return (
+                    <div
+                      key={tool.toolUseId || index}
+                      className="flex items-center gap-2 border-t border-[#21262d]/50 px-3 py-1.5 text-[11px] first:border-t-0"
+                    >
+                      {getToolIcon(tool.toolName)}
+                      <span className="flex-shrink-0 font-medium text-[#8b949e]">{tool.toolName}</span>
+                      {inputPreview && <span className="truncate text-[#667085]">{inputPreview}</span>}
+                    </div>
+                  )
+                })
+              )}
+            </div>
+            {block.input && <AgentInputToggle parsedInput={parsedInput} rawInput={block.input} />}
+          </div>
+        )}
+      </div>
+    )
+  }
+
+  if (block.toolName === 'TodoWrite' && Array.isArray(parsedInput?.todos)) {
+    const todos: Array<{ content: string; status: string; priority?: string; id?: string }> = parsedInput.todos
+    const completedCount = todos.filter((todo) => todo.status === 'completed').length
+
+    return (
+      <div className="overflow-hidden rounded-lg border border-[#21262d]">
+        <button
+          onClick={() => setOpen((value) => !value)}
+          className="flex w-full items-center gap-2 bg-[#161b22] px-3 py-2 text-[12px] transition-colors hover:bg-[#1c2333]"
+        >
+          {open ? <ChevronDown size={12} className="text-[#667085]" /> : <ChevronRight size={12} className="text-[#667085]" />}
+          <CheckCircle2 size={13} style={{ color: accentColor }} />
+          <span className="font-medium text-[#e6edf3]">TodoWrite</span>
+          <span className="text-[11px] text-[#667085]">{completedCount}/{todos.length} done</span>
+          <span className="ml-auto flex-shrink-0">
+            {block.done ? <CheckCircle2 size={13} className="text-[#22C55E]" /> : <TypingIndicatorMini accentColor={accentColor} />}
+          </span>
+        </button>
+
+        <div className="space-y-1 border-t border-[#21262d] bg-[#0d1117] px-3 py-2">
+          {todos.map((todo, index) => {
+            const isPending = todo.status === 'pending'
+            const isInProgress = todo.status === 'in_progress'
+            const isCompleted = todo.status === 'completed'
+            const icon = isPending ? '○' : isInProgress ? '◐' : '●'
+            return (
+              <div key={index} className="flex items-start gap-2 text-[12px]">
+                <span className="mt-0.5 flex-shrink-0 font-mono text-[13px]" style={{ color: isPending ? '#667085' : '#00FFA7' }}>
+                  {icon}
+                </span>
+                <span className={isCompleted ? 'opacity-60 line-through' : ''} style={{ color: isPending ? '#8b949e' : isCompleted ? '#8b949e' : '#e6edf3' }}>
+                  {todo.content}
+                </span>
+              </div>
+            )
+          })}
+        </div>
+      </div>
+    )
+  }
+
+  const displayInfo = parsedInput
+    ? (parsedInput.command || parsedInput.file_path || parsedInput.path || parsedInput.pattern || parsedInput.description || '')
+    : ''
+
+  return (
+    <div className="overflow-hidden rounded-lg border border-[#21262d]">
+      <button
+        onClick={() => setOpen((value) => !value)}
+        className="flex w-full items-center gap-2 bg-[#161b22] px-3 py-2 text-[12px] transition-colors hover:bg-[#1c2333]"
+      >
+        {open ? <ChevronDown size={12} className="text-[#667085]" /> : <ChevronRight size={12} className="text-[#667085]" />}
+        <FileCode size={13} style={{ color: accentColor }} />
+        <span className="font-medium text-[#e6edf3]">{block.toolName}</span>
+        {displayInfo && <span className="max-w-[300px] truncate font-mono text-[11px] text-[#667085]">{displayInfo}</span>}
+        <span className="ml-auto flex-shrink-0">
+          {block.done ? <CheckCircle2 size={13} className="text-[#22C55E]" /> : <TypingIndicatorMini accentColor={accentColor} />}
+        </span>
+      </button>
+
+      {open && block.input && (
+        <div className="border-t border-[#21262d] bg-[#0d1117] px-3 py-2">
+          <pre className="max-h-48 overflow-y-auto whitespace-pre-wrap break-all font-mono text-[11px] text-[#8b949e]">
+            {parsedInput ? JSON.stringify(parsedInput, null, 2) : block.input}
+          </pre>
+        </div>
+      )}
+    </div>
+  )
+}
+
+export function ApprovalCard({ req, accentColor, onAllow, onDeny }: { req: any; accentColor: string; onAllow: () => void; onDeny: () => void }) {
+  let summary = ''
+  const inp = req.input as any
+
+  if (req.toolName === 'Bash') {
+    summary = inp?.command ? String(inp.command).slice(0, 120) : ''
+  } else if (req.toolName === 'Write') {
+    const lines = inp?.content ? String(inp.content).split('\n').slice(0, 5).join('\n') : ''
+    summary = inp?.file_path ? `${inp.file_path}${lines ? '\n' + lines : ''}` : lines
+  } else if (req.toolName === 'Edit') {
+    summary = inp?.file_path ? String(inp.file_path) : ''
+  } else if (req.toolName === 'Agent') {
+    const agentName = inp?.subagent_type || inp?.agent || ''
+    const prompt = inp?.prompt || inp?.description || ''
+    summary = agentName ? `@${agentName}${prompt ? ' — ' + String(prompt).slice(0, 80) : ''}` : String(prompt).slice(0, 100)
+  }
+  if (!summary && req.title) summary = req.title
+
+  return (
+    <div className="flex items-start gap-3 rounded-lg border border-[#F59E0B30] bg-[#161b22] px-3 py-2.5">
+      <ShieldAlert size={14} className="mt-0.5 flex-shrink-0" style={{ color: '#F59E0B' }} />
+      <div className="min-w-0 flex-1">
+        <div className="mb-0.5 flex items-center gap-2">
+          <span className="text-[11px] font-semibold text-[#e6edf3]">{req.toolName}</span>
+          {summary && <span className="max-w-[260px] truncate font-mono text-[10px] text-[#8b949e]">{summary}</span>}
+        </div>
+        {req.description && <p className="truncate text-[10px] text-[#667085]">{req.description}</p>}
+      </div>
+      <div className="flex flex-shrink-0 items-center gap-1.5">
+        <button
+          onClick={onAllow}
+          className="flex items-center gap-1 rounded-md border px-2.5 py-1 text-[11px] font-medium transition-colors"
+          style={{ background: `${accentColor}20`, color: accentColor, borderColor: `${accentColor}40` }}
+        >
+          <Check size={11} />
+          Allow
+        </button>
+        <button
+          onClick={onDeny}
+          className="flex items-center gap-1 rounded-md border px-2.5 py-1 text-[11px] font-medium transition-colors hover:bg-white/5"
+          style={{ background: 'transparent', color: '#8b949e', borderColor: '#21262d' }}
+        >
+          <Ban size={11} />
+          Deny
+        </button>
+      </div>
+    </div>
+  )
+}
diff --git a/dashboard/frontend/src/context/ThemeContext.tsx b/dashboard/frontend/src/context/ThemeContext.tsx
new file mode 100644
index 00000000..b94a2d8c
--- /dev/null
+++ b/dashboard/frontend/src/context/ThemeContext.tsx
@@ -0,0 +1,52 @@
+import { createContext, useCallback, useContext, useEffect, useState, type ReactNode } from 'react'
+import { applyTheme, persistTheme, resolveInitialTheme, type ThemeMode } from '../lib/theme'
+
+interface ThemeContextValue {
+  theme: ThemeMode
+  isDark: boolean
+  isLight: boolean
+  setTheme: (theme: ThemeMode) => void
+  toggleTheme: () => void
+}
+
+const ThemeContext = createContext<ThemeContextValue | null>(null)
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  const [theme, setThemeState] = useState<ThemeMode>(() => resolveInitialTheme())
+
+  useEffect(() => {
+    applyTheme(theme)
+  }, [theme])
+
+  const setTheme = useCallback((nextTheme: ThemeMode) => {
+    persistTheme(nextTheme)
+    setThemeState(nextTheme)
+  }, [])
+
+  const toggleTheme = useCallback(() => {
+    setTheme(theme === 'dark' ? 'light' : 'dark')
+  }, [setTheme, theme])
+
+  return (
+    <ThemeContext.Provider
+      value={{
+        theme,
+        isDark: theme === 'dark',
+        isLight: theme === 'light',
+        setTheme,
+        toggleTheme,
+      }}
+    >
+      {children}
+    </ThemeContext.Provider>
+  )
+}
+
+export function useTheme() {
+  const ctx = useContext(ThemeContext)
+  if (!ctx) {
+    throw new Error('useTheme must be used within <ThemeProvider>')
+  }
+  return ctx
+}
+
diff --git a/dashboard/frontend/src/lib/navigation.ts b/dashboard/frontend/src/lib/navigation.ts
new file mode 100644
index 00000000..196df408
--- /dev/null
+++ b/dashboard/frontend/src/lib/navigation.ts
@@ -0,0 +1,136 @@
+import type { LucideIcon } from 'lucide-react'
+import {
+  Activity,
+  BookOpen,
+  Bot,
+  BarChart3,
+  Brain,
+  Calendar,
+  CalendarClock,
+  Cpu,
+  Database,
+  DollarSign,
+  FolderOpen,
+  HardDriveDownload,
+  Heart,
+  Layout,
+  LayoutDashboard,
+  Library,
+  Monitor,
+  Plug,
+  Puzzle,
+  ScrollText,
+  Settings,
+  Share2,
+  Shield,
+  Target,
+  Ticket,
+  Users,
+  Webhook,
+  Clock,
+  Zap,
+} from 'lucide-react'
+
+export interface NavItem {
+  to: string
+  labelKey: string
+  icon: LucideIcon
+  resource: string | null
+  desktopOnly?: boolean
+}
+
+export interface NavGroup {
+  key: string
+  collapsible: boolean
+  adminOnly?: boolean
+  items: NavItem[]
+}
+
+export const NAV_GROUPS: NavGroup[] = [
+  {
+    key: 'main',
+    collapsible: false,
+    items: [
+      { to: '/', labelKey: 'overview', icon: LayoutDashboard, resource: null },
+    ],
+  },
+  {
+    key: 'operations',
+    collapsible: true,
+    items: [
+      { to: '/agents', labelKey: 'agents', icon: Bot, resource: 'agents' },
+      { to: '/skills', labelKey: 'skills', icon: Zap, resource: 'skills' },
+      { to: '/routines', labelKey: 'routines', icon: Clock, resource: 'routines' },
+      { to: '/tasks', labelKey: 'tasks', icon: CalendarClock, resource: 'tasks' },
+      { to: '/triggers', labelKey: 'triggers', icon: Webhook, resource: 'triggers' },
+      { to: '/heartbeats', labelKey: 'heartbeats', icon: Heart, resource: 'heartbeats' },
+      { to: '/activity', labelKey: 'activity', icon: Activity, resource: 'scheduler' },
+      { to: '/goals', labelKey: 'goals', icon: Target, resource: 'goals' },
+      { to: '/topics', labelKey: 'issues', icon: Ticket, resource: 'tickets' },
+      { to: '/templates', labelKey: 'templates', icon: Layout, resource: 'templates' },
+    ],
+  },
+  {
+    key: 'data',
+    collapsible: true,
+    items: [
+      { to: '/workspace', labelKey: 'workspace', icon: FolderOpen, resource: 'workspace' },
+      { to: '/shares', labelKey: 'shareLinks', icon: Share2, resource: 'workspace' },
+      { to: '/memory', labelKey: 'memory', icon: Brain, resource: 'memory' },
+      { to: '/mempalace', labelKey: 'mempalace', icon: Library, resource: 'mempalace' },
+      { to: '/knowledge', labelKey: 'knowledge', icon: Database, resource: 'knowledge' },
+      { to: '/costs', labelKey: 'costs', icon: DollarSign, resource: 'costs' },
+    ],
+  },
+  {
+    key: 'system',
+    collapsible: true,
+    items: [
+      { to: '/settings', labelKey: 'settings', icon: Settings, resource: 'config' },
+      { to: '/systems', labelKey: 'systems', icon: Monitor, resource: 'systems' },
+      { to: '/observability', labelKey: 'observability', icon: BarChart3, resource: 'systems' },
+      { to: '/providers', labelKey: 'providers', icon: Cpu, resource: 'config' },
+      { to: '/plugins', labelKey: 'plugins', icon: Puzzle, resource: 'config' },
+      { to: '/integrations', labelKey: 'integrations', icon: Plug, resource: 'integrations' },
+      { to: '/scheduler', labelKey: 'scheduler', icon: Calendar, resource: 'scheduler' },
+      { to: '/backups', labelKey: 'backups', icon: HardDriveDownload, resource: 'config' },
+    ],
+  },
+  {
+    key: 'admin',
+    collapsible: true,
+    adminOnly: true,
+    items: [
+      { to: '/users', labelKey: 'users', icon: Users, resource: 'users' },
+      { to: '/roles', labelKey: 'roles', icon: Shield, resource: 'users' },
+      { to: '/audit', labelKey: 'audit', icon: ScrollText, resource: 'audit' },
+    ],
+  },
+]
+
+export const DOCS_NAV_ITEM: NavItem = {
+  to: '/docs',
+  labelKey: 'docs',
+  icon: BookOpen,
+  resource: null,
+}
+
+export function getVisibleNavGroups(hasPermission: (resource: string, action: string) => boolean): NavGroup[] {
+  return NAV_GROUPS
+    .map((group) => {
+      const items = group.items.filter((item) => item.resource === null || hasPermission(item.resource, 'view'))
+      if (items.length === 0) return null
+
+      if (group.adminOnly) {
+        const hasAnyAdmin = group.items.some((item) => item.resource && hasPermission(item.resource, 'view'))
+        if (!hasAnyAdmin) return null
+      }
+
+      return { ...group, items }
+    })
+    .filter((group): group is NavGroup => group !== null)
+}
+
+export function getVisibleNavItems(hasPermission: (resource: string, action: string) => boolean): NavItem[] {
+  return [...getVisibleNavGroups(hasPermission).flatMap((group) => group.items), DOCS_NAV_ITEM]
+}
diff --git a/dashboard/frontend/src/lib/pwa.ts b/dashboard/frontend/src/lib/pwa.ts
new file mode 100644
index 00000000..18b96849
--- /dev/null
+++ b/dashboard/frontend/src/lib/pwa.ts
@@ -0,0 +1,18 @@
+export function registerServiceWorker() {
+  if (!('serviceWorker' in navigator)) return
+  if (!import.meta.env.PROD) return
+
+  const register = () => {
+    navigator.serviceWorker.register('/sw.js').catch((error) => {
+      console.warn('[pwa] service worker registration failed', error)
+    })
+  }
+
+  if (document.readyState === 'complete') {
+    register()
+    return
+  }
+
+  window.addEventListener('load', register, { once: true })
+}
+
diff --git a/dashboard/frontend/src/lib/theme.ts b/dashboard/frontend/src/lib/theme.ts
new file mode 100644
index 00000000..fbed42a4
--- /dev/null
+++ b/dashboard/frontend/src/lib/theme.ts
@@ -0,0 +1,44 @@
+export type ThemeMode = 'dark' | 'light'
+
+export const THEME_STORAGE_KEY = 'evonexus.theme'
+
+function getStoredTheme(): ThemeMode | null {
+  if (typeof window === 'undefined') return null
+  try {
+    const value = window.localStorage.getItem(THEME_STORAGE_KEY)
+    if (value === 'dark' || value === 'light') return value
+  } catch {}
+  return null
+}
+
+function getPreferredTheme(): ThemeMode {
+  if (typeof window === 'undefined') return 'dark'
+  return window.matchMedia?.('(prefers-color-scheme: light)').matches ? 'light' : 'dark'
+}
+
+export function resolveInitialTheme(): ThemeMode {
+  return getStoredTheme() ?? getPreferredTheme()
+}
+
+export function applyTheme(theme: ThemeMode) {
+  if (typeof document === 'undefined') return
+
+  const root = document.documentElement
+  root.dataset.theme = theme
+  root.style.colorScheme = theme
+
+  const body = document.body
+  body.dataset.theme = theme
+
+  const themeColor = theme === 'light' ? '#f5f7fb' : '#0C111D'
+  const meta = document.querySelector('meta[name="theme-color"]') as HTMLMetaElement | null
+  if (meta) meta.content = themeColor
+}
+
+export function persistTheme(theme: ThemeMode) {
+  if (typeof window === 'undefined') return
+  try {
+    window.localStorage.setItem(THEME_STORAGE_KEY, theme)
+  } catch {}
+}
+
diff --git a/dashboard/frontend/src/pages/Observability.tsx b/dashboard/frontend/src/pages/Observability.tsx
new file mode 100644
index 00000000..2667a22d
--- /dev/null
+++ b/dashboard/frontend/src/pages/Observability.tsx
@@ -0,0 +1,243 @@
+import { useEffect, useState } from 'react'
+import { Activity, RefreshCw, ShieldCheck, Database, Plug, Clock3, AlertTriangle } from 'lucide-react'
+import { api } from '../lib/api'
+import { PageSkeleton } from '../components/PageStates'
+
+type Summary = any
+
+function MetricCard({
+  icon: Icon,
+  label,
+  value,
+  detail,
+}: {
+  icon: any
+  label: string
+  value: string
+  detail?: string
+}) {
+  return (
+    <div className="rounded-2xl border border-[color:var(--border)] bg-[var(--bg-card)] p-5 shadow-[0_18px_40px_rgba(0,0,0,0.15)]">
+      <div className="flex items-start justify-between gap-3">
+        <div>
+          <p className="text-[11px] uppercase tracking-[0.16em] text-[#667085]">{label}</p>
+          <div className="mt-2 text-2xl font-semibold text-[color:var(--text-primary)]">{value}</div>
+        </div>
+        <div className="rounded-xl border border-white/10 bg-white/5 p-2 text-[#00FFA7]">
+          <Icon size={18} />
+        </div>
+      </div>
+      {detail && <p className="mt-3 text-sm text-[color:var(--text-secondary)]">{detail}</p>}
+    </div>
+  )
+}
+
+export default function Observability() {
+  const [summary, setSummary] = useState<Summary | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  const load = async () => {
+    setLoading(true)
+    setError(null)
+    try {
+      const data = await api.get('/observability/summary')
+      setSummary(data)
+    } catch {
+      setError('Failed to load observability summary')
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  useEffect(() => {
+    load()
+  }, [])
+
+  if (loading && !summary) {
+    return (
+      <div className="space-y-6">
+        <div className="flex items-center justify-between">
+          <div>
+            <h1 className="text-xl font-bold text-white">Observability</h1>
+            <p className="text-sm text-[#5a6b7f]">Platform health, provider metrics, and runtime state.</p>
+          </div>
+        </div>
+        <PageSkeleton rows={3} cards={3} />
+      </div>
+    )
+  }
+
+  const providerMetrics = summary?.provider_metrics?.providers || []
+  const routing = summary?.provider_config?.routing?.failover_order || []
+
+  return (
+    <div className="space-y-6">
+      <div className="flex flex-col gap-4 lg:flex-row lg:items-end lg:justify-between">
+        <div>
+          <h1 className="text-xl font-bold text-white">Observability</h1>
+          <p className="mt-1 text-sm text-[#5a6b7f]">Platform health, provider metrics, queue state, and cache usage.</p>
+        </div>
+        <button
+          type="button"
+          onClick={load}
+          className="inline-flex items-center gap-2 rounded-xl border border-[#1e2a3a] bg-[#0b1018] px-4 py-2 text-sm font-medium text-[#e2e8f0] transition-colors hover:border-[#00FFA7]/40 hover:text-[#00FFA7]"
+        >
+          <RefreshCw size={14} />
+          Refresh
+        </button>
+      </div>
+
+      {error && (
+        <div className="rounded-2xl border border-red-500/20 bg-red-500/5 px-4 py-3 text-sm text-red-200">
+          {error}
+        </div>
+      )}
+
+      <div className="grid gap-4 md:grid-cols-2 xl:grid-cols-4">
+        <MetricCard
+          icon={Database}
+          label="Database"
+          value={summary?.database_backend || 'unknown'}
+          detail={summary?.backend?.checks?.database?.status || 'n/a'}
+        />
+        <MetricCard
+          icon={ShieldCheck}
+          label="Backend"
+          value={summary?.backend?.status || 'unknown'}
+          detail={summary?.backend?.checks?.secret_key?.status ? `Secret key: ${summary.backend.checks.secret_key.status}` : undefined}
+        />
+        <MetricCard
+          icon={Activity}
+          label="Terminal"
+          value={summary?.terminal_server?.status || 'unknown'}
+          detail={summary?.terminal_server?.reachable ? 'reachable' : summary?.terminal_server?.error || 'offline'}
+        />
+        <MetricCard
+          icon={Plug}
+          label="Plugins"
+          value={`${summary?.plugins?.installed_count || 0} installed`}
+          detail={`${summary?.plugins?.registry_count || 0} in registry`}
+        />
+      </div>
+
+      <div className="grid gap-4 xl:grid-cols-[1.4fr_1fr]">
+        <div className="rounded-2xl border border-[color:var(--border)] bg-[var(--bg-card)] p-5">
+          <div className="flex items-center justify-between gap-3">
+            <div>
+              <h2 className="text-sm font-semibold text-[color:var(--text-primary)]">Provider metrics</h2>
+              <p className="text-xs text-[color:var(--text-secondary)]">Success rate and latency by provider.</p>
+            </div>
+            <div className="rounded-lg border border-[#1e2a3a] bg-[#0b1018] px-3 py-1 text-[11px] text-[#5a6b7f]">
+              {summary?.provider_metrics?.total_events || 0} events
+            </div>
+          </div>
+
+          <div className="mt-4 overflow-x-auto">
+            <table className="min-w-full text-left text-sm">
+              <thead className="text-[11px] uppercase tracking-[0.12em] text-[#667085]">
+                <tr>
+                  <th className="py-2 pr-3">Provider</th>
+                  <th className="py-2 pr-3">Events</th>
+                  <th className="py-2 pr-3">Success</th>
+                  <th className="py-2 pr-3">Latency</th>
+                  <th className="py-2 pr-3">Last event</th>
+                </tr>
+              </thead>
+              <tbody>
+                {providerMetrics.map((row: any) => (
+                  <tr key={row.provider_id} className="border-t border-white/5">
+                    <td className="py-3 pr-3 font-medium text-white">{row.provider_id}</td>
+                    <td className="py-3 pr-3 text-[#cbd5e1]">{row.events}</td>
+                    <td className="py-3 pr-3 text-[#cbd5e1]">{row.success_rate ?? 'n/a'}%</td>
+                    <td className="py-3 pr-3 text-[#cbd5e1]">{row.avg_latency_ms ?? 'n/a'} ms</td>
+                    <td className="py-3 pr-3 text-[#94a3b8]">{row.last_event?.event || 'n/a'}</td>
+                  </tr>
+                ))}
+                {providerMetrics.length === 0 && (
+                  <tr>
+                    <td className="py-4 text-sm text-[#5a6b7f]" colSpan={5}>
+                      No provider metrics yet.
+                    </td>
+                  </tr>
+                )}
+              </tbody>
+            </table>
+          </div>
+        </div>
+
+        <div className="space-y-4">
+          <div className="rounded-2xl border border-[color:var(--border)] bg-[var(--bg-card)] p-5">
+            <h2 className="text-sm font-semibold text-[color:var(--text-primary)]">Routing</h2>
+            <p className="mt-1 text-xs text-[color:var(--text-secondary)]">Current failover order used by the terminal server.</p>
+            <div className="mt-3 flex flex-wrap gap-2">
+              {routing.map((item: string) => (
+                <span key={item} className="rounded-full border border-[#1e2a3a] bg-[#0b1018] px-2.5 py-1 text-[11px] text-[#e2e8f0]">
+                  {item}
+                </span>
+              ))}
+            </div>
+          </div>
+
+          <div className="rounded-2xl border border-[color:var(--border)] bg-[var(--bg-card)] p-5">
+            <h2 className="text-sm font-semibold text-[color:var(--text-primary)]">System snapshot</h2>
+            <div className="mt-3 space-y-2 text-sm">
+              <div className="flex items-center justify-between gap-3">
+                <span className="text-[color:var(--text-secondary)]">Cache</span>
+                <span className="text-white">{summary?.cache?.backend || 'unknown'}</span>
+              </div>
+              <div className="flex items-center justify-between gap-3">
+                <span className="text-[color:var(--text-secondary)]">Queue</span>
+                <span className="text-white">{summary?.queue?.backend || 'unknown'}</span>
+              </div>
+              <div className="flex items-center justify-between gap-3">
+                <span className="text-[color:var(--text-secondary)]">Generated at</span>
+                <span className="text-white">{summary?.generated_at ? new Date(summary.generated_at).toLocaleString() : 'n/a'}</span>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <div className="rounded-2xl border border-[color:var(--border)] bg-[var(--bg-card)] p-5">
+        <div className="flex items-center justify-between gap-3">
+          <div>
+            <h2 className="text-sm font-semibold text-[color:var(--text-primary)]">Recent events</h2>
+            <p className="text-xs text-[color:var(--text-secondary)]">Queue and platform activity from the last snapshot.</p>
+          </div>
+          <div className="flex items-center gap-2 rounded-lg border border-[#1e2a3a] bg-[#0b1018] px-3 py-1 text-[11px] text-[#5a6b7f]">
+            <Clock3 size={12} />
+            {summary?.recent_events?.length || 0}
+          </div>
+        </div>
+
+        <div className="mt-4 space-y-2">
+          {(summary?.recent_events || []).slice().reverse().map((event: any, index: number) => (
+            <div key={`${event.ts}-${index}`} className="flex items-start gap-3 rounded-xl border border-white/5 bg-[#0b1018] px-4 py-3">
+              <div className="mt-0.5 rounded-full bg-[#00FFA7]/15 p-1 text-[#00FFA7]">
+                <AlertTriangle size={12} />
+              </div>
+              <div className="min-w-0 flex-1">
+                <div className="flex items-center gap-2">
+                  <span className="text-sm font-medium text-white">{event.topic || 'event'}</span>
+                  <span className="text-[11px] text-[#5a6b7f]">{event.source || 'dashboard'}</span>
+                </div>
+                <p className="mt-1 truncate text-xs text-[#94a3b8]">
+                  {JSON.stringify(event.payload || {}).slice(0, 220)}
+                </p>
+              </div>
+              <span className="shrink-0 text-[11px] text-[#5a6b7f]">
+                {event.ts ? new Date(event.ts).toLocaleTimeString() : ''}
+              </span>
+            </div>
+          ))}
+          {(summary?.recent_events || []).length === 0 && (
+            <div className="rounded-xl border border-dashed border-[#1e2a3a] px-4 py-8 text-center text-sm text-[#5a6b7f]">
+              No recent events recorded.
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/dashboard/frontend/src/pages/SettingsSecurityTab.tsx b/dashboard/frontend/src/pages/SettingsSecurityTab.tsx
new file mode 100644
index 00000000..a25c229d
--- /dev/null
+++ b/dashboard/frontend/src/pages/SettingsSecurityTab.tsx
@@ -0,0 +1,257 @@
+import { useCallback, useEffect, useState } from 'react'
+import { AlertTriangle, Copy, KeyRound, QrCode, ShieldCheck } from 'lucide-react'
+import { useAuth } from '../context/AuthContext'
+import { api } from '../lib/api'
+
+type ToastType = 'success' | 'error' | 'info'
+
+const inp = 'w-full px-4 py-3 rounded-lg bg-[#0f1520] border border-[#1e2a3a] text-[#e2e8f0] placeholder-[#3d4f65] text-sm transition-colors duration-200 focus:outline-none focus:border-[#00FFA7]/60 focus:ring-1 focus:ring-[#00FFA7]/20'
+const lbl = 'block text-[11px] font-semibold text-[#5a6b7f] mb-1.5 tracking-[0.08em] uppercase'
+
+interface SecurityTabProps {
+  showToast: (msg: string, type?: ToastType) => void
+}
+
+export default function SecurityTab({ showToast }: SecurityTabProps) {
+  const { hasPermission, user } = useAuth()
+  const canManage = hasPermission('config', 'manage')
+  const [status, setStatus] = useState<any | null>(null)
+  const [enrollment, setEnrollment] = useState<any | null>(null)
+  const [verificationCode, setVerificationCode] = useState('')
+  const [password, setPassword] = useState('')
+  const [loading, setLoading] = useState(true)
+  const [saving, setSaving] = useState(false)
+
+  const load = useCallback(async () => {
+    setLoading(true)
+    try {
+      const data = await api.get('/auth/2fa/status')
+      setStatus(data)
+    } catch (error) {
+      showToast(error instanceof Error ? error.message : 'Failed to load 2FA status', 'error')
+    } finally {
+      setLoading(false)
+    }
+  }, [showToast])
+
+  useEffect(() => {
+    load()
+  }, [load])
+
+  const startSetup = async () => {
+    if (!canManage) {
+      showToast('Only admin accounts can manage 2FA', 'error')
+      return
+    }
+    setSaving(true)
+    try {
+      const data = await api.post('/auth/2fa/setup')
+      setEnrollment(data)
+      setVerificationCode('')
+      showToast('2FA enrollment started')
+      await load()
+    } catch (error) {
+      showToast(error instanceof Error ? error.message : 'Failed to start 2FA setup', 'error')
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  const confirmSetup = async () => {
+    if (!canManage) {
+      showToast('Only admin accounts can manage 2FA', 'error')
+      return
+    }
+    if (!verificationCode.trim()) {
+      showToast('Enter the verification code from your authenticator app', 'error')
+      return
+    }
+    setSaving(true)
+    try {
+      await api.post('/auth/2fa/confirm', { code: verificationCode.trim() })
+      setEnrollment(null)
+      setVerificationCode('')
+      setPassword('')
+      showToast('Two-factor authentication enabled')
+      await load()
+    } catch (error) {
+      showToast(error instanceof Error ? error.message : 'Failed to confirm 2FA', 'error')
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  const disableTwoFactor = async () => {
+    if (!canManage) {
+      showToast('Only admin accounts can manage 2FA', 'error')
+      return
+    }
+    if (!password.trim()) {
+      showToast('Enter your current password to disable 2FA', 'error')
+      return
+    }
+    setSaving(true)
+    try {
+      await api.post('/auth/2fa/disable', { password, totp_code: verificationCode.trim() })
+      setEnrollment(null)
+      setVerificationCode('')
+      setPassword('')
+      showToast('Two-factor authentication disabled')
+      await load()
+    } catch (error) {
+      showToast(error instanceof Error ? error.message : 'Failed to disable 2FA', 'error')
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  const secret = enrollment?.secret || (status?.enrollment_pending ? 'Enrollment pending in session' : '')
+  const provisioningUri = enrollment?.otpauth_uri || ''
+
+  return (
+    <div className="max-w-2xl space-y-5">
+      <div className="rounded-2xl border border-[#21262d] bg-[#161b22] p-5">
+        <div className="flex items-start justify-between gap-4 mb-4">
+          <div>
+            <h3 className="text-[13px] font-semibold text-[#e6edf3] flex items-center gap-2">
+              <ShieldCheck size={15} className="text-[#00FFA7]" />
+              Two-factor authentication
+            </h3>
+            <p className="text-[11px] text-[#667085] mt-1">
+              Protect admin access with a TOTP authenticator app.
+            </p>
+          </div>
+          <div className="text-right text-[11px] text-[#667085]">
+            <div className={status?.enabled ? 'text-[#00FFA7]' : 'text-[#f87171]'}>
+              {status?.enabled ? 'Enabled' : 'Disabled'}
+            </div>
+            <div>{user?.role || 'user'}</div>
+          </div>
+        </div>
+
+        {loading ? (
+          <div className="space-y-3">
+            {[...Array(3)].map((_, i) => <div key={i} className="skeleton h-10 rounded-lg" />)}
+          </div>
+        ) : (
+          <div className="space-y-4">
+            <div className="rounded-xl border border-[#1e2a3a] bg-[#0f1520] p-4">
+              <div className="flex items-center gap-2 text-sm text-[#e6edf3]">
+                <KeyRound size={14} className="text-[#00FFA7]" />
+                <span>Current status</span>
+              </div>
+              <p className="mt-2 text-xs text-[#667085]">
+                {status?.enabled
+                  ? `Enabled${status?.confirmed_at ? ` since ${status.confirmed_at}` : ''}`
+                  : '2FA is not enabled for this account.'}
+              </p>
+              {status?.last_used_step ? (
+                <p className="mt-1 text-[11px] text-[#5a6b7f]">Last accepted time-step: {status.last_used_step}</p>
+              ) : null}
+            </div>
+
+            {!canManage && (
+              <div className="rounded-xl border border-[#3a2a2a] bg-[#1a0a0a] p-4 text-xs text-[#f87171] flex items-start gap-2">
+                <AlertTriangle size={14} className="mt-0.5 shrink-0" />
+                <span>Only admin accounts can enroll or disable 2FA.</span>
+              </div>
+            )}
+
+            {secret && (
+              <div className="rounded-xl border border-[#1e2a3a] bg-[#0b1018] p-4 space-y-3">
+                <div className="flex items-center gap-2 text-sm text-[#e6edf3]">
+                  <QrCode size={14} className="text-[#00FFA7]" />
+                  <span>Enrollment secret</span>
+                </div>
+                <div className="rounded-lg border border-[#1e2a3a] bg-[#0f1520] px-3 py-2 text-xs font-mono text-[#00FFA7] break-all">
+                  {secret}
+                </div>
+                {provisioningUri && (
+                  <div className="rounded-lg border border-[#1e2a3a] bg-[#0f1520] px-3 py-2 text-[11px] text-[#667085] break-all">
+                    {provisioningUri}
+                  </div>
+                )}
+                <button
+                  type="button"
+                  onClick={async () => {
+                    try {
+                      if (secret) {
+                        await navigator.clipboard.writeText(secret)
+                        showToast('Secret copied to clipboard')
+                      }
+                    } catch {
+                      showToast('Clipboard copy failed', 'error')
+                    }
+                  }}
+                  className="inline-flex items-center gap-2 text-[11px] px-3 py-1.5 rounded-md border border-[#1e2a3a] text-[#e6edf3] hover:text-[#00FFA7] hover:border-[#00FFA7]/40 transition-colors"
+                >
+                  <Copy size={12} />
+                  Copy secret
+                </button>
+              </div>
+            )}
+
+            {canManage && (
+              <div className="grid gap-3">
+                <div className="grid grid-cols-1 sm:grid-cols-2 gap-3">
+                  <button
+                    type="button"
+                    disabled={saving}
+                    onClick={startSetup}
+                    className="inline-flex items-center justify-center gap-2 rounded-xl bg-[#00FFA7] px-4 py-2.5 text-sm font-semibold text-[#080c14] transition-colors hover:bg-[#00e69a] disabled:opacity-40"
+                  >
+                    {status?.enabled ? 'Regenerate secret' : 'Start setup'}
+                  </button>
+                  <button
+                    type="button"
+                    disabled={saving || !secret}
+                    onClick={confirmSetup}
+                    className="inline-flex items-center justify-center gap-2 rounded-xl border border-[#1e2a3a] px-4 py-2.5 text-sm font-semibold text-[#e6edf3] transition-colors hover:border-[#00FFA7]/40 hover:text-[#00FFA7] disabled:opacity-40"
+                  >
+                    Confirm enrollment
+                  </button>
+                </div>
+
+                <div className="grid grid-cols-1 sm:grid-cols-2 gap-3">
+                  <div>
+                    <label className={lbl}>Verification code</label>
+                    <input
+                      type="text"
+                      value={verificationCode}
+                      onChange={(e) => setVerificationCode(e.target.value)}
+                      className={inp}
+                      placeholder="123456"
+                      inputMode="numeric"
+                      autoComplete="one-time-code"
+                    />
+                  </div>
+                  <div>
+                    <label className={lbl}>Current password</label>
+                    <input
+                      type="password"
+                      value={password}
+                      onChange={(e) => setPassword(e.target.value)}
+                      className={inp}
+                      placeholder="••••••••"
+                      autoComplete="current-password"
+                    />
+                  </div>
+                </div>
+
+                <button
+                  type="button"
+                  disabled={saving || !status?.enabled}
+                  onClick={disableTwoFactor}
+                  className="inline-flex items-center justify-center gap-2 rounded-xl border border-[#3a2a2a] bg-[#1a0a0a] px-4 py-2.5 text-sm font-semibold text-[#f87171] transition-colors hover:border-[#f87171]/40 disabled:opacity-40"
+                >
+                  Disable 2FA
+                </button>
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
+
diff --git a/dashboard/frontend/src/pages/integrations/CustomIntegrationModal.tsx b/dashboard/frontend/src/pages/integrations/CustomIntegrationModal.tsx
new file mode 100644
index 00000000..f9efd4a1
--- /dev/null
+++ b/dashboard/frontend/src/pages/integrations/CustomIntegrationModal.tsx
@@ -0,0 +1,300 @@
+import { useEffect, useRef, useState } from 'react'
+import { Eye, EyeOff, Loader2, Plus, X } from 'lucide-react'
+import { api } from '../../lib/api'
+import { CATEGORY_OPTIONS, EMPTY_FORM, type CustomIntegrationForm, slugify } from './types'
+
+interface CustomModalProps {
+  open: boolean
+  initial?: CustomIntegrationForm & { slug: string }
+  isEdit: boolean
+  onClose: () => void
+  onSaved: (envWritten?: boolean) => void
+}
+
+export function CustomIntegrationModal({ open, initial, isEdit, onClose, onSaved }: CustomModalProps) {
+  const [form, setForm] = useState<CustomIntegrationForm>(EMPTY_FORM)
+  const [slugManual, setSlugManual] = useState(false)
+  const [errors, setErrors] = useState<Partial<Record<keyof CustomIntegrationForm, string>>>({})
+  const [saving, setSaving] = useState(false)
+  const [visibleRows, setVisibleRows] = useState<Set<number>>(new Set())
+  const overlayRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (open) {
+      const baseForm = initial
+        ? {
+            ...initial,
+            envKeys: (initial.envKeys as unknown as (string | { name: string; value: string })[]).map((k) =>
+              typeof k === 'string' ? { name: k, value: '' } : k
+            ),
+          }
+        : EMPTY_FORM
+      setForm(baseForm)
+      setSlugManual(isEdit)
+      setErrors({})
+      setVisibleRows(new Set())
+      setSaving(false)
+    }
+  }, [open, initial, isEdit])
+
+  useEffect(() => {
+    if (!open) return
+    const handler = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose()
+    }
+    document.addEventListener('keydown', handler)
+    return () => document.removeEventListener('keydown', handler)
+  }, [open, onClose])
+
+  const setField = <K extends keyof CustomIntegrationForm>(key: K, value: CustomIntegrationForm[K]) => {
+    setForm((prev) => {
+      const next = { ...prev, [key]: value }
+      if (key === 'displayName' && !slugManual) {
+        next.slug = slugify(value as string)
+      }
+      return next
+    })
+    setErrors((prev) => ({ ...prev, [key]: undefined }))
+  }
+
+  const validate = (): boolean => {
+    const errs: Partial<Record<keyof CustomIntegrationForm, string>> = {}
+    if (!form.displayName.trim()) errs.displayName = 'Required'
+    if (!form.slug.trim()) {
+      errs.slug = 'Required'
+    } else if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(form.slug)) {
+      errs.slug = 'Lowercase letters, digits and hyphens only'
+    }
+    setErrors(errs)
+    return Object.keys(errs).length === 0
+  }
+
+  const handleSave = async () => {
+    if (!validate()) return
+    setSaving(true)
+    try {
+      const envKeyNames = form.envKeys.map((r) => r.name).filter((n) => n.trim())
+      const envValues: Record<string, string> = {}
+      for (const row of form.envKeys) {
+        if (row.name.trim() && row.value.trim()) {
+          envValues[row.name.trim()] = row.value.trim()
+        }
+      }
+      const hasEnvValues = Object.keys(envValues).length > 0
+
+      if (isEdit && initial?.slug) {
+        await api.patch(`/integrations/custom/${initial.slug}`, {
+          displayName: form.displayName,
+          description: form.description,
+          category: form.category,
+          envKeys: envKeyNames,
+          ...(hasEnvValues ? { envValues } : {}),
+        })
+      } else {
+        await api.post('/integrations/custom', {
+          slug: form.slug,
+          displayName: form.displayName,
+          description: form.description,
+          category: form.category,
+          envKeys: envKeyNames,
+          ...(hasEnvValues ? { envValues } : {}),
+        })
+      }
+      onSaved(hasEnvValues)
+      onClose()
+    } catch (e: unknown) {
+      const msg = e instanceof Error ? e.message : 'Error saving'
+      setErrors({ displayName: msg })
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  const addEnvRow = () => {
+    setField('envKeys', [...form.envKeys, { name: '', value: '' }])
+  }
+
+  const removeEnvRow = (idx: number) => {
+    setField('envKeys', form.envKeys.filter((_, i) => i !== idx))
+    setVisibleRows((prev) => {
+      const next = new Set(prev)
+      next.delete(idx)
+      return next
+    })
+  }
+
+  const updateEnvRow = (idx: number, field: 'name' | 'value', val: string) => {
+    const next = form.envKeys.map((r, i) =>
+      i === idx ? { ...r, [field]: field === 'name' ? val.toUpperCase() : val } : r
+    )
+    setField('envKeys', next)
+  }
+
+  const toggleRowVisibility = (idx: number) => {
+    setVisibleRows((prev) => {
+      const next = new Set(prev)
+      if (next.has(idx)) next.delete(idx)
+      else next.add(idx)
+      return next
+    })
+  }
+
+  if (!open) return null
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center p-4">
+      <div
+        ref={overlayRef}
+        className="absolute inset-0 bg-black/60 backdrop-blur-[2px]"
+        onClick={onClose}
+      />
+      <div className="relative w-full max-w-lg bg-[#0C111D] border border-[#21262d] rounded-2xl shadow-2xl flex flex-col max-h-[90vh]">
+        <div className="flex items-center justify-between px-5 py-4 border-b border-[#21262d]">
+          <h2 className="text-base font-semibold text-[#e6edf3]">
+            {isEdit ? 'Edit Custom Integration' : 'New Custom Integration'}
+          </h2>
+          <button
+            type="button"
+            onClick={onClose}
+            className="p-1.5 rounded-lg text-[#667085] hover:text-[#e6edf3] hover:bg-[#21262d] transition-colors"
+          >
+            <X size={16} />
+          </button>
+        </div>
+
+        <div className="flex-1 overflow-y-auto px-5 py-5 space-y-4">
+          <div>
+            <label className="block text-xs font-medium text-[#8b949e] mb-1">
+              Display Name <span className="text-red-400">*</span>
+            </label>
+            <input
+              type="text"
+              value={form.displayName}
+              onChange={(e) => setField('displayName', e.target.value)}
+              placeholder="My Custom API"
+              className="w-full rounded-lg border border-[#21262d] bg-[#161b22] px-3 py-2 text-sm text-[#e6edf3] placeholder-[#3F3F46] focus:outline-none focus:border-[#00FFA7]/50 transition-colors"
+            />
+            {errors.displayName && <p className="text-xs text-red-400 mt-1">{errors.displayName}</p>}
+          </div>
+
+          <div>
+            <label className="block text-xs font-medium text-[#8b949e] mb-1">
+              Slug <span className="text-red-400">*</span>
+            </label>
+            <div className="flex items-center rounded-lg border border-[#21262d] bg-[#161b22] focus-within:border-[#00FFA7]/50 transition-colors">
+              <span className="pl-3 text-xs text-[#3F3F46] shrink-0">custom-int-</span>
+              <input
+                type="text"
+                value={form.slug}
+                onChange={(e) => {
+                  setSlugManual(true)
+                  setField('slug', e.target.value)
+                }}
+                disabled={isEdit}
+                placeholder="my-api"
+                className="flex-1 bg-transparent px-1 py-2 text-sm text-[#e6edf3] placeholder-[#3F3F46] focus:outline-none disabled:opacity-50"
+              />
+            </div>
+            {errors.slug && <p className="text-xs text-red-400 mt-1">{errors.slug}</p>}
+          </div>
+
+          <div>
+            <label className="block text-xs font-medium text-[#8b949e] mb-1">Description</label>
+            <textarea
+              value={form.description}
+              onChange={(e) => setField('description', e.target.value)}
+              rows={2}
+              placeholder="What this integration does..."
+              className="w-full rounded-lg border border-[#21262d] bg-[#161b22] px-3 py-2 text-sm text-[#e6edf3] placeholder-[#3F3F46] focus:outline-none focus:border-[#00FFA7]/50 transition-colors resize-none"
+            />
+          </div>
+
+          <div>
+            <label className="block text-xs font-medium text-[#8b949e] mb-1">Category</label>
+            <select
+              value={form.category}
+              onChange={(e) => setField('category', e.target.value)}
+              className="w-full rounded-lg border border-[#21262d] bg-[#161b22] px-3 py-2 text-sm text-[#e6edf3] focus:outline-none focus:border-[#00FFA7]/50 transition-colors"
+            >
+              {CATEGORY_OPTIONS.map((o) => (
+                <option key={o.value} value={o.value}>
+                  {o.label}
+                </option>
+              ))}
+            </select>
+          </div>
+
+          <div>
+            <label className="block text-xs font-medium text-[#8b949e] mb-1">Env Keys</label>
+            <div className="space-y-1.5 mb-2">
+              {form.envKeys.map((row, idx) => (
+                <div key={idx} className="flex items-center gap-1.5">
+                  <input
+                    type="text"
+                    value={row.name}
+                    onChange={(e) => updateEnvRow(idx, 'name', e.target.value)}
+                    placeholder="MY_API_KEY"
+                    className="w-44 shrink-0 rounded-lg border border-[#21262d] bg-[#161b22] px-3 py-1.5 text-xs text-[#00FFA7] placeholder-[#3F3F46] focus:outline-none focus:border-[#00FFA7]/50 transition-colors font-mono"
+                  />
+                  <div className="relative flex-1">
+                    <input
+                      type={visibleRows.has(idx) ? 'text' : 'password'}
+                      value={row.value}
+                      onChange={(e) => updateEnvRow(idx, 'value', e.target.value)}
+                      placeholder={isEdit ? 'leave empty to keep current' : 'secret value (optional)'}
+                      className="w-full rounded-lg border border-[#21262d] bg-[#161b22] px-3 py-1.5 pr-8 text-xs text-[#e6edf3] placeholder-[#3F3F46] focus:outline-none focus:border-[#00FFA7]/50 transition-colors"
+                    />
+                    {row.value.length > 0 && (
+                      <button
+                        type="button"
+                        onClick={() => toggleRowVisibility(idx)}
+                        className="absolute right-2 top-1/2 -translate-y-1/2 text-[#667085] hover:text-[#e6edf3] transition-colors"
+                        tabIndex={-1}
+                      >
+                        {visibleRows.has(idx) ? <EyeOff size={12} /> : <Eye size={12} />}
+                      </button>
+                    )}
+                  </div>
+                  <button
+                    type="button"
+                    onClick={() => removeEnvRow(idx)}
+                    className="p-1 rounded text-[#667085] hover:text-red-400 transition-colors shrink-0"
+                  >
+                    <X size={12} />
+                  </button>
+                </div>
+              ))}
+            </div>
+            <button
+              type="button"
+              onClick={addEnvRow}
+              className="flex items-center gap-1.5 px-3 py-1.5 rounded-lg border border-dashed border-[#21262d] text-xs text-[#667085] hover:text-[#e6edf3] hover:border-[#344054] transition-colors"
+            >
+              <Plus size={12} />
+              Add env key
+            </button>
+          </div>
+        </div>
+
+        <div className="flex items-center justify-end gap-3 px-5 py-4 border-t border-[#21262d]">
+          <button
+            type="button"
+            onClick={onClose}
+            className="px-4 py-2 rounded-lg text-sm text-[#667085] hover:text-[#e6edf3] hover:bg-[#21262d] transition-colors"
+          >
+            Cancel
+          </button>
+          <button
+            type="button"
+            onClick={handleSave}
+            disabled={saving}
+            className="flex items-center gap-1.5 px-4 py-2 rounded-lg bg-[#00FFA7] text-[#0C111D] text-sm font-semibold hover:bg-[#00e699] transition-colors disabled:opacity-60 disabled:cursor-not-allowed"
+          >
+            {saving && <Loader2 size={14} className="animate-spin" />}
+            {isEdit ? 'Save Changes' : 'Create'}
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/dashboard/frontend/src/pages/integrations/DatabasesTab.tsx b/dashboard/frontend/src/pages/integrations/DatabasesTab.tsx
new file mode 100644
index 00000000..0c5dedf5
--- /dev/null
+++ b/dashboard/frontend/src/pages/integrations/DatabasesTab.tsx
@@ -0,0 +1,552 @@
+import { useState, type FormEvent, type ReactNode } from 'react'
+import { AlertCircle, Database, Eye, EyeOff, Loader2, Lock, Pencil, Plus, Trash2, Unlock, X } from 'lucide-react'
+import { api } from '../../lib/api'
+import {
+  DB_FLAVOR_META,
+  EMPTY_DB_FORM,
+  SSL_MODES_POSTGRES,
+  inputClass,
+  type DatabaseConnection,
+  type DatabaseFlavor,
+  type DbFormState,
+  type FlavorMeta,
+} from './types'
+
+interface DatabasesTabProps {
+  flavors: DatabaseFlavor[]
+  onReload: () => void
+}
+
+interface DeleteTarget {
+  flavor: 'postgres' | 'mysql' | 'mongo' | 'redis'
+  index: number
+  label: string
+}
+
+export function DatabasesTab({ flavors, onReload }: DatabasesTabProps) {
+  const postgres = flavors.find((f) => f.slug === 'postgres') ?? { slug: 'postgres', skill: 'db-postgres', ok: true, count: 0, connections: [] }
+  const mysql = flavors.find((f) => f.slug === 'mysql') ?? { slug: 'mysql', skill: 'db-mysql', ok: true, count: 0, connections: [] }
+  const mongo = flavors.find((f) => f.slug === 'mongo') ?? { slug: 'mongo', skill: 'db-mongo', ok: true, count: 0, connections: [] }
+  const redis = flavors.find((f) => f.slug === 'redis') ?? { slug: 'redis', skill: 'db-redis', ok: true, count: 0, connections: [] }
+
+  const [modalFlavor, setModalFlavor] = useState<'postgres' | 'mysql' | 'mongo' | 'redis' | null>(null)
+  const [editingIndex, setEditingIndex] = useState<number | null>(null)
+  const [formInitial, setFormInitial] = useState<Partial<DbFormState>>({})
+  const [deleteTarget, setDeleteTarget] = useState<DeleteTarget | null>(null)
+  const [deleting, setDeleting] = useState(false)
+
+  const openCreate = (flavor: 'postgres' | 'mysql' | 'mongo' | 'redis') => {
+    setEditingIndex(null)
+    setFormInitial({})
+    setModalFlavor(flavor)
+  }
+
+  const openEdit = (flavor: 'postgres' | 'mysql' | 'mongo' | 'redis', conn: DatabaseConnection) => {
+    setEditingIndex(conn.index)
+    const usesConnString = conn.host === '<dsn>' || conn.host === '<uri>' || conn.host === '<url>'
+    setFormInitial({
+      label: conn.label,
+      host: usesConnString ? '' : (conn.host ?? ''),
+      port: conn.port ? String(conn.port) : '',
+      database: flavor === 'redis' ? '' : (conn.database ?? ''),
+      db: flavor === 'redis' ? (conn.database ?? '') : '',
+      ssl_mode: conn.ssl_mode ?? '',
+      allow_write: conn.allow_write,
+      query_timeout: String(conn.query_timeout),
+      max_rows: String(conn.max_rows),
+    })
+    setModalFlavor(flavor)
+  }
+
+  const handleDelete = async () => {
+    if (!deleteTarget) return
+    setDeleting(true)
+    try {
+      await api.delete(`/integrations/databases/${deleteTarget.flavor}/${deleteTarget.index}`)
+      setDeleteTarget(null)
+      onReload()
+    } catch (e) {
+      console.error(e)
+    } finally {
+      setDeleting(false)
+    }
+  }
+
+  return (
+    <div className="space-y-8">
+      {deleteTarget && (
+        <div className="fixed inset-0 z-[70] flex items-center justify-center p-4">
+          <div className="absolute inset-0 bg-black/60 backdrop-blur-[2px]" onClick={() => setDeleteTarget(null)} />
+          <div className="relative w-full max-w-sm bg-[#0C111D] border border-[#21262d] rounded-2xl shadow-2xl p-6">
+            <h3 className="text-base font-semibold text-[#e6edf3] mb-2">Remove database connection</h3>
+            <p className="text-sm text-[#667085] mb-5">
+              Remove <span className="text-[#e6edf3] font-medium">{deleteTarget.label}</span>? The env variables will be deleted from{' '}
+              <code className="text-[#00FFA7] font-mono text-xs">.env</code>.
+            </p>
+            <div className="flex items-center justify-end gap-3">
+              <button onClick={() => setDeleteTarget(null)} className="px-4 py-2 rounded-lg text-sm text-[#667085] hover:text-[#e6edf3] hover:bg-[#21262d] transition-colors">Cancel</button>
+              <button onClick={handleDelete} disabled={deleting} className="flex items-center gap-1.5 px-4 py-2 rounded-lg bg-red-500/80 text-white text-sm font-semibold hover:bg-red-500 transition-colors disabled:opacity-60">
+                {deleting && <Loader2 size={14} className="animate-spin" />} Remove
+              </button>
+            </div>
+          </div>
+        </div>
+      )}
+
+      {modalFlavor && (
+        <DatabaseFormModal
+          flavor={modalFlavor}
+          editingIndex={editingIndex}
+          initial={formInitial}
+          onClose={() => setModalFlavor(null)}
+          onSaved={() => {
+            setModalFlavor(null)
+            onReload()
+          }}
+        />
+      )}
+
+      <FlavorSection flavor={postgres} onAdd={() => openCreate('postgres')} onEdit={(c) => openEdit('postgres', c)} onDelete={(c) => setDeleteTarget({ flavor: 'postgres', index: c.index, label: c.label })} />
+      <FlavorSection flavor={mysql} onAdd={() => openCreate('mysql')} onEdit={(c) => openEdit('mysql', c)} onDelete={(c) => setDeleteTarget({ flavor: 'mysql', index: c.index, label: c.label })} />
+      <FlavorSection flavor={mongo} onAdd={() => openCreate('mongo')} onEdit={(c) => openEdit('mongo', c)} onDelete={(c) => setDeleteTarget({ flavor: 'mongo', index: c.index, label: c.label })} />
+      <FlavorSection flavor={redis} onAdd={() => openCreate('redis')} onEdit={(c) => openEdit('redis', c)} onDelete={(c) => setDeleteTarget({ flavor: 'redis', index: c.index, label: c.label })} />
+    </div>
+  )
+}
+
+function FlavorSection({
+  flavor,
+  onAdd,
+  onEdit,
+  onDelete,
+}: {
+  flavor: DatabaseFlavor
+  onAdd: () => void
+  onEdit: (c: DatabaseConnection) => void
+  onDelete: (c: DatabaseConnection) => void
+}) {
+  const meta = DB_FLAVOR_META[flavor.slug] ?? { color: '#667085', colorMuted: 'rgba(102,112,133,0.10)', label: flavor.slug, defaultPort: 0 }
+
+  return (
+    <section>
+      <div className="flex items-center justify-between mb-4">
+        <div className="flex items-center gap-2.5">
+          <div className="flex items-center justify-center w-7 h-7 rounded-lg" style={{ backgroundColor: meta.colorMuted, border: `1px solid ${meta.color}33` }}>
+            <Database size={14} style={{ color: meta.color }} />
+          </div>
+          <h2 className="text-base font-semibold text-[#e6edf3]">{meta.label}</h2>
+          {flavor.count > 0 && (
+            <span className="text-xs px-2 py-0.5 rounded-full" style={{ backgroundColor: meta.colorMuted, color: meta.color, border: `1px solid ${meta.color}40` }}>
+              {flavor.count}
+            </span>
+          )}
+          {!flavor.ok && (
+            <span className="text-[10px] px-2 py-0.5 rounded-full bg-red-500/10 text-red-400 border border-red-500/25 flex items-center gap-1">
+              <AlertCircle size={10} /> {flavor.error || 'parser error'}
+            </span>
+          )}
+        </div>
+        <button onClick={onAdd} className="flex items-center gap-1.5 text-xs px-3 py-1.5 rounded-full bg-[#00FFA7]/10 text-[#00FFA7] border border-[#00FFA7]/20 hover:bg-[#00FFA7]/20 transition-all">
+          <Plus size={13} /> Add {meta.label}
+        </button>
+      </div>
+
+      {flavor.connections.length === 0 ? (
+        <div
+          onClick={onAdd}
+          role="button"
+          tabIndex={0}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter' || e.key === ' ') {
+              e.preventDefault()
+              onAdd()
+            }
+          }}
+          className="cursor-pointer rounded-xl border border-dashed border-[#21262d] hover:border-[#00FFA7]/30 bg-[#161b22]/50 p-8 flex flex-col items-center justify-center gap-2 transition-colors group"
+        >
+          <div className="flex items-center justify-center w-10 h-10 rounded-xl bg-[#00FFA7]/8 border border-[#00FFA7]/15 group-hover:bg-[#00FFA7]/15 transition-colors">
+            <Plus size={20} className="text-[#00FFA7]" />
+          </div>
+          <p className="text-sm font-medium text-[#667085] group-hover:text-[#e6edf3] transition-colors">Add {meta.label} connection</p>
+          <p className="text-xs text-[#3F3F46]">Host, port, user, password - stored in .env automatically</p>
+        </div>
+      ) : (
+        <div className="grid grid-cols-1 md:grid-cols-2 gap-3">
+          {flavor.connections.map((conn) => (
+            <ConnectionCard key={conn.index} conn={conn} flavor={flavor.slug} meta={meta} onEdit={() => onEdit(conn)} onDelete={() => onDelete(conn)} />
+          ))}
+        </div>
+      )}
+    </section>
+  )
+}
+
+function ConnectionCard({
+  conn,
+  flavor,
+  meta,
+  onEdit,
+  onDelete,
+}: {
+  conn: DatabaseConnection
+  flavor: string
+  meta: FlavorMeta
+  onEdit: () => void
+  onDelete: () => void
+}) {
+  const envPrefix = `DB_${flavor.toUpperCase()}_${conn.index}`
+  const hostDisplay =
+    conn.host === '<dsn>' ? 'via DSN' :
+    conn.host === '<uri>' ? 'via URI' :
+    conn.host === '<url>' ? 'via URL' :
+    (conn.host ?? '—')
+  const dbLabel = flavor === 'redis' ? 'DB index' : 'Database'
+  const sslLabel = flavor === 'redis' || flavor === 'mongo' ? 'TLS' : 'SSL'
+  const sslValue =
+    flavor === 'redis' || flavor === 'mongo'
+      ? (conn as DatabaseConnection & { tls?: boolean }).tls ? 'on' : 'off'
+      : (conn.ssl_mode ?? '—')
+
+  return (
+    <div className="group relative rounded-xl border border-[#21262d] bg-[#161b22] p-4 transition-all hover:border-transparent">
+      <div className="pointer-events-none absolute inset-0 rounded-xl opacity-0 transition-opacity duration-300 group-hover:opacity-100"
+        style={{ boxShadow: `inset 0 0 0 1px ${meta.color}44, 0 0 16px ${meta.color}22`, borderRadius: 'inherit' }} />
+
+      <div className="relative flex items-start justify-between mb-3">
+        <div className="min-w-0 flex-1">
+          <div className="flex items-center gap-2 mb-0.5">
+            <span className="text-sm font-semibold text-[#e6edf3] truncate">{conn.label}</span>
+            <span className="text-[10px] px-1.5 py-0.5 rounded-full font-mono text-[#667085] bg-white/[0.04] border border-[#21262d] shrink-0">#{conn.index}</span>
+          </div>
+          <p className="text-[11px] text-[#667085] font-mono truncate">{envPrefix}_*</p>
+        </div>
+        <div className="flex items-center gap-1.5 shrink-0">
+          {conn.allow_write ? (
+            <span className="inline-flex items-center gap-1 text-[10px] font-medium px-2 py-0.5 rounded-full bg-amber-500/10 text-amber-400 border border-amber-500/25" title="ALLOW_WRITE=true">
+              <Unlock size={10} /> read/write
+            </span>
+          ) : (
+            <span className="inline-flex items-center gap-1 text-[10px] font-medium px-2 py-0.5 rounded-full bg-[#00FFA7]/10 text-[#00FFA7] border border-[#00FFA7]/25">
+              <Lock size={10} /> read-only
+            </span>
+          )}
+        </div>
+      </div>
+
+      <div className="relative grid grid-cols-2 gap-x-4 gap-y-1.5 text-xs mb-3">
+        <div><p className="text-[10px] uppercase tracking-wider text-[#3F3F46] mb-0.5">Host</p><p className="text-[#e6edf3] font-mono truncate" title={hostDisplay}>{hostDisplay}</p></div>
+        <div><p className="text-[10px] uppercase tracking-wider text-[#3F3F46] mb-0.5">Port</p><p className="text-[#e6edf3] font-mono">{conn.port ?? '—'}</p></div>
+        <div><p className="text-[10px] uppercase tracking-wider text-[#3F3F46] mb-0.5">{dbLabel}</p><p className="text-[#e6edf3] font-mono truncate" title={conn.database ?? '—'}>{conn.database ?? '—'}</p></div>
+        <div><p className="text-[10px] uppercase tracking-wider text-[#3F3F46] mb-0.5">{sslLabel}</p><p className="text-[#e6edf3] font-mono">{sslValue}</p></div>
+      </div>
+
+      <div className="relative flex items-center justify-between gap-2 pt-3 border-t border-[#21262d]">
+        <div className="flex items-center gap-3 text-[10px] text-[#667085]">
+          <span>timeout <span className="text-[#e6edf3] font-mono">{conn.query_timeout}s</span></span>
+          <span>max rows <span className="text-[#e6edf3] font-mono">{conn.max_rows}</span></span>
+        </div>
+        <div className="flex items-center gap-1">
+          <button onClick={onEdit} className="flex items-center gap-1 px-2 py-1 rounded-lg text-[10px] text-[#667085] hover:text-[#e6edf3] hover:bg-[#21262d] transition-colors" title="Edit">
+            <Pencil size={11} /> Edit
+          </button>
+          <button onClick={onDelete} className="p-1.5 rounded-lg hover:bg-red-500/10 text-[#667085] hover:text-red-400 transition-colors" title="Remove">
+            <Trash2 size={12} />
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+const SSL_PLACEHOLDER = SSL_MODES_POSTGRES
+
+function DatabaseFormModal({
+  flavor,
+  editingIndex,
+  initial,
+  onClose,
+  onSaved,
+}: {
+  flavor: 'postgres' | 'mysql' | 'mongo' | 'redis'
+  editingIndex: number | null
+  initial: Partial<DbFormState>
+  onClose: () => void
+  onSaved: () => void
+}) {
+  const meta = DB_FLAVOR_META[flavor]
+  const isEdit = editingIndex !== null
+
+  const [form, setForm] = useState<DbFormState>({
+    ...EMPTY_DB_FORM,
+    port: String(meta.defaultPort),
+    query_timeout: '30',
+    max_rows: '1000',
+    ssl_mode: flavor === 'postgres' ? 'require' : '',
+    ...initial,
+  } as DbFormState)
+  const [showPassword, setShowPassword] = useState(false)
+  const [saving, setSaving] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const update = <K extends keyof DbFormState>(key: K, value: DbFormState[K]) => {
+    setForm((prev) => ({ ...prev, [key]: value }))
+  }
+
+  const submit = async (e: FormEvent) => {
+    e.preventDefault()
+    setError(null)
+
+    if (!form.label.trim()) {
+      setError('Label is required')
+      return
+    }
+
+    const connectionStringField =
+      flavor === 'mongo' ? form.uri.trim() :
+      flavor === 'redis' ? form.url.trim() :
+      form.dsn.trim()
+    if (!connectionStringField && !form.host.trim()) {
+      setError(flavor === 'mongo' ? 'Host or URI is required' :
+               flavor === 'redis' ? 'Host or URL is required' :
+               'Host is required (or use a full DSN)')
+      return
+    }
+
+    const body: Record<string, unknown> = {
+      label: form.label.trim(),
+      host: form.host.trim() || undefined,
+      port: form.port.trim() || undefined,
+      allow_write: form.allow_write ? 'true' : undefined,
+      query_timeout: form.query_timeout.trim() || undefined,
+      max_rows: form.max_rows.trim() || undefined,
+    }
+
+    if (flavor === 'postgres' || flavor === 'mysql') {
+      body.database = form.database.trim() || undefined
+      body.user = form.user.trim() || undefined
+      body.ssl_ca_path = form.ssl_ca_path.trim() || undefined
+      body.dsn = form.dsn.trim() || undefined
+      if (flavor === 'postgres') body.ssl_mode = form.ssl_mode || undefined
+    } else if (flavor === 'mongo') {
+      body.database = form.database.trim() || undefined
+      body.user = form.user.trim() || undefined
+      body.auth_source = form.auth_source.trim() || undefined
+      body.tls = form.tls ? 'true' : undefined
+      body.uri = form.uri.trim() || undefined
+    } else if (flavor === 'redis') {
+      body.db = form.db.trim() || undefined
+      body.username = form.username.trim() || undefined
+      body.tls = form.tls ? 'true' : undefined
+      body.url = form.url.trim() || undefined
+    }
+
+    if (isEdit) {
+      body.password = form.password === '' ? '__KEEP__' : form.password
+    } else {
+      body.password = form.password
+    }
+
+    setSaving(true)
+    try {
+      if (isEdit) {
+        await api.put(`/integrations/databases/${flavor}/${editingIndex}`, body)
+      } else {
+        await api.post(`/integrations/databases/${flavor}`, body)
+      }
+      onSaved()
+    } catch (e: unknown) {
+      const msg = e instanceof Error ? e.message : 'Failed to save'
+      setError(msg)
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  return (
+    <div className="fixed inset-0 z-[60] flex items-center justify-center p-4">
+      <div className="absolute inset-0 bg-black/60 backdrop-blur-[2px]" onClick={onClose} />
+      <div className="relative w-full max-w-lg max-h-[90vh] overflow-y-auto bg-[#0C111D] border border-[#21262d] rounded-2xl shadow-2xl">
+        <form onSubmit={submit}>
+          <div className="flex items-center justify-between p-5 border-b border-[#21262d]">
+            <div className="flex items-center gap-3">
+              <div className="flex items-center justify-center w-9 h-9 rounded-lg" style={{ backgroundColor: meta.colorMuted, border: `1px solid ${meta.color}33` }}>
+                <Database size={16} style={{ color: meta.color }} />
+              </div>
+              <div>
+                <h3 className="text-base font-semibold text-[#e6edf3]">{isEdit ? 'Edit' : 'Add'} {meta.label} connection</h3>
+                <p className="text-xs text-[#667085] mt-0.5">Saved to <code className="text-[#00FFA7] font-mono">.env</code> as <code className="text-[#00FFA7] font-mono">DB_{flavor.toUpperCase()}_N_*</code></p>
+              </div>
+            </div>
+            <button type="button" onClick={onClose} className="p-1.5 rounded-lg text-[#667085] hover:text-[#e6edf3] hover:bg-[#21262d]"><X size={16} /></button>
+          </div>
+
+          <div className="p-5 space-y-4">
+            {error && (
+              <div className="flex items-start gap-2 rounded-lg bg-red-500/10 border border-red-500/25 px-3 py-2 text-xs text-red-300">
+                <AlertCircle size={14} className="shrink-0 mt-0.5" /><span>{error}</span>
+              </div>
+            )}
+
+            <Field label="Label" required hint="How agents refer to this DB (e.g. msgops-dev)">
+              <input type="text" value={form.label} onChange={(e) => update('label', e.target.value)} placeholder="msgops-dev" autoFocus className={inputClass} />
+            </Field>
+
+            <div className="grid grid-cols-[1fr,90px] gap-3">
+              <Field label="Host">
+                <input type="text" value={form.host} onChange={(e) => update('host', e.target.value)} placeholder="db.example.com" className={inputClass} />
+              </Field>
+              <Field label="Port">
+                <input type="number" value={form.port} onChange={(e) => update('port', e.target.value)} placeholder={String(meta.defaultPort)} className={inputClass} />
+              </Field>
+            </div>
+
+            {flavor === 'redis' ? (
+              <Field label="DB index" hint="Redis numeric database (default 0)">
+                <input type="number" min={0} value={form.db} onChange={(e) => update('db', e.target.value)} placeholder="0" className={inputClass} />
+              </Field>
+            ) : (
+              <Field label="Database" hint={flavor === 'mongo' ? 'Optional if included in URI' : undefined}>
+                <input type="text" value={form.database} onChange={(e) => update('database', e.target.value)} placeholder="my_database" className={inputClass} />
+              </Field>
+            )}
+
+            <div className="grid grid-cols-2 gap-3">
+              <Field label={flavor === 'redis' ? 'Username (ACL)' : 'User'} hint={flavor === 'redis' ? 'Optional (Redis 6+ ACL)' : undefined}>
+                <input
+                  type="text"
+                  value={flavor === 'redis' ? form.username : form.user}
+                  onChange={(e) => update(flavor === 'redis' ? 'username' : 'user', e.target.value)}
+                  placeholder={flavor === 'redis' ? 'default' : 'agent_readonly'}
+                  className={inputClass}
+                  autoComplete="off"
+                />
+              </Field>
+              <Field label="Password" hint={isEdit ? 'Leave blank to keep current' : undefined}>
+                <div className="relative">
+                  <input type={showPassword ? 'text' : 'password'} value={form.password} onChange={(e) => update('password', e.target.value)} placeholder={isEdit ? '••••••• (unchanged)' : 'password'} className={inputClass + ' pr-9'} autoComplete="new-password" />
+                  <button type="button" onClick={() => setShowPassword((v) => !v)} className="absolute right-2 top-1/2 -translate-y-1/2 p-1 text-[#667085] hover:text-[#e6edf3]">
+                    {showPassword ? <EyeOff size={14} /> : <Eye size={14} />}
+                  </button>
+                </div>
+              </Field>
+            </div>
+
+            {flavor === 'postgres' && (
+              <Field label="SSL mode" hint="Postgres connection encryption">
+                <select value={form.ssl_mode} onChange={(e) => update('ssl_mode', e.target.value)} className={inputClass}>
+                  {SSL_PLACEHOLDER.map((m) => <option key={m} value={m}>{m || '— none —'}</option>)}
+                </select>
+              </Field>
+            )}
+
+            {(flavor === 'postgres' || flavor === 'mysql') && (
+              <Field label="SSL CA path" hint={flavor === 'postgres' ? 'Optional, for verify-ca / verify-full' : 'Optional, enables TLS verification'}>
+                <input type="text" value={form.ssl_ca_path} onChange={(e) => update('ssl_ca_path', e.target.value)} placeholder="/path/to/ca.pem" className={inputClass} />
+              </Field>
+            )}
+
+            {flavor === 'mongo' && (
+              <div className="grid grid-cols-[1fr,auto] gap-3 items-end">
+                <Field label="Auth source" hint="Optional (e.g. admin)">
+                  <input type="text" value={form.auth_source} onChange={(e) => update('auth_source', e.target.value)} placeholder="admin" className={inputClass} />
+                </Field>
+                <label className="flex items-center gap-2 cursor-pointer select-none pb-2">
+                  <input type="checkbox" checked={form.tls} onChange={(e) => update('tls', e.target.checked)} className="peer sr-only" />
+                  <span className={`w-9 h-5 rounded-full border transition-all flex items-center ${form.tls ? 'bg-[#00FFA7]/30 border-[#00FFA7]/50' : 'bg-[#161b22] border-[#21262d]'}`}>
+                    <span className={`block w-4 h-4 rounded-full transition-all ${form.tls ? 'ml-4 bg-[#00FFA7]' : 'ml-0.5 bg-[#667085]'}`} />
+                  </span>
+                  <span className="text-xs text-[#e6edf3] font-medium">TLS</span>
+                </label>
+              </div>
+            )}
+
+            {flavor === 'redis' && (
+              <label className="flex items-center gap-2.5 cursor-pointer select-none">
+                <input type="checkbox" checked={form.tls} onChange={(e) => update('tls', e.target.checked)} className="peer sr-only" />
+                <span className={`w-9 h-5 rounded-full border transition-all flex items-center ${form.tls ? 'bg-[#00FFA7]/30 border-[#00FFA7]/50' : 'bg-[#161b22] border-[#21262d]'}`}>
+                  <span className={`block w-4 h-4 rounded-full transition-all ${form.tls ? 'ml-4 bg-[#00FFA7]' : 'ml-0.5 bg-[#667085]'}`} />
+                </span>
+                <div>
+                  <span className="text-xs text-[#e6edf3] font-medium">TLS (rediss://)</span>
+                  <p className="text-[10px] text-[#667085] mt-0.5">Enable for managed Redis (Upstash, AWS, etc).</p>
+                </div>
+              </label>
+            )}
+
+            <details className="group rounded-lg border border-[#21262d] bg-[#161b22]/50">
+              <summary className="cursor-pointer px-3 py-2 text-xs text-[#667085] hover:text-[#e6edf3] flex items-center gap-1.5 select-none">
+                <span className="group-open:rotate-90 transition-transform">▸</span> Advanced
+              </summary>
+              <div className="px-3 pb-3 pt-1 space-y-3">
+                {(flavor === 'postgres' || flavor === 'mysql') && (
+                  <Field label="Full DSN (overrides host/port/user/password)" hint="Use only if the components above don't cover your setup">
+                    <input type="text" value={form.dsn} onChange={(e) => update('dsn', e.target.value)} placeholder={flavor === 'postgres' ? 'postgresql://user:pw@host:5432/db' : 'mysql://user:pw@host:3306/db'} className={inputClass + ' font-mono text-xs'} />
+                  </Field>
+                )}
+                {flavor === 'mongo' && (
+                  <Field label="Full URI (overrides host/port/user/password)" hint="Use for Atlas or complex connection strings">
+                    <input type="text" value={form.uri} onChange={(e) => update('uri', e.target.value)} placeholder="mongodb+srv://user:pw@cluster.abc.mongodb.net/db" className={inputClass + ' font-mono text-xs'} />
+                  </Field>
+                )}
+                {flavor === 'redis' && (
+                  <Field label="Full URL (overrides host/port/username/password)" hint="Use for managed Redis (Upstash, AWS, etc)">
+                    <input type="text" value={form.url} onChange={(e) => update('url', e.target.value)} placeholder="rediss://user:pw@host:6380/0" className={inputClass + ' font-mono text-xs'} />
+                  </Field>
+                )}
+
+                <div className="grid grid-cols-2 gap-3">
+                  <Field label="Query timeout (s)">
+                    <input type="number" min={1} value={form.query_timeout} onChange={(e) => update('query_timeout', e.target.value)} className={inputClass} />
+                  </Field>
+                  <Field label="Max rows returned">
+                    <input type="number" min={1} value={form.max_rows} onChange={(e) => update('max_rows', e.target.value)} className={inputClass} />
+                  </Field>
+                </div>
+
+                <label className="flex items-center gap-2.5 cursor-pointer select-none">
+                  <input type="checkbox" checked={form.allow_write} onChange={(e) => update('allow_write', e.target.checked)} className="peer sr-only" />
+                  <span className={`w-9 h-5 rounded-full border transition-all flex items-center ${form.allow_write ? 'bg-amber-500/30 border-amber-500/50' : 'bg-[#161b22] border-[#21262d]'}`}>
+                    <span className={`block w-4 h-4 rounded-full transition-all ${form.allow_write ? 'ml-4 bg-amber-400' : 'ml-0.5 bg-[#667085]'}`} />
+                  </span>
+                  <div>
+                    <span className="text-xs text-[#e6edf3] font-medium">Allow write queries</span>
+                    <p className="text-[10px] text-[#667085] mt-0.5">Default off. When on, DELETE/UPDATE/INSERT are permitted on this DB.</p>
+                  </div>
+                </label>
+              </div>
+            </details>
+          </div>
+
+          <div className="flex items-center justify-end gap-3 px-5 py-4 border-t border-[#21262d] bg-[#0a0f18]">
+            <button type="button" onClick={onClose} className="px-4 py-2 rounded-lg text-sm text-[#667085] hover:text-[#e6edf3] hover:bg-[#21262d] transition-colors">Cancel</button>
+            <button type="submit" disabled={saving} className="flex items-center gap-1.5 px-4 py-2 rounded-lg bg-[#00FFA7] text-[#0C111D] text-sm font-semibold hover:bg-[#00FFA7]/90 transition-colors disabled:opacity-60">
+              {saving && <Loader2 size={14} className="animate-spin" />} {isEdit ? 'Save changes' : 'Add connection'}
+            </button>
+          </div>
+        </form>
+      </div>
+    </div>
+  )
+}
+
+function Field({
+  label,
+  hint,
+  required,
+  children,
+}: {
+  label: string
+  hint?: string
+  required?: boolean
+  children: ReactNode
+  }) {
+  return (
+    <div>
+      <label className="flex items-center gap-1.5 text-xs font-medium text-[#e6edf3] mb-1.5">
+        {label}{required && <span className="text-[#00FFA7]">*</span>}
+      </label>
+      {children}
+      {hint && <p className="text-[10px] text-[#667085] mt-1">{hint}</p>}
+    </div>
+  )
+}
diff --git a/dashboard/frontend/src/pages/integrations/IntegrationCard.tsx b/dashboard/frontend/src/pages/integrations/IntegrationCard.tsx
new file mode 100644
index 00000000..49561bdb
--- /dev/null
+++ b/dashboard/frontend/src/pages/integrations/IntegrationCard.tsx
@@ -0,0 +1,150 @@
+import { Pencil, Settings, Trash2 } from 'lucide-react'
+import { getIntegrationIcon, getTypeMeta, type Integration } from './types'
+import { getIntegrationMeta } from '../../lib/integrationMeta'
+
+interface IntegrationCardProps {
+  int: Integration
+  onSelect: (int: Integration) => void
+  onEdit?: (int: Integration) => void
+  onDelete?: (int: Integration) => void
+}
+
+export function IntegrationCard({ int, onSelect, onEdit, onDelete }: IntegrationCardProps) {
+  const typeMeta = getTypeMeta(int.type)
+  const intIcon = getIntegrationIcon(int.name)
+  const Icon = intIcon?.icon ?? typeMeta.icon
+  const iconColor = intIcon?.color ?? typeMeta.color
+  const iconBg = intIcon?.colorMuted ?? typeMeta.colorMuted
+  const isConnected = int.status === 'ok'
+  const intMeta = int.kind === 'core' ? getIntegrationMeta(int.name) : null
+  const isOAuth = intMeta?.oauthFlow === true
+  const isConfigurable = !isOAuth && (
+    (intMeta?.fields && intMeta.fields.length > 0) ||
+    (int.kind === 'custom' && (int.envKeys?.length ?? 0) > 0)
+  )
+  const isCustom = int.kind === 'custom'
+  const isClickable = !!intMeta || isConfigurable
+
+  return (
+    <div
+      onClick={() => {
+        if (isClickable) onSelect(int)
+      }}
+      role={isClickable ? 'button' : undefined}
+      tabIndex={isClickable ? 0 : undefined}
+      onKeyDown={(e) => {
+        if (isClickable && (e.key === 'Enter' || e.key === ' ')) {
+          e.preventDefault()
+          onSelect(int)
+        }
+      }}
+      aria-label={isClickable ? `Configurar ${int.name}` : undefined}
+      className={[
+        'group relative rounded-xl border border-[#21262d] bg-[#161b22] p-5 transition-all duration-300 hover:border-transparent',
+        isClickable ? 'cursor-pointer' : '',
+      ].join(' ')}
+    >
+      <div
+        className="pointer-events-none absolute inset-0 rounded-xl opacity-0 transition-opacity duration-300 group-hover:opacity-100"
+        style={{
+          boxShadow: isConnected
+            ? 'inset 0 0 0 1px rgba(0,255,167,0.27), 0 0 20px rgba(0,255,167,0.10)'
+            : `inset 0 0 0 1px ${typeMeta.color}44, 0 0 20px ${typeMeta.glowColor}`,
+          borderRadius: 'inherit',
+        }}
+      />
+
+      <div className="relative flex items-start justify-between mb-3">
+        <div
+          className="flex h-10 w-10 items-center justify-center rounded-lg transition-transform duration-300 group-hover:scale-110"
+          style={{ backgroundColor: iconBg }}
+        >
+          <Icon size={20} style={{ color: iconColor }} />
+        </div>
+        <div className="flex items-center gap-1.5">
+          {isCustom && (
+            <>
+              <button
+                type="button"
+                onClick={(e) => {
+                  e.stopPropagation()
+                  onEdit?.(int)
+                }}
+                className="p-1 rounded text-[#667085] hover:text-[#00FFA7] transition-colors opacity-0 group-hover:opacity-100"
+                title="Edit"
+              >
+                <Pencil size={13} />
+              </button>
+              <button
+                type="button"
+                onClick={(e) => {
+                  e.stopPropagation()
+                  onDelete?.(int)
+                }}
+                className="p-1 rounded text-[#667085] hover:text-red-400 transition-colors opacity-0 group-hover:opacity-100"
+                title="Delete"
+              >
+                <Trash2 size={13} />
+              </button>
+            </>
+          )}
+          <span
+            className="inline-block h-2.5 w-2.5 rounded-full mt-1"
+            style={{
+              backgroundColor: isConnected ? '#00FFA7' : '#3F3F46',
+              boxShadow: isConnected ? '0 0 8px rgba(0,255,167,0.5)' : 'none',
+            }}
+          />
+        </div>
+      </div>
+
+      <div className="relative flex items-center gap-2 mb-2">
+        <h3 className="text-[15px] font-semibold text-[#e6edf3] transition-colors duration-200 group-hover:text-white">
+          {int.name}
+        </h3>
+        {isCustom && (
+          <span className="text-[9px] font-semibold uppercase tracking-wider px-1.5 py-0.5 rounded-full bg-[#00FFA7]/10 text-[#00FFA7] border border-[#00FFA7]/20">
+            Custom
+          </span>
+        )}
+      </div>
+
+      {isCustom && int.description && (
+        <p className="relative text-xs text-[#667085] mb-2 line-clamp-2">{int.description}</p>
+      )}
+
+      <div className="relative flex items-center justify-between gap-2">
+        <div className="flex items-center gap-2">
+          <span
+            className="text-[10px] font-medium uppercase tracking-wider px-2 py-0.5 rounded-full border"
+            style={{
+              backgroundColor: typeMeta.colorMuted,
+              color: typeMeta.color,
+              borderColor: `${typeMeta.color}33`,
+            }}
+          >
+            {int.type}
+          </span>
+          <span className={`text-[10px] font-medium px-2 py-0.5 rounded-full border ${
+            isConnected
+              ? 'bg-[#00FFA7]/10 text-[#00FFA7] border-[#00FFA7]/25'
+              : 'bg-[#FBBF24]/10 text-[#FBBF24] border-[#FBBF24]/25'
+          }`}>
+            {isConnected ? 'Connected' : 'Not configured'}
+          </span>
+        </div>
+
+        {isOAuth ? (
+          <span className="flex items-center gap-1 text-[11px] text-[#667085] group-hover:text-[#00FFA7] opacity-0 group-hover:opacity-100 transition-all duration-200">
+            Conectar
+          </span>
+        ) : isConfigurable ? (
+          <span className="flex items-center gap-1 text-[11px] text-[#667085] group-hover:text-[#00FFA7] opacity-0 group-hover:opacity-100 transition-all duration-200">
+            <Settings size={11} />
+            Configurar
+          </span>
+        ) : null}
+      </div>
+    </div>
+  )
+}
diff --git a/dashboard/frontend/src/pages/integrations/SocialAccountsTab.tsx b/dashboard/frontend/src/pages/integrations/SocialAccountsTab.tsx
new file mode 100644
index 00000000..a9865bf3
--- /dev/null
+++ b/dashboard/frontend/src/pages/integrations/SocialAccountsTab.tsx
@@ -0,0 +1,118 @@
+import { CheckCircle2, AlertCircle, Plus, Trash2, Globe } from 'lucide-react'
+import { getPlatformMeta, type SocialPlatform } from './types'
+
+interface SocialAccountsTabProps {
+  platforms: SocialPlatform[]
+  onDisconnect: (platformId: string, index: number) => void
+}
+
+export function SocialAccountsTab({ platforms, onDisconnect }: SocialAccountsTabProps) {
+  return (
+    <div>
+      <div className="flex items-center gap-2.5 mb-6">
+        <div className="flex items-center justify-center w-7 h-7 rounded-lg bg-[#00FFA7]/8 border border-[#00FFA7]/15">
+          <Globe size={14} className="text-[#00FFA7]" />
+        </div>
+        <h2 className="text-base font-semibold text-[#e6edf3]">Social Accounts</h2>
+      </div>
+
+      <div className="space-y-6">
+        {platforms.map((platform) => {
+          const platMeta = getPlatformMeta(platform.id)
+          const PlatIcon = platMeta.icon
+
+          return (
+            <div key={platform.id}>
+              <div className="flex items-center justify-between mb-3">
+                <div className="flex items-center gap-3">
+                  <div
+                    className="flex h-8 w-8 items-center justify-center rounded-lg"
+                    style={{ backgroundColor: platMeta.colorMuted }}
+                  >
+                    <PlatIcon size={16} style={{ color: platMeta.color }} />
+                  </div>
+                  <span className="font-semibold text-[#e6edf3] text-sm">{platform.name}</span>
+                  <span className="text-[11px] px-2 py-0.5 rounded-full bg-white/[0.04] text-[#667085] border border-[#21262d]">
+                    {platform.accounts.length} account{platform.accounts.length !== 1 ? 's' : ''}
+                  </span>
+                </div>
+                <a
+                  href={`/connect/${platform.id}`}
+                  className="flex items-center gap-1.5 text-xs px-3 py-1.5 rounded-full bg-[#00FFA7]/10 text-[#00FFA7] border border-[#00FFA7]/20 hover:bg-[#00FFA7]/20 hover:shadow-[0_0_12px_rgba(0,255,167,0.10)] transition-all"
+                >
+                  <Plus size={13} /> Add account
+                </a>
+              </div>
+
+              {platform.accounts.length > 0 ? (
+                <div className="space-y-2">
+                  {platform.accounts.map((acc) => {
+                    const isOk = acc.status === 'connected'
+                    const isExpiring = acc.status === 'expiring'
+                    const isExpired = acc.status === 'expired'
+
+                    return (
+                      <div
+                        key={acc.index}
+                        className="group relative rounded-xl border border-[#21262d] bg-[#161b22] p-4 flex items-center justify-between transition-all duration-300 hover:border-transparent"
+                      >
+                        <div
+                          className="pointer-events-none absolute inset-0 rounded-xl opacity-0 transition-opacity duration-300 group-hover:opacity-100"
+                          style={{
+                            boxShadow: `inset 0 0 0 1px ${platMeta.color}44, 0 0 16px ${platMeta.glowColor}`,
+                            borderRadius: 'inherit',
+                          }}
+                        />
+
+                        <div className="relative flex items-center gap-3">
+                          <span
+                            className="inline-block w-2.5 h-2.5 rounded-full shrink-0"
+                            style={{
+                              backgroundColor: isOk ? '#00FFA7' : isExpired ? '#EF4444' : isExpiring ? '#FBBF24' : '#3F3F46',
+                              boxShadow: isOk ? '0 0 6px rgba(0,255,167,0.5)' : isExpired ? '0 0 6px rgba(239,68,68,0.5)' : 'none',
+                            }}
+                          />
+                          <div>
+                            <p className="text-sm font-medium text-[#e6edf3]">{acc.label}</p>
+                            <p className="text-xs text-[#667085] mt-0.5">{acc.detail}</p>
+                          </div>
+                        </div>
+
+                        <div className="relative flex items-center gap-2">
+                          <span className={`inline-flex items-center gap-1 text-[10px] font-medium px-2.5 py-1 rounded-full border ${
+                            isOk ? 'bg-[#00FFA7]/10 text-[#00FFA7] border-[#00FFA7]/25' :
+                            isExpiring ? 'bg-[#FBBF24]/10 text-[#FBBF24] border-[#FBBF24]/25' :
+                            isExpired ? 'bg-red-500/10 text-red-400 border-red-500/25' :
+                            'bg-white/[0.04] text-[#667085] border-[#21262d]'
+                          }`}>
+                            {isOk && <CheckCircle2 size={10} />}
+                            {(isExpiring || isExpired) && <AlertCircle size={10} />}
+                            {isOk ? 'Connected' :
+                             isExpiring ? `Expires in ${acc.days_left}d` :
+                             isExpired ? 'Expired' : 'Incomplete'}
+                          </span>
+                          <button
+                            onClick={() => onDisconnect(platform.id, acc.index)}
+                            className="p-1.5 rounded-lg hover:bg-red-500/10 text-[#667085] hover:text-red-400 transition-colors"
+                            title="Remove"
+                          >
+                            <Trash2 size={14} />
+                          </button>
+                        </div>
+                      </div>
+                    )
+                  })}
+                </div>
+              ) : (
+                <div className="rounded-xl border border-dashed border-[#21262d] bg-[#161b22]/50 p-6 text-center">
+                  <p className="text-sm text-[#667085]">No accounts connected</p>
+                  <p className="text-xs text-[#3F3F46] mt-1">Click "Add account" to get started</p>
+                </div>
+              )}
+            </div>
+          )
+        })}
+      </div>
+    </div>
+  )
+}
diff --git a/dashboard/frontend/src/pages/integrations/types.ts b/dashboard/frontend/src/pages/integrations/types.ts
new file mode 100644
index 00000000..44809838
--- /dev/null
+++ b/dashboard/frontend/src/pages/integrations/types.ts
@@ -0,0 +1,226 @@
+import { type LucideIcon, Database, DollarSign, GitBranch, GitFork, Globe, Hash, Image, Key, Mail, MessageSquare, Phone, Plug, Send, Video, Camera, Briefcase, BookOpen, Calendar, Zap, ListTodo } from 'lucide-react'
+
+export interface Integration {
+  name: string
+  type: string
+  status: 'ok' | 'error' | 'pending'
+  kind: 'core' | 'custom'
+  slug?: string
+  description?: string
+  envKeys?: string[]
+  category?: string
+}
+
+export interface SocialAccount {
+  index: number
+  label: string
+  status: string
+  detail: string
+  days_left: number | null
+}
+
+export interface SocialPlatform {
+  id: string
+  name: string
+  icon: string
+  accounts: SocialAccount[]
+  has_connected: boolean
+}
+
+export interface DatabaseConnection {
+  index: number
+  label: string
+  host: string | null
+  port: number | null
+  database: string | null
+  ssl_mode?: string | null
+  tls?: boolean
+  allow_write: boolean
+  query_timeout: number
+  max_rows: number
+}
+
+export interface DatabaseFlavor {
+  slug: 'postgres' | 'mysql' | 'mongo' | 'redis' | string
+  skill: string
+  ok: boolean
+  count: number
+  connections: DatabaseConnection[]
+  error?: string
+}
+
+export type TabKey = 'integrations' | 'social' | 'databases'
+
+export interface CustomIntegrationForm {
+  displayName: string
+  slug: string
+  description: string
+  category: string
+  envKeys: { name: string; value: string }[]
+}
+
+export interface DbFormState {
+  label: string
+  host: string
+  port: string
+  database: string
+  user: string
+  password: string
+  ssl_mode: string
+  ssl_ca_path: string
+  dsn: string
+  uri: string
+  auth_source: string
+  tls: boolean
+  url: string
+  db: string
+  username: string
+  allow_write: boolean
+  query_timeout: string
+  max_rows: string
+}
+
+export interface FlavorMeta {
+  color: string
+  colorMuted: string
+  label: string
+  defaultPort: number
+}
+
+export interface IconMeta {
+  icon: LucideIcon
+  color: string
+  colorMuted: string
+  glowColor?: string
+}
+
+export const TYPE_META: Record<string, IconMeta> = {
+  api: { icon: Globe, color: '#60A5FA', colorMuted: 'rgba(96,165,250,0.12)', glowColor: 'rgba(96,165,250,0.15)' },
+  mcp: { icon: Plug, color: '#A78BFA', colorMuted: 'rgba(167,139,250,0.12)', glowColor: 'rgba(167,139,250,0.15)' },
+  cli: { icon: Database, color: '#22D3EE', colorMuted: 'rgba(34,211,238,0.12)', glowColor: 'rgba(34,211,238,0.15)' },
+  erp: { icon: DollarSign, color: '#34D399', colorMuted: 'rgba(52,211,153,0.12)', glowColor: 'rgba(52,211,153,0.15)' },
+  bot: { icon: MessageSquare, color: '#FBBF24', colorMuted: 'rgba(251,191,36,0.12)', glowColor: 'rgba(251,191,36,0.15)' },
+  oauth: { icon: Globe, color: '#F472B6', colorMuted: 'rgba(244,114,182,0.12)', glowColor: 'rgba(244,114,182,0.15)' },
+}
+
+export const DEFAULT_TYPE: IconMeta = {
+  icon: Plug,
+  color: '#8b949e',
+  colorMuted: 'rgba(139,148,158,0.12)',
+  glowColor: 'rgba(139,148,158,0.15)',
+}
+
+export const INTEGRATION_ICONS: Record<string, IconMeta> = {
+  omie: { icon: DollarSign, color: '#34D399', colorMuted: 'rgba(52,211,153,0.12)' },
+  stripe: { icon: DollarSign, color: '#635BFF', colorMuted: 'rgba(99,91,255,0.12)' },
+  bling: { icon: DollarSign, color: '#3B82F6', colorMuted: 'rgba(59,130,246,0.12)' },
+  asaas: { icon: Zap, color: '#FBBF24', colorMuted: 'rgba(251,191,36,0.12)' },
+  todoist: { icon: ListTodo, color: '#E44332', colorMuted: 'rgba(228,67,50,0.12)' },
+  fathom: { icon: Video, color: '#7C3AED', colorMuted: 'rgba(124,58,237,0.12)' },
+  discord: { icon: Hash, color: '#5865F2', colorMuted: 'rgba(88,101,242,0.12)' },
+  telegram: { icon: Send, color: '#26A5E4', colorMuted: 'rgba(38,165,228,0.12)' },
+  whatsapp: { icon: Phone, color: '#25D366', colorMuted: 'rgba(37,211,102,0.12)' },
+  licensing: { icon: Key, color: '#00FFA7', colorMuted: 'rgba(0,255,167,0.12)' },
+  'evolution api': { icon: MessageSquare, color: '#00FFA7', colorMuted: 'rgba(0,255,167,0.12)' },
+  'evolution go': { icon: GitBranch, color: '#00FFA7', colorMuted: 'rgba(0,255,167,0.12)' },
+  'evo crm': { icon: Database, color: '#00FFA7', colorMuted: 'rgba(0,255,167,0.12)' },
+  'ai image creator': { icon: Image, color: '#F472B6', colorMuted: 'rgba(244,114,182,0.12)' },
+  github: { icon: GitFork, color: '#E6EDF3', colorMuted: 'rgba(230,237,243,0.12)' },
+  linear: { icon: BookOpen, color: '#5E6AD2', colorMuted: 'rgba(94,106,210,0.12)' },
+  'google calendar': { icon: Calendar, color: '#4285F4', colorMuted: 'rgba(66,133,244,0.12)' },
+  gmail: { icon: Mail, color: '#EA4335', colorMuted: 'rgba(234,67,53,0.12)' },
+  youtube: { icon: Video, color: '#FF0000', colorMuted: 'rgba(255,0,0,0.12)' },
+  instagram: { icon: Camera, color: '#E4405F', colorMuted: 'rgba(228,64,95,0.12)' },
+  linkedin: { icon: Briefcase, color: '#0A66C2', colorMuted: 'rgba(10,102,194,0.12)' },
+  notion: { icon: BookOpen, color: '#FFFFFF', colorMuted: 'rgba(255,255,255,0.08)' },
+  canva: { icon: Globe, color: '#00C4CC', colorMuted: 'rgba(0,196,204,0.12)' },
+  figma: { icon: Globe, color: '#A259FF', colorMuted: 'rgba(162,89,255,0.12)' },
+}
+
+export const PLATFORM_ICONS: Record<string, IconMeta> = {
+  youtube: { icon: Video, color: '#EF4444', colorMuted: 'rgba(239,68,68,0.12)', glowColor: 'rgba(239,68,68,0.15)' },
+  instagram: { icon: Camera, color: '#E879F9', colorMuted: 'rgba(232,121,249,0.12)', glowColor: 'rgba(232,121,249,0.15)' },
+  linkedin: { icon: Briefcase, color: '#60A5FA', colorMuted: 'rgba(96,165,250,0.12)', glowColor: 'rgba(96,165,250,0.15)' },
+}
+
+export const DEFAULT_PLATFORM: IconMeta = {
+  icon: Globe,
+  color: '#8b949e',
+  colorMuted: 'rgba(139,148,158,0.12)',
+  glowColor: 'rgba(139,148,158,0.15)',
+}
+
+export const CATEGORY_OPTIONS = [
+  { value: 'messaging', label: 'Messaging' },
+  { value: 'payments', label: 'Payments' },
+  { value: 'crm', label: 'CRM' },
+  { value: 'social', label: 'Social' },
+  { value: 'productivity', label: 'Productivity' },
+  { value: 'other', label: 'Other' },
+]
+
+export const EMPTY_FORM: CustomIntegrationForm = {
+  displayName: '',
+  slug: '',
+  description: '',
+  category: 'other',
+  envKeys: [],
+}
+
+export const DB_FLAVOR_META: Record<string, FlavorMeta> = {
+  postgres: { color: '#00AEEF', colorMuted: 'rgba(0,174,239,0.10)', label: 'Postgres', defaultPort: 5432 },
+  mysql: { color: '#F29111', colorMuted: 'rgba(242,145,17,0.10)', label: 'MySQL', defaultPort: 3306 },
+  mongo: { color: '#4DB33D', colorMuted: 'rgba(77,179,61,0.10)', label: 'MongoDB', defaultPort: 27017 },
+  redis: { color: '#DC382D', colorMuted: 'rgba(220,56,45,0.10)', label: 'Redis', defaultPort: 6379 },
+}
+
+export const EMPTY_DB_FORM: DbFormState = {
+  label: '',
+  host: '',
+  port: '',
+  database: '',
+  user: '',
+  password: '',
+  ssl_mode: '',
+  ssl_ca_path: '',
+  dsn: '',
+  uri: '',
+  auth_source: '',
+  tls: false,
+  url: '',
+  db: '',
+  username: '',
+  allow_write: false,
+  query_timeout: '',
+  max_rows: '',
+}
+
+export const SSL_MODES_POSTGRES = ['', 'disable', 'require', 'verify-ca', 'verify-full']
+
+export const inputClass = 'w-full bg-[#161b22] border border-[#21262d] rounded-lg px-3 py-2 text-sm text-[#e6edf3] placeholder:text-[#3F3F46] focus:outline-none focus:border-[#00FFA7]/40 focus:ring-1 focus:ring-[#00FFA7]/20 transition-colors'
+
+export function getIntegrationIcon(name: string) {
+  const key = Object.keys(INTEGRATION_ICONS).find((k) => name.toLowerCase().includes(k))
+  return key ? INTEGRATION_ICONS[key] : null
+}
+
+export function getTypeMeta(type: string) {
+  if (!type) return DEFAULT_TYPE
+  const key = Object.keys(TYPE_META).find((k) => type.toLowerCase().includes(k))
+  return key ? TYPE_META[key] : DEFAULT_TYPE
+}
+
+export function getPlatformMeta(id: string) {
+  const key = Object.keys(PLATFORM_ICONS).find((k) => id.toLowerCase().includes(k))
+  return key ? PLATFORM_ICONS[key] : DEFAULT_PLATFORM
+}
+
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9 -]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+}
diff --git a/dashboard/frontend/test-results/.last-run.json b/dashboard/frontend/test-results/.last-run.json
new file mode 100644
index 00000000..cbcc1fba
--- /dev/null
+++ b/dashboard/frontend/test-results/.last-run.json
@@ -0,0 +1,4 @@
+{
+  "status": "passed",
+  "failedTests": []
+}
\ No newline at end of file
diff --git a/dashboard/frontend/tests/e2e/setup-login.spec.ts b/dashboard/frontend/tests/e2e/setup-login.spec.ts
new file mode 100644
index 00000000..1f5ec038
--- /dev/null
+++ b/dashboard/frontend/tests/e2e/setup-login.spec.ts
@@ -0,0 +1,37 @@
+import { expect, test } from '@playwright/test'
+
+test('setup and login flow reaches the dashboard', async ({ page, browser }) => {
+  const adminPassword = 'Valid!1234'
+
+  await page.goto('/')
+  await page.locator('input[autocomplete="username"], input[autocomplete="organization"]').first().waitFor({ state: 'visible' })
+  const organizationField = page.locator('input[autocomplete="organization"]')
+  if (await organizationField.count() > 0) {
+    await page.locator('input[autocomplete="name"]').first().fill('Evo Nexus')
+    await organizationField.fill('EvoNexus')
+    await page.getByRole('button', { name: /continue/i }).click()
+  }
+
+  await page.locator('input[autocomplete="username"]').fill('admin')
+  await page.locator('input[autocomplete="email"]').fill('admin@example.com')
+  await page.locator('input[autocomplete="name"]').fill('Admin User')
+
+  const newPasswordInputs = page.locator('input[autocomplete="new-password"]')
+  await newPasswordInputs.nth(0).fill(adminPassword)
+  await newPasswordInputs.nth(1).fill(adminPassword)
+  await page.getByRole('button', { name: /create account/i }).click()
+  await expect(page).toHaveURL(/\/providers$/)
+
+  const loginContext = await browser.newContext()
+  const loginPage = await loginContext.newPage()
+
+  await loginPage.goto('/login')
+  await loginPage.locator('input[autocomplete="username"]').fill('admin')
+  await loginPage.locator('input[autocomplete="current-password"]').fill(adminPassword)
+  await loginPage.getByRole('button', { name: /sign in/i }).click()
+  await expect(loginPage).toHaveURL(/\/providers$/)
+
+  await loginPage.goto('/agents')
+  await expect(loginPage).toHaveURL(/\/agents/)
+  await expect(loginPage.locator('body')).toContainText(/Agents/i)
+})
diff --git a/dashboard/terminal-server/src/claude-bridge.js b/dashboard/terminal-server/src/claude-bridge.js
index baa68ae4..f4d53ad0 100644
--- a/dashboard/terminal-server/src/claude-bridge.js
+++ b/dashboard/terminal-server/src/claude-bridge.js
@@ -5,6 +5,7 @@ const {
   loadProviderConfig,
   resolveProviderModel,
   getProviderMode,
+  getProviderCandidates,
 } = require('./provider-config');
 
 class ClaudeBridge {
@@ -104,11 +105,18 @@ class ClaudeBridge {
 
     try {
       // Reload provider config fresh on every session start
-      // so switching provider in the dashboard takes effect immediately
-      const providerConfig = this._loadProviderConfig();
+      // so switching provider in the dashboard takes effect immediately.
+      // TKR Customization: Use failover provider chain for resilience
+      const activeProviderConfig = this._loadProviderConfig();
+      const providerCandidates = getProviderCandidates('code', activeProviderConfig.provider_id || activeProviderConfig.active);
+      const providerConfig = providerCandidates[0] || activeProviderConfig;
       const providerMode = getProviderMode(providerConfig);
       const providerModel = resolveProviderModel(providerConfig);
 
+      if (providerConfig.provider_id && providerConfig.provider_id !== (activeProviderConfig.provider_id || activeProviderConfig.active)) {
+        console.log(`[failover] Selected provider ${providerConfig.provider_id} after ${activeProviderConfig.provider_id || activeProviderConfig.active} was unavailable`);
+      }
+
       // Block session if no provider is active
       if (!providerConfig.active || providerConfig.active === 'none') {
         const msg = '\r\n\x1b[1;33mNo AI provider is active.\x1b[0m\r\nGo to \x1b[1;32mProviders\x1b[0m in the dashboard to configure and activate a provider.\r\n';
diff --git a/dashboard/terminal-server/src/http-routes.js b/dashboard/terminal-server/src/http-routes.js
new file mode 100644
index 00000000..44956d6a
--- /dev/null
+++ b/dashboard/terminal-server/src/http-routes.js
@@ -0,0 +1,276 @@
+const WebSocket = require('ws');
+const { v4: uuidv4 } = require('uuid');
+
+function registerTerminalHttpRoutes(app, server) {
+  app.get('/api/health', (req, res) => {
+    const snapshot = server.getHealthSnapshot(false);
+    res.status(snapshot.status === 'error' ? 503 : 200).json(snapshot);
+  });
+
+  app.get('/api/health/deep', (req, res) => {
+    const snapshot = server.getHealthSnapshot(true);
+    res.status(snapshot.status === 'error' ? 503 : 200).json(snapshot);
+  });
+
+  // Find-or-create a session for a specific subagent (e.g. 'oracle')
+  app.post('/api/sessions/for-agent', (req, res) => {
+    const { agentName, workingDir, ticketId, systemPromptExtras } = req.body;
+    if (!agentName) {
+      return res.status(400).json({ error: 'agentName is required' });
+    }
+
+    // Scope reuse by (agentName, ticketId) when ticketId is provided.
+    // Without ticketId the old behaviour is preserved (reuse by agentName alone).
+    for (const [id, s] of server.claudeSessions.entries()) {
+      const agentMatch = s.agentName === agentName;
+      const ticketMatch = ticketId ? s.ticketId === ticketId : !s.ticketId;
+      if (agentMatch && ticketMatch) {
+        return res.json({
+          success: true,
+          sessionId: id,
+          reused: true,
+          session: {
+            id,
+            name: s.name,
+            workingDir: s.workingDir,
+            active: s.active,
+            agentName: s.agentName,
+            ticketId: s.ticketId || null,
+          },
+        });
+      }
+    }
+
+    let validWorkingDir = server.baseFolder;
+    if (workingDir) {
+      const validation = server.validatePath(workingDir);
+      if (!validation.valid) {
+        return res.status(403).json({
+          error: validation.error,
+          message: 'Cannot create session with working directory outside the allowed area',
+        });
+      }
+      validWorkingDir = validation.path;
+    }
+
+    const sessionId = uuidv4();
+    const session = {
+      id: sessionId,
+      name: `${agentName} — ${new Date().toLocaleString()}`,
+      created: new Date(),
+      lastActivity: new Date(),
+      active: false,
+      agent: null,
+      agentName,
+      ticketId: ticketId || null,
+      systemPromptExtras: systemPromptExtras || null,
+      workingDir: validWorkingDir,
+      connections: new Set(),
+      outputBuffer: [],
+      maxBufferSize: 1000,
+    };
+    server.claudeSessions.set(sessionId, session);
+    server.requestSessionSave();
+
+    res.json({
+      success: true,
+      sessionId,
+      reused: false,
+      session: {
+        id: sessionId,
+        name: session.name,
+        workingDir: session.workingDir,
+        active: false,
+        agentName,
+        ticketId: ticketId || null,
+      },
+    });
+  });
+
+  // List all sessions for a given agent
+  app.get('/api/sessions/by-agent/:agentName', (req, res) => {
+    const { agentName } = req.params;
+    const sessions = [];
+    for (const [id, s] of server.claudeSessions.entries()) {
+      if (s.agentName === agentName) {
+        // Build preview and find last message timestamp
+        let preview = '';
+        let lastMessageTs = 0;
+        if (Array.isArray(s.chatHistory) && s.chatHistory.length > 0) {
+          // Last message timestamp for sorting
+          const lastMsg = s.chatHistory[s.chatHistory.length - 1];
+          lastMessageTs = lastMsg.ts || 0;
+          // Preview from last user message
+          for (let i = s.chatHistory.length - 1; i >= 0; i--) {
+            if (s.chatHistory[i].role === 'user' && s.chatHistory[i].text) {
+              preview = s.chatHistory[i].text.slice(0, 80);
+              break;
+            }
+          }
+        }
+        sessions.push({
+          id,
+          name: s.name,
+          created: s.created,
+          active: s.active,
+          agentName: s.agentName,
+          ticketId: s.ticketId || null,
+          archived: s.archived || false,
+          lastActivity: lastMessageTs || (s.lastActivity ? new Date(s.lastActivity).getTime() : 0),
+          preview,
+          messageCount: Array.isArray(s.chatHistory) ? s.chatHistory.length : 0,
+        });
+      }
+    }
+    // Sort by lastActivity descending (most recent first)
+    sessions.sort((a, b) => (b.lastActivity || 0) - (a.lastActivity || 0));
+    res.json({ sessions });
+  });
+
+  // Create a NEW session for an agent (always creates, never reuses)
+  app.post('/api/sessions/create', (req, res) => {
+    const { agentName, workingDir } = req.body;
+    if (!agentName) {
+      return res.status(400).json({ error: 'agentName is required' });
+    }
+
+    let validWorkingDir = server.baseFolder;
+    if (workingDir) {
+      const validation = server.validatePath(workingDir);
+      if (!validation.valid) {
+        return res.status(403).json({ error: validation.error });
+      }
+      validWorkingDir = validation.path;
+    }
+
+    // Count existing sessions for this agent to number them
+    let count = 0;
+    for (const s of server.claudeSessions.values()) {
+      if (s.agentName === agentName) count++;
+    }
+
+    const sessionId = uuidv4();
+    const session = {
+      id: sessionId,
+      name: `${agentName} #${count + 1}`,
+      created: new Date(),
+      lastActivity: new Date(),
+      active: false,
+      agent: null,
+      agentName,
+      workingDir: validWorkingDir,
+      connections: new Set(),
+      outputBuffer: [],
+      maxBufferSize: 1000,
+    };
+    server.claudeSessions.set(sessionId, session);
+    server.requestSessionSave();
+
+    res.json({
+      success: true,
+      sessionId,
+      session: {
+        id: sessionId,
+        name: session.name,
+        workingDir: session.workingDir,
+        active: false,
+        agentName,
+      },
+    });
+  });
+
+  app.get('/api/sessions/:sessionId', (req, res) => {
+    const session = server.claudeSessions.get(req.params.sessionId);
+    if (!session) return res.status(404).json({ error: 'Session not found' });
+    res.json({
+      id: session.id,
+      name: session.name,
+      created: session.created,
+      active: session.active,
+      workingDir: session.workingDir,
+      connectedClients: session.connections.size,
+      lastActivity: session.lastActivity,
+      ticketId: session.ticketId || null,
+    });
+  });
+
+  // Bind a session to a ticket (Feature 1.3 — session binding)
+  app.post('/api/sessions/:sessionId/ticket', (req, res) => {
+    const session = server.claudeSessions.get(req.params.sessionId);
+    if (!session) return res.status(404).json({ error: 'Session not found' });
+    const { ticketId } = req.body || {};
+    // ticketId can be null to unbind
+    session.ticketId = ticketId || null;
+    session.lastActivity = new Date();
+    server.requestSessionSave();
+    res.json({ success: true, sessionId: session.id, ticketId: session.ticketId });
+  });
+
+  // Rename or archive a session
+  app.patch('/api/sessions/:sessionId', (req, res) => {
+    const session = server.claudeSessions.get(req.params.sessionId);
+    if (!session) return res.status(404).json({ error: 'Session not found' });
+    const { name, archived } = req.body || {};
+    if (name !== undefined) {
+      if (typeof name !== 'string' || !name.trim()) {
+        return res.status(400).json({ error: 'name must be a non-empty string' });
+      }
+      session.name = name.trim();
+    }
+    if (archived !== undefined) {
+      session.archived = Boolean(archived);
+    }
+    session.lastActivity = new Date();
+    server.requestSessionSave();
+    res.json({
+      id: session.id,
+      name: session.name,
+      archived: session.archived || false,
+      lastActivity: session.lastActivity,
+    });
+  });
+
+  app.delete('/api/sessions/:sessionId', (req, res) => {
+    const sessionId = req.params.sessionId;
+    const session = server.claudeSessions.get(sessionId);
+    if (!session) return res.status(404).json({ error: 'Session not found' });
+
+    if (session.active) server.claudeBridge.stopSession(sessionId);
+
+    session.connections.forEach((wsId) => {
+      const wsInfo = server.webSocketConnections.get(wsId);
+      if (wsInfo && wsInfo.ws.readyState === WebSocket.OPEN) {
+        wsInfo.ws.send(JSON.stringify({ type: 'session_deleted', message: 'Session has been deleted' }));
+        wsInfo.ws.close();
+      }
+    });
+
+    server.claudeSessions.delete(sessionId);
+    server.requestSessionSave();
+    res.json({ success: true, message: 'Session deleted' });
+  });
+
+  // Return all unresolved permission requests across all active sessions
+  app.get('/api/notifications/pending', (req, res) => {
+    const notifications = [];
+    for (const [sessionId, session] of server.claudeSessions.entries()) {
+      const bridgeSession = server.chatBridge.sessions.get(sessionId);
+      if (!bridgeSession?.pendingApprovals) continue;
+      for (const [requestId] of bridgeSession.pendingApprovals.entries()) {
+        notifications.push({
+          id: `agent_awaiting-${sessionId}-${requestId}`,
+          event: 'agent_awaiting',
+          sessionId,
+          agentName: session.agentName || '',
+          toolName: undefined,
+          createdAt: Date.now(),
+        });
+      }
+    }
+    res.json({ notifications });
+  });
+}
+
+module.exports = {
+  registerTerminalHttpRoutes,
+};
diff --git a/dashboard/terminal-server/src/platform-event-broker.js b/dashboard/terminal-server/src/platform-event-broker.js
new file mode 100644
index 00000000..f56099b4
--- /dev/null
+++ b/dashboard/terminal-server/src/platform-event-broker.js
@@ -0,0 +1,100 @@
+const fs = require('fs');
+
+const { PLATFORM_EVENTS_PATH } = require('./platform-support');
+
+function parseJsonl(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return [];
+  }
+
+  const raw = fs.readFileSync(filePath, 'utf8');
+  if (!raw.trim()) {
+    return [];
+  }
+
+  return raw
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+function createPlatformEventBroker(options = {}) {
+  const eventsPath = options.eventsPath || PLATFORM_EVENTS_PATH;
+  const pollIntervalMs = options.pollIntervalMs ?? 2000;
+  const onEvent = typeof options.onEvent === 'function' ? options.onEvent : () => {};
+  const dev = !!options.dev;
+  const logger = options.logger || console;
+
+  let stopped = false;
+  let interval = null;
+  let cursor = 0;
+
+  const ensureCursor = () => {
+    const events = parseJsonl(eventsPath);
+    cursor = events.length;
+  };
+
+  const flush = () => {
+    if (stopped) return;
+
+    const events = parseJsonl(eventsPath);
+    if (events.length < cursor) {
+      cursor = 0;
+    }
+
+    const freshEvents = events.slice(cursor);
+    cursor = events.length;
+
+    for (const event of freshEvents) {
+      try {
+        onEvent(event);
+      } catch (error) {
+        if (dev) {
+          logger.warn?.('[platform-event-broker] handler failed:', error?.message || error);
+        }
+      }
+    }
+  };
+
+  ensureCursor();
+
+  if (pollIntervalMs > 0) {
+    interval = setInterval(flush, pollIntervalMs);
+    if (typeof interval.unref === 'function') {
+      interval.unref();
+    }
+  }
+
+  return {
+    eventsPath,
+    stop() {
+      stopped = true;
+      if (interval) {
+        clearInterval(interval);
+        interval = null;
+      }
+    },
+    flush,
+    status() {
+      return {
+        backend: 'file-poll',
+        active: !stopped,
+        eventsPath,
+        cursor,
+      };
+    },
+  };
+}
+
+module.exports = {
+  createPlatformEventBroker,
+  parseJsonl,
+};
diff --git a/dashboard/terminal-server/src/platform-metrics.js b/dashboard/terminal-server/src/platform-metrics.js
new file mode 100644
index 00000000..ffe81012
--- /dev/null
+++ b/dashboard/terminal-server/src/platform-metrics.js
@@ -0,0 +1,31 @@
+const { PROVIDER_METRICS_PATH, appendJsonl } = require('./platform-support');
+
+function recordProviderEvent({
+  providerId,
+  event,
+  model = null,
+  latencyMs = null,
+  success = null,
+  detail = null,
+  mode = null,
+  metadata = null,
+}) {
+  try {
+    return appendJsonl(PROVIDER_METRICS_PATH, {
+      provider_id: providerId,
+      event,
+      model,
+      latency_ms: latencyMs,
+      success,
+      detail,
+      mode,
+      metadata: metadata || {},
+    });
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  recordProviderEvent,
+};
diff --git a/dashboard/terminal-server/src/platform-support.js b/dashboard/terminal-server/src/platform-support.js
new file mode 100644
index 00000000..2a8ab69a
--- /dev/null
+++ b/dashboard/terminal-server/src/platform-support.js
@@ -0,0 +1,41 @@
+const fs = require('fs');
+const path = require('path');
+
+const WORKSPACE_ROOT = path.resolve(__dirname, '..', '..', '..');
+const PLATFORM_DATA_DIR = path.join(WORKSPACE_ROOT, 'dashboard', 'data', 'platform');
+const PROVIDER_METRICS_PATH = path.join(PLATFORM_DATA_DIR, 'provider-metrics.jsonl');
+const PLATFORM_EVENTS_PATH = path.join(PLATFORM_DATA_DIR, 'events.jsonl');
+
+function ensurePlatformDataDir() {
+  fs.mkdirSync(PLATFORM_DATA_DIR, { recursive: true });
+  return PLATFORM_DATA_DIR;
+}
+
+function appendJsonl(filePath, payload) {
+  ensurePlatformDataDir();
+  const event = {
+    ts: new Date().toISOString(),
+    ...payload,
+  };
+  fs.appendFileSync(filePath, `${JSON.stringify(event)}\n`, 'utf8');
+  return event;
+}
+
+function readJson(filePath, fallback) {
+  try {
+    if (!fs.existsSync(filePath)) return fallback;
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+module.exports = {
+  WORKSPACE_ROOT,
+  PLATFORM_DATA_DIR,
+  PROVIDER_METRICS_PATH,
+  PLATFORM_EVENTS_PATH,
+  ensurePlatformDataDir,
+  appendJsonl,
+  readJson,
+};
diff --git a/dashboard/terminal-server/src/provider-config.js b/dashboard/terminal-server/src/provider-config.js
index 2065d480..1445d4c7 100644
--- a/dashboard/terminal-server/src/provider-config.js
+++ b/dashboard/terminal-server/src/provider-config.js
@@ -3,6 +3,7 @@ const path = require('path');
 
 const WORKSPACE_ROOT = path.resolve(__dirname, '..', '..', '..');
 const PROVIDERS_PATH = path.join(WORKSPACE_ROOT, 'config', 'providers.json');
+const CODEX_AUTH_FILE = path.join(WORKSPACE_ROOT, 'config', 'codex-auth.json');
 
 const ALLOWED_CLI = new Set(['claude', 'openclaude']);
 const ALLOWED_ENV_VARS = new Set([
@@ -24,10 +25,130 @@ const ALLOWED_ENV_VARS = new Set([
   'CLOUD_ML_REGION',
 ]);
 
+// ---- TKR Customization: Failover routing support ----
+const DEFAULT_FAILOVER_ORDER = [
+  'anthropic',
+  'openrouter',
+  'openai',
+  'codex_auth',
+  'gemini',
+  'bedrock',
+  'vertex',
+];
+
 function _normalizeModel(model) {
   return (model || '').trim().toLowerCase();
 }
 
+function loadProvidersFile() {
+  try {
+    if (!fs.existsSync(PROVIDERS_PATH)) {
+      return { active_provider: 'anthropic', providers: {} };
+    }
+    return JSON.parse(fs.readFileSync(PROVIDERS_PATH, 'utf8'));
+  } catch {
+    return { active_provider: 'anthropic', providers: {} };
+  }
+}
+
+function getProviderRouting(config, activeProviderId = null) {
+  const providers = config?.providers || {};
+  const active = activeProviderId || config?.active_provider || 'anthropic';
+  const routing = config?.routing && typeof config.routing === 'object' ? config.routing : {};
+  const seen = new Set();
+  const ordered = [];
+
+  const append = (providerId) => {
+    if (!providerId || seen.has(providerId)) return;
+    const provider = providers[providerId];
+    if (!provider || provider.coming_soon) return;
+    seen.add(providerId);
+    ordered.push(providerId);
+  };
+
+  append(active);
+  if (routing.enabled !== false && Array.isArray(routing.failover_order)) {
+    routing.failover_order.forEach(append);
+  }
+  DEFAULT_FAILOVER_ORDER.forEach(append);
+  Object.keys(providers).forEach(append);
+
+  return {
+    enabled: routing.enabled !== false,
+    failover_order: ordered,
+  };
+}
+
+function buildProviderConfig(config, providerId) {
+  const active = providerId || config?.active_provider || 'anthropic';
+  const provider = config?.providers?.[active] || {};
+
+  let cliCommand = provider.cli_command || 'claude';
+  if (!ALLOWED_CLI.has(cliCommand)) cliCommand = 'claude';
+
+  const envVars = Object.fromEntries(
+    Object.entries(provider.env_vars || {}).filter(
+      ([k, v]) => v !== '' && ALLOWED_ENV_VARS.has(k)
+    )
+  );
+
+  if (active === 'codex_auth' && 'OPENAI_API_KEY' in envVars) {
+    delete envVars.OPENAI_API_KEY;
+  }
+
+  return {
+    provider_id: active,
+    cli_command: cliCommand,
+    env_vars: envVars,
+    active,
+    provider_name: provider.name || active,
+    routing: getProviderRouting(config, active),
+    provider,
+  };
+}
+
+function isProviderReady(providerConfig) {
+  if (!providerConfig || providerConfig.active === 'none') return false;
+  if (providerConfig.active === 'anthropic') return true;
+  if (providerConfig.active === 'codex_auth') {
+    return fs.existsSync(CODEX_AUTH_FILE);
+  }
+
+  const env = providerConfig.env_vars || {};
+  const requiredKeys = Object.keys(env).filter((key) =>
+    /API_KEY|TOKEN|BEARER|PROJECT_ID|AUTH_JSON_PATH/.test(key)
+  );
+  return requiredKeys.some((key) => Boolean((env[key] || '').trim()));
+}
+
+function supportsMode(providerConfig, mode) {
+  if (!providerConfig) return false;
+  if (mode === 'chat') {
+    return providerConfig.active !== 'anthropic' && providerConfig.cli_command === 'openclaude';
+  }
+  if (mode === 'code') {
+    if (providerConfig.active === 'anthropic') return true;
+    return getProviderMode(providerConfig) === 'code';
+  }
+  return true;
+}
+
+function resolveProviderChain(mode = 'chat', preferredProviderId = null) {
+  const config = loadProvidersFile();
+  const routing = getProviderRouting(config, preferredProviderId || config.active_provider);
+  const providers = config.providers || {};
+  return routing.failover_order
+    .map((providerId) => buildProviderConfig(config, providerId))
+    .filter((providerConfig) => providers[providerConfig.provider_id])
+    .filter((providerConfig) => supportsMode(providerConfig, mode))
+    .filter((providerConfig) => isProviderReady(providerConfig));
+}
+
+function getProviderCandidates(mode = 'chat', preferredProviderId = null) {
+  return resolveProviderChain(mode, preferredProviderId);
+}
+// ---- End TKR Customization ----
+
 function isCodeModel(model) {
   const m = _normalizeModel(model);
   if (!m) return false;
@@ -46,9 +167,12 @@ function isChatCompletionModel(model) {
 
 function resolveProviderModel(providerConfig) {
   const env = providerConfig?.env_vars || {};
+  const provider = providerConfig?.provider || {};
   const active = providerConfig?.active || 'anthropic';
   const fromEnv = (env.OPENAI_MODEL || '').trim();
   if (fromEnv) return fromEnv;
+  const fromDefault = (provider.default_model || '').trim();
+  if (fromDefault) return fromDefault;
   if (active === 'codex_auth') return 'codexplan';
   if (active === 'openai') return 'gpt-4.1';
   return '';
@@ -62,45 +186,30 @@ function getProviderMode(providerConfig) {
   return 'chat';
 }
 
-function loadProviderConfig() {
+function loadProviderConfig(providerId = null) {
+  const config = loadProvidersFile();
   try {
-    if (!fs.existsSync(PROVIDERS_PATH)) {
-      return { cli_command: 'claude', env_vars: {}, active: 'anthropic' };
-    }
-
-    const config = JSON.parse(fs.readFileSync(PROVIDERS_PATH, 'utf8'));
-    const active = config.active_provider || 'anthropic';
-    const provider = config.providers?.[active] || {};
-
-    let cliCommand = provider.cli_command || 'claude';
-    if (!ALLOWED_CLI.has(cliCommand)) cliCommand = 'claude';
-
-    const envVars = Object.fromEntries(
-      Object.entries(provider.env_vars || {}).filter(
-        ([k, v]) => v !== '' && ALLOWED_ENV_VARS.has(k)
-      )
-    );
-
-    if (active === 'codex_auth' && 'OPENAI_API_KEY' in envVars) {
-      delete envVars.OPENAI_API_KEY;
-    }
-
+    return buildProviderConfig(config, providerId || config.active_provider || 'anthropic');
+  } catch {
     return {
-      cli_command: cliCommand,
-      env_vars: envVars,
-      active,
-      provider_name: provider.name || active,
+      provider_id: providerId || 'anthropic',
+      cli_command: 'claude',
+      env_vars: {},
+      active: providerId || 'anthropic',
+      provider_name: providerId || 'anthropic',
+      routing: { enabled: true, failover_order: [providerId || 'anthropic'] },
+      provider: {},
     };
-  } catch {
-    return { cli_command: 'claude', env_vars: {}, active: 'anthropic' };
   }
 }
 
 module.exports = {
   loadProviderConfig,
+  loadProvidersFile,
+  resolveProviderChain,
+  getProviderCandidates,
   resolveProviderModel,
   getProviderMode,
   isCodeModel,
   isChatCompletionModel,
 };
-
diff --git a/dashboard/terminal-server/src/runtime-config.js b/dashboard/terminal-server/src/runtime-config.js
new file mode 100644
index 00000000..36ba8d97
--- /dev/null
+++ b/dashboard/terminal-server/src/runtime-config.js
@@ -0,0 +1,41 @@
+function parsePositiveNumber(raw, fallback) {
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value < 0) {
+    return fallback;
+  }
+  return value;
+}
+
+function resolveTerminalServerConfig(options = {}) {
+  const envPort = parsePositiveNumber(process.env.TERMINAL_SERVER_PORT, null);
+  const ttlHours = parsePositiveNumber(process.env.TERMINAL_SESSION_TTL_HOURS, null);
+  const gcMinutes = parsePositiveNumber(process.env.TERMINAL_SESSION_GC_INTERVAL_MINUTES, null);
+  const heartbeatTimeout = parsePositiveNumber(process.env.TERMINAL_WS_HEARTBEAT_TIMEOUT_MS, null);
+  const heartbeatSweep = parsePositiveNumber(process.env.TERMINAL_WS_HEARTBEAT_SWEEP_INTERVAL_MS, null);
+  const envBaseFolder = process.env.TERMINAL_SERVER_BASE_FOLDER?.trim();
+
+  return {
+    port: options.port || envPort || 32352,
+    dev: options.dev || false,
+    baseFolder: options.baseFolder || envBaseFolder || process.cwd(),
+    sessionTtlMs: options.sessionTtlMs ?? (
+      ttlHours && ttlHours > 0 ? ttlHours * 60 * 60 * 1000 : (24 * 60 * 60 * 1000)
+    ),
+    sessionGcIntervalMs: options.sessionGcIntervalMs ?? (
+      gcMinutes !== null && gcMinutes >= 0 ? gcMinutes * 60 * 1000 : (15 * 60 * 1000)
+    ),
+    autoSaveIntervalMs: options.autoSaveIntervalMs ?? 30000,
+    sessionSaveDebounceMs: options.sessionSaveDebounceMs ?? 2000,
+    wsHeartbeatTimeoutMs: options.wsHeartbeatTimeoutMs ?? (
+      heartbeatTimeout && heartbeatTimeout > 0 ? heartbeatTimeout : (60 * 1000)
+    ),
+    wsHeartbeatSweepIntervalMs: options.wsHeartbeatSweepIntervalMs ?? (
+      heartbeatSweep && heartbeatSweep > 0 ? heartbeatSweep : (15 * 1000)
+    ),
+  };
+}
+
+module.exports = {
+  parsePositiveNumber,
+  resolveTerminalServerConfig,
+};
diff --git a/dashboard/terminal-server/src/terminal-server-runtime.js b/dashboard/terminal-server/src/terminal-server-runtime.js
new file mode 100644
index 00000000..51446a53
--- /dev/null
+++ b/dashboard/terminal-server/src/terminal-server-runtime.js
@@ -0,0 +1,1025 @@
+const express = require('express');
+const http = require('http');
+const path = require('path');
+const fs = require('fs');
+const WebSocket = require('ws');
+const cors = require('cors');
+const { v4: uuidv4 } = require('uuid');
+const ClaudeBridge = require('./claude-bridge');
+const { ChatBridge } = require('./chat-bridge');
+const { registerTerminalHttpRoutes } = require('./http-routes');
+const { resolveTerminalServerConfig } = require('./runtime-config');
+const SessionStore = require('./utils/session-store');
+const ChatLogger = require('./utils/chat-logger');
+const TerminalAuditLog = require('./utils/terminal-audit-log');
+const { createPlatformEventBroker } = require('./platform-event-broker');
+const { loadProviderConfig, getProviderMode } = require('./provider-config');
+
+class TerminalServer {
+  constructor(options = {}) {
+    const runtimeConfig = resolveTerminalServerConfig(options);
+    this.port = runtimeConfig.port;
+    this.dev = runtimeConfig.dev;
+    this.baseFolder = runtimeConfig.baseFolder;
+    this.sessionTtlMs = runtimeConfig.sessionTtlMs;
+    this.sessionGcIntervalMs = runtimeConfig.sessionGcIntervalMs;
+    this.autoSaveIntervalMs = runtimeConfig.autoSaveIntervalMs;
+    this.sessionSaveDebounceMs = runtimeConfig.sessionSaveDebounceMs;
+    this.wsHeartbeatTimeoutMs = runtimeConfig.wsHeartbeatTimeoutMs;
+    this.wsHeartbeatSweepIntervalMs = runtimeConfig.wsHeartbeatSweepIntervalMs;
+
+    this.app = express();
+    this.claudeSessions = new Map();
+    this.webSocketConnections = new Map();
+    this.globalSubscribers = new Set(); // wsIds subscribed to global notifications
+    this.claudeBridge = new ClaudeBridge();
+    this.chatBridge = new ChatBridge();
+    this.sessionStore = new SessionStore({ sessionTtlMs: this.sessionTtlMs });
+    this.chatLogger = new ChatLogger(this.baseFolder);
+    this.auditLogger = new TerminalAuditLog(this.baseFolder);
+    this.platformEvents = [];
+    this.platformEventBroker = createPlatformEventBroker({
+      onEvent: (event) => this.handlePlatformEvent(event),
+      dev: this.dev,
+    });
+    this.autoSaveInterval = null;
+    this.sessionGcInterval = null;
+    this.wsHeartbeatInterval = null;
+    this._sessionSaveTimer = null;
+    this._sessionSavePromise = null;
+    this._sessionSaveResolve = null;
+    this.isShuttingDown = false;
+    this._beforeExitSaved = false;
+    this._handleSigint = () => this.handleShutdown();
+    this._handleSigterm = () => this.handleShutdown();
+    this._handleBeforeExit = () => {
+      if (this._beforeExitSaved) return;
+      this._beforeExitSaved = true;
+      void this.saveSessionsToDisk();
+    };
+    this.ready = this.loadPersistedSessions();
+
+    this.setupExpress();
+    this.setupAutoSave();
+    this.setupSessionGc();
+    this.setupHeartbeatMonitor();
+  }
+
+  async loadPersistedSessions() {
+    try {
+      const sessions = await this.sessionStore.loadSessions();
+      this.claudeSessions = sessions;
+      if (sessions.size > 0) {
+        console.log(`Loaded ${sessions.size} persisted sessions`);
+      }
+    } catch (error) {
+      console.error('Failed to load persisted sessions:', error);
+    }
+  }
+
+  setupAutoSave() {
+    if (this.autoSaveIntervalMs > 0) {
+      this.autoSaveInterval = setInterval(() => {
+        this.requestSessionSave();
+      }, this.autoSaveIntervalMs);
+    }
+
+    process.on('SIGINT', this._handleSigint);
+    process.on('SIGTERM', this._handleSigterm);
+    process.on('beforeExit', this._handleBeforeExit);
+  }
+
+  setupSessionGc() {
+    if (this.sessionGcIntervalMs <= 0) {
+      return;
+    }
+
+    this.sessionGcInterval = setInterval(() => {
+      void this.purgeStaleSessions();
+    }, this.sessionGcIntervalMs);
+  }
+
+  setupHeartbeatMonitor() {
+    if (this.wsHeartbeatSweepIntervalMs <= 0 || this.wsHeartbeatTimeoutMs <= 0) {
+      return;
+    }
+
+    this.wsHeartbeatInterval = setInterval(() => {
+      void this.purgeStaleWebSocketConnections();
+    }, this.wsHeartbeatSweepIntervalMs);
+  }
+
+  async saveSessionsToDisk() {
+    if (this._sessionSaveTimer) {
+      clearTimeout(this._sessionSaveTimer);
+      this._sessionSaveTimer = null;
+      this._sessionSaveResolve = null;
+      this._sessionSavePromise = null;
+    }
+    if (this.claudeSessions.size === 0 && !fs.existsSync(this.sessionStore.sessionsFile)) {
+      return true;
+    }
+    return await this.sessionStore.saveSessions(this.claudeSessions);
+  }
+
+  requestSessionSave() {
+    if (this._sessionSaveTimer) {
+      return this._sessionSavePromise || Promise.resolve(false);
+    }
+
+    this._sessionSavePromise = new Promise((resolve) => {
+      this._sessionSaveResolve = resolve;
+    });
+
+    this._sessionSaveTimer = setTimeout(async () => {
+      this._sessionSaveTimer = null;
+      try {
+        const result = await this.saveSessionsToDisk();
+        this._sessionSaveResolve?.(result);
+      } catch (error) {
+        this._sessionSaveResolve?.(false);
+        if (this.dev) console.error('Failed to save sessions after debounce:', error);
+      } finally {
+        this._sessionSaveResolve = null;
+        this._sessionSavePromise = null;
+      }
+    }, this.sessionSaveDebounceMs);
+
+    if (typeof this._sessionSaveTimer.unref === 'function') {
+      this._sessionSaveTimer.unref();
+    }
+
+    return this._sessionSavePromise;
+  }
+
+  recordAuditEvent(action, wsInfo, target, extra = {}) {
+    if (!this.auditLogger) return;
+    this.auditLogger.append({
+      action,
+      actor: {
+        wsId: wsInfo?.id || null,
+        remoteAddress: wsInfo?.remoteAddress || null,
+      },
+      target,
+      ...extra,
+    });
+  }
+
+  handlePlatformEvent(event) {
+    if (!event || typeof event !== 'object') {
+      return;
+    }
+
+    this.platformEvents.push(event);
+    if (this.platformEvents.length > 100) {
+      this.platformEvents.shift();
+    }
+
+    if (this.dev) {
+      console.log(`[platform-event] ${event.topic || 'unknown'} from ${event.source || 'unknown'}`);
+    }
+
+    this.broadcastToGlobalSubscribers({
+      type: 'platform_event',
+      event,
+    });
+  }
+
+  async purgeStaleWebSocketConnections() {
+    const now = Date.now();
+    let closed = 0;
+
+    for (const [wsId, wsInfo] of this.webSocketConnections.entries()) {
+      const lastHeartbeatAt = Number(wsInfo.lastHeartbeatAt || 0);
+      if (!lastHeartbeatAt || (now - lastHeartbeatAt) <= this.wsHeartbeatTimeoutMs) {
+        continue;
+      }
+
+      if (this.dev) {
+        console.warn(`Closing stale WebSocket ${wsId} after ${now - lastHeartbeatAt}ms without heartbeat`);
+      }
+
+      this.recordAuditEvent(
+        'ws_timeout',
+        wsInfo,
+        { wsId, sessionId: wsInfo.claudeSessionId || null },
+        { elapsedMs: now - lastHeartbeatAt },
+      );
+
+      try {
+        if (typeof wsInfo.ws.terminate === 'function') {
+          wsInfo.ws.terminate();
+        } else if (typeof wsInfo.ws.close === 'function') {
+          wsInfo.ws.close(4000, 'Heartbeat timeout');
+        }
+      } catch {}
+
+      this.cleanupWebSocketConnection(wsId);
+      closed += 1;
+    }
+
+    return { closed };
+  }
+
+  _checkPathAccess(targetPath, requireWrite = false) {
+    try {
+      const mode = requireWrite ? fs.constants.R_OK | fs.constants.W_OK : fs.constants.R_OK;
+      fs.accessSync(targetPath, mode);
+      return { status: 'ok', path: targetPath };
+    } catch (error) {
+      return {
+        status: 'error',
+        path: targetPath,
+        detail: error.message,
+      };
+    }
+  }
+
+  _getProviderHealth() {
+    try {
+      const providerConfig = loadProviderConfig() || {};
+      const providerMode = getProviderMode(providerConfig);
+      const active = providerConfig.active || 'none';
+      const routing = providerConfig.routing || { enabled: true, failover_order: [active] };
+      if (!active || active === 'none') {
+        return { status: 'warning', active, routing, detail: 'No provider configured' };
+      }
+      if (active !== 'anthropic' && providerMode !== 'code') {
+        return {
+          status: 'warning',
+          active,
+          mode: providerMode,
+          routing,
+          detail: `Provider ${active} is not in code mode`,
+        };
+      }
+      return {
+        status: 'ok',
+        active,
+        mode: providerMode,
+        routing,
+      };
+    } catch (error) {
+      return {
+        status: 'error',
+        detail: error.message,
+      };
+    }
+  }
+
+  getHealthSnapshot(deep = false) {
+    const now = Date.now();
+    let staleSessions = 0;
+    for (const session of this.claudeSessions.values()) {
+      if (this.sessionStore.isSessionStale(session, now)) {
+        staleSessions += 1;
+      }
+    }
+
+    const checks = {
+      storage: this._checkPathAccess(this.sessionStore.storageDir, true),
+      sessions_file: fs.existsSync(this.sessionStore.sessionsFile)
+        ? this._checkPathAccess(this.sessionStore.sessionsFile, false)
+        : { status: 'warning', path: this.sessionStore.sessionsFile, detail: 'Sessions file not created yet' },
+      workspace: this._checkPathAccess(this.baseFolder, false),
+    };
+
+    if (deep) {
+      checks.providers = this._getProviderHealth();
+    }
+
+    const statuses = Object.values(checks).map((check) => check.status);
+    const status = statuses.includes('error')
+      ? 'error'
+      : (statuses.includes('warning') ? 'warning' : 'ok');
+
+    return {
+      status,
+      timestamp: new Date().toISOString(),
+      uptime_seconds: Math.round(process.uptime()),
+      counts: {
+        claudeSessions: this.claudeSessions.size,
+        activeSessions: Array.from(this.claudeSessions.values()).filter((s) => s.active).length,
+        staleSessions,
+        webSocketConnections: this.webSocketConnections.size,
+        globalSubscribers: this.globalSubscribers.size,
+      claudeBridgeSessions: this.claudeBridge.sessions.size,
+      chatBridgeSessions: this.chatBridge.sessions.size,
+      platformEvents: this.platformEvents.length,
+    },
+    memory: process.memoryUsage(),
+    checks,
+  };
+  }
+
+  async purgeStaleSessions() {
+    const now = Date.now();
+    const staleEntries = [];
+    for (const [sessionId, session] of this.claudeSessions.entries()) {
+      if (this.sessionStore.isSessionStale(session, now)) {
+        staleEntries.push([sessionId, session]);
+      }
+    }
+
+    if (staleEntries.length === 0) {
+      return { removed: 0 };
+    }
+
+    let removed = 0;
+    for (const [sessionId, session] of staleEntries) {
+      if (session.active) {
+        continue;
+      }
+
+      const claudeSession = this.claudeBridge.getSession(sessionId);
+      if (claudeSession && claudeSession.active) {
+        continue;
+      }
+      const chatSession = this.chatBridge.getSession(sessionId);
+      if (chatSession && chatSession.active) {
+        continue;
+      }
+
+      this.claudeSessions.delete(sessionId);
+      removed += 1;
+
+      try {
+        await Promise.allSettled([
+          this.claudeBridge.stopSession(sessionId),
+          this.chatBridge.stopSession(sessionId),
+        ]);
+      } catch (error) {
+        if (this.dev) console.warn(`Failed to clean stale session ${sessionId}:`, error.message);
+      }
+    }
+
+    await this.saveSessionsToDisk();
+    return { removed };
+  }
+
+  async handleShutdown() {
+    if (this.isShuttingDown) return;
+    this.isShuttingDown = true;
+    console.log('\nGracefully shutting down...');
+    if (this._sessionSaveTimer) {
+      clearTimeout(this._sessionSaveTimer);
+      this._sessionSaveTimer = null;
+      this._sessionSaveResolve = null;
+      this._sessionSavePromise = null;
+    }
+    process.removeListener('SIGINT', this._handleSigint);
+    process.removeListener('SIGTERM', this._handleSigterm);
+    process.removeListener('beforeExit', this._handleBeforeExit);
+    this._beforeExitSaved = true;
+    await this.saveSessionsToDisk();
+    if (this.autoSaveInterval) clearInterval(this.autoSaveInterval);
+    if (this.sessionGcInterval) clearInterval(this.sessionGcInterval);
+    if (this.wsHeartbeatInterval) clearInterval(this.wsHeartbeatInterval);
+    if (this.platformEventBroker) this.platformEventBroker.stop();
+    this.close();
+    process.exit(0);
+  }
+
+  isPathWithinBase(targetPath) {
+    try {
+      const resolvedTarget = path.resolve(targetPath);
+      const resolvedBase = path.resolve(this.baseFolder);
+      return resolvedTarget.startsWith(resolvedBase);
+    } catch {
+      return false;
+    }
+  }
+
+  validatePath(targetPath) {
+    if (!targetPath) return { valid: false, error: 'Path is required' };
+    const resolvedPath = path.resolve(targetPath);
+    if (!this.isPathWithinBase(resolvedPath)) {
+      return { valid: false, error: 'Access denied: Path is outside the allowed directory' };
+    }
+    return { valid: true, path: resolvedPath };
+  }
+
+  setupExpress() {
+    this.app.use(cors());
+    this.app.use(express.json());
+    registerTerminalHttpRoutes(this.app, this);
+  }
+
+  async start() {
+    await this.ready;
+    const server = http.createServer(this.app);
+
+    this.wss = new WebSocket.Server({ server });
+    this.wss.on('connection', (ws, req) => this.handleWebSocketConnection(ws, req));
+
+    return new Promise((resolve, reject) => {
+      server.listen(this.port, '0.0.0.0', (err) => {
+        if (err) return reject(err);
+        this.server = server;
+        resolve(server);
+      });
+    });
+  }
+
+  handleWebSocketConnection(ws, req) {
+    const wsId = uuidv4();
+    const url = new URL(req.url, 'ws://localhost');
+    const claudeSessionId = url.searchParams.get('sessionId');
+    const remoteAddress = req.socket?.remoteAddress || req.headers['x-forwarded-for'] || 'unknown';
+
+    if (this.dev) console.log(`New WebSocket connection: ${wsId}`);
+
+    const wsInfo = {
+      id: wsId,
+      ws,
+      claudeSessionId: null,
+      created: new Date(),
+      lastHeartbeatAt: Date.now(),
+      remoteAddress,
+      userAgent: req.headers['user-agent'] || null,
+    };
+    this.webSocketConnections.set(wsId, wsInfo);
+    this.recordAuditEvent('ws_connected', wsInfo, { wsId }, { sessionId: claudeSessionId || null });
+
+    // Send pending chat history if session is in chat mode
+    if (claudeSessionId) {
+      const sess = this.claudeSessions.get(claudeSessionId);
+      if (sess?.chatHistory?.length > 0) {
+        this.sendToWebSocket(ws, { type: 'chat_history', messages: sess.chatHistory });
+      }
+    }
+
+    ws.on('message', async (message) => {
+      try {
+        const data = JSON.parse(message);
+        await this.handleMessage(wsId, data);
+      } catch (error) {
+        if (this.dev) console.error('Error handling message:', error);
+        this.sendToWebSocket(ws, { type: 'error', message: 'Failed to process message' });
+      }
+    });
+
+    ws.on('close', () => {
+      if (this.dev) console.log(`WebSocket connection closed: ${wsId}`);
+      this.recordAuditEvent('ws_closed', wsInfo, { wsId, sessionId: wsInfo.claudeSessionId || null });
+      this.cleanupWebSocketConnection(wsId);
+    });
+
+    ws.on('error', (error) => {
+      if (this.dev) console.error(`WebSocket error for connection ${wsId}:`, error);
+      this.cleanupWebSocketConnection(wsId);
+    });
+
+    this.sendToWebSocket(ws, { type: 'connected', connectionId: wsId });
+
+    if (claudeSessionId && this.claudeSessions.has(claudeSessionId)) {
+      this.joinClaudeSession(wsId, claudeSessionId);
+    }
+  }
+
+  async handleMessage(wsId, data) {
+    const wsInfo = this.webSocketConnections.get(wsId);
+    if (!wsInfo) return;
+
+    switch (data.type) {
+      case 'subscribe_global':
+        this.globalSubscribers.add(wsId);
+        break;
+
+      case 'unsubscribe_global':
+        this.globalSubscribers.delete(wsId);
+        break;
+
+      case 'join_session':
+        await this.joinClaudeSession(wsId, data.sessionId);
+        break;
+
+      case 'leave_session':
+        await this.leaveClaudeSession(wsId);
+        break;
+
+      case 'start_claude':
+        await this.startClaude(wsId, data.options || {});
+        break;
+
+      case 'input':
+        if (wsInfo.claudeSessionId) {
+          const session = this.claudeSessions.get(wsInfo.claudeSessionId);
+          if (session && session.connections.has(wsId) && session.active && session.agent === 'claude') {
+            try {
+              await this.claudeBridge.sendInput(wsInfo.claudeSessionId, data.data);
+            } catch (error) {
+              if (this.dev) console.error(`Failed to send input to session ${wsInfo.claudeSessionId}:`, error.message);
+              this.sendToWebSocket(wsInfo.ws, {
+                type: 'error',
+                message: 'Agent is not running in this session. Please start an agent first.',
+              });
+            }
+          }
+        }
+        break;
+
+      case 'chat_send':
+        // Send a chat message via Agent SDK
+        if (wsInfo.claudeSessionId) {
+          const chatSession = this.claudeSessions.get(wsInfo.claudeSessionId);
+          if (chatSession && data.prompt) {
+            chatSession.mode = 'chat';
+            chatSession.active = true;
+            chatSession.lastActivity = new Date();
+            if (!chatSession.chatHistory) chatSession.chatHistory = [];
+
+            // --- Rewind handling ---
+            if (data.rewindFromUuid) {
+              const rewindUuid = data.rewindFromUuid;
+
+              // Find uuid in in-memory cache
+              let cutIdx = chatSession.chatHistory.findIndex(m => m.uuid === rewindUuid);
+
+              // Fall back to JSONL scan if cache is cold or uuid not found
+              if (cutIdx === -1 && chatSession.agentName) {
+                const fromLog = this.chatLogger.read(chatSession.agentName, wsInfo.claudeSessionId);
+                cutIdx = fromLog.findIndex(m => m.uuid === rewindUuid);
+                if (cutIdx !== -1) {
+                  // Sync cache from JSONL
+                  chatSession.chatHistory = fromLog;
+                  cutIdx = chatSession.chatHistory.findIndex(m => m.uuid === rewindUuid);
+                }
+              }
+
+              if (cutIdx === -1) {
+                // uuid not found — error out without mutating state
+                this.sendToWebSocket(wsInfo.ws, {
+                  type: 'chat_error',
+                  message: `Rewind target not found: ${rewindUuid}`,
+                });
+                chatSession.active = false;
+                break;
+              }
+
+              // 1. If a turn is streaming, stop it first
+              if (this.chatBridge.isActive(wsInfo.claudeSessionId)) {
+                await this.chatBridge.stopSession(wsInfo.claudeSessionId);
+              }
+
+              // 2. Null out sdkSessionId so the next turn starts fresh
+              chatSession.sdkSessionId = null;
+              await this.saveSessionsToDisk();
+
+              // 3. Truncate in-memory cache to everything strictly before rewindUuid
+              chatSession.chatHistory = chatSession.chatHistory.slice(0, cutIdx);
+
+              // 4. Append rewind marker to JSONL
+              this.chatLogger.appendRewindMarker(chatSession.agentName, wsInfo.claudeSessionId, rewindUuid);
+            }
+            // --- End rewind handling ---
+
+            // Store user message in history
+            const userMsg = {
+              role: 'user',
+              text: data.prompt,
+              files: data.files || undefined,
+              ts: Date.now(),
+            };
+            chatSession.chatHistory.push(userMsg);
+            this.chatLogger.append(chatSession.agentName, wsInfo.claudeSessionId, userMsg);
+            this.recordAuditEvent(
+              'chat_send',
+              wsInfo,
+              { wsId, sessionId: wsInfo.claudeSessionId },
+              {
+                promptChars: String(data.prompt).length,
+                filesCount: Array.isArray(data.files) ? data.files.length : 0,
+                rewindFromUuid: data.rewindFromUuid || null,
+              },
+            );
+
+            // Accumulate assistant response for history
+            let assistantBlocks = [];
+            let isStreaming = false;
+
+            try {
+              await this.chatBridge.startSession(wsInfo.claudeSessionId, {
+                agentName: chatSession.agentName,
+                workingDir: chatSession.workingDir,
+                prompt: data.prompt,
+                files: data.files,
+                sdkSessionId: chatSession.sdkSessionId || undefined,
+                systemPromptExtras: chatSession.systemPromptExtras || undefined,
+                onMessage: (msg) => {
+                  // Track SDK session ID
+                  if (msg.type === 'session_id' && msg.sdkSessionId) {
+                    chatSession.sdkSessionId = msg.sdkSessionId;
+                    return; // Don't forward internal event
+                  }
+
+                  // Forward permission requests to the WebSocket client.
+                  if (msg.type === 'permission_request') {
+                    const permPayload = {
+                      type: 'permission_request',
+                      sessionId: wsInfo.claudeSessionId,
+                      requestId: msg.requestId,
+                      toolName: msg.toolName,
+                      input: msg.input,
+                      title: msg.title || null,
+                      description: msg.description || null,
+                    };
+                    this.broadcastToSession(wsInfo.claudeSessionId, permPayload);
+                    // Global notification
+                    const createdAt = Date.now();
+                    const inputPreview = msg.input
+                      ? (typeof msg.input === 'string' ? msg.input : JSON.stringify(msg.input)).slice(0, 80)
+                      : undefined;
+                    this.broadcastToGlobalSubscribers({
+                      type: 'notification',
+                      id: `agent_awaiting-${wsInfo.claudeSessionId}-${msg.requestId}`,
+                      event: 'agent_awaiting',
+                      sessionId: wsInfo.claudeSessionId,
+                      agentName: chatSession.agentName || '',
+                      toolName: msg.toolName,
+                      inputPreview,
+                      createdAt,
+                    }, wsInfo.claudeSessionId);
+                    return;
+                  }
+
+                  // Auto-bind session to a ticket when the agent creates one.
+                  // Only binds if not already bound — doesn't overwrite user's manual pick.
+                  if (msg.type === 'ticket_detected' && msg.ticketId) {
+                    if (!chatSession.ticketId) {
+                      chatSession.ticketId = msg.ticketId;
+                      this.broadcastToSession(wsInfo.claudeSessionId, {
+                        type: 'ticket_bound',
+                        ticketId: msg.ticketId,
+                        auto: true,
+                      });
+                    }
+                    return;
+                  }
+
+                  // Build assistant blocks for history
+                  if (msg.type === 'text_start' || msg.type === 'message_start') {
+                    if (!isStreaming) {
+                      isStreaming = true;
+                      assistantBlocks = [];
+                    }
+                  }
+                  if (msg.type === 'text_delta') {
+                    const last = assistantBlocks[assistantBlocks.length - 1];
+                    if (last?.type === 'text') {
+                      last.text += msg.text || '';
+                    } else {
+                      assistantBlocks.push({ type: 'text', text: msg.text || '' });
+                    }
+                  }
+                  if (msg.type === 'tool_use_start') {
+                    assistantBlocks.push({
+                      type: 'tool_use',
+                      toolName: msg.toolName,
+                      toolId: msg.toolId,
+                      input: '',
+                      done: false,
+                    });
+                  }
+                  if (msg.type === 'tool_input_delta') {
+                    const last = assistantBlocks[assistantBlocks.length - 1];
+                    if (last?.type === 'tool_use') {
+                      last.input += msg.json || '';
+                    }
+                  }
+                  if (msg.type === 'block_stop') {
+                    const last = assistantBlocks[assistantBlocks.length - 1];
+                    if (last?.type === 'tool_use') last.done = true;
+                  }
+
+                  // Also broadcast the current assistant blocks for live history
+                  this.broadcastToSession(wsInfo.claudeSessionId, { type: 'chat_event', event: msg });
+                },
+                onError: (err) => {
+                  chatSession.active = false;
+                  this.broadcastToSession(wsInfo.claudeSessionId, {
+                    type: 'chat_error',
+                    message: err.message || 'Unknown error',
+                  });
+                },
+                onComplete: (info) => {
+                  chatSession.active = false;
+                  // Store SDK session ID for future resume
+                  if (info?.sdkSessionId) {
+                    chatSession.sdkSessionId = info.sdkSessionId;
+                  }
+                  // Save assistant message to history
+                  if (assistantBlocks.length > 0) {
+                    const assistantMsg = {
+                      role: 'assistant',
+                      blocks: assistantBlocks,
+                      ts: Date.now(),
+                      streaming: false,
+                    };
+                    chatSession.chatHistory.push(assistantMsg);
+                    this.chatLogger.append(chatSession.agentName, wsInfo.claudeSessionId, assistantMsg);
+                  }
+                  this.requestSessionSave();
+                  this.broadcastToSession(wsInfo.claudeSessionId, { type: 'chat_complete' });
+                  // Global notification — skip if a client is already watching this session
+                  const hasWatcher = chatSession.connections && chatSession.connections.size > 0;
+                  if (!hasWatcher) {
+                    this.broadcastToGlobalSubscribers({
+                      type: 'notification',
+                      id: `agent_finished-${wsInfo.claudeSessionId}-${Date.now()}`,
+                      event: 'agent_finished',
+                      sessionId: wsInfo.claudeSessionId,
+                      agentName: chatSession.agentName || '',
+                      createdAt: Date.now(),
+                    }, wsInfo.claudeSessionId);
+                  }
+                },
+              });
+            } catch (err) {
+              console.error('[chat_send] Error starting chat session:', err);
+              chatSession.active = false;
+              this.sendToWebSocket(wsInfo.ws, { type: 'chat_error', message: err.message || String(err) });
+            }
+          }
+        }
+        break;
+
+      case 'chat_stop':
+        if (wsInfo.claudeSessionId) {
+          this.recordAuditEvent('chat_stop', wsInfo, { wsId, sessionId: wsInfo.claudeSessionId });
+          await this.chatBridge.stopSession(wsInfo.claudeSessionId);
+          const s = this.claudeSessions.get(wsInfo.claudeSessionId);
+          if (s) s.active = false;
+          this.requestSessionSave();
+        }
+        break;
+
+      case 'permission_response':
+        if (wsInfo.claudeSessionId && data.requestId !== undefined) {
+          this.recordAuditEvent(
+            'permission_response',
+            wsInfo,
+            { wsId, sessionId: wsInfo.claudeSessionId, requestId: data.requestId },
+            { approved: !!data.approved },
+          );
+          this.chatBridge.respondToApproval(wsInfo.claudeSessionId, data.requestId, !!data.approved);
+        }
+        break;
+
+      case 'resize':
+        if (wsInfo.claudeSessionId) {
+          const session = this.claudeSessions.get(wsInfo.claudeSessionId);
+          if (session && session.connections.has(wsId) && session.active && session.agent === 'claude') {
+            try {
+              await this.claudeBridge.resize(wsInfo.claudeSessionId, data.cols, data.rows);
+            } catch {
+              if (this.dev) console.log(`Resize ignored - agent not active in session ${wsInfo.claudeSessionId}`);
+            }
+          }
+        }
+        break;
+
+      case 'stop':
+        if (wsInfo.claudeSessionId) {
+          this.recordAuditEvent('stop_request', wsInfo, { wsId, sessionId: wsInfo.claudeSessionId });
+          await this.stopClaude(wsInfo.claudeSessionId);
+        }
+        break;
+
+      case 'ping':
+        wsInfo.lastHeartbeatAt = Date.now();
+        this.sendToWebSocket(wsInfo.ws, { type: 'pong' });
+        break;
+
+      default:
+        if (this.dev) console.log(`Unknown message type: ${data.type}`);
+    }
+  }
+
+  async joinClaudeSession(wsId, claudeSessionId) {
+    const wsInfo = this.webSocketConnections.get(wsId);
+    if (!wsInfo) return;
+
+    const session = this.claudeSessions.get(claudeSessionId);
+    if (!session) {
+      this.sendToWebSocket(wsInfo.ws, { type: 'error', message: 'Session not found' });
+      return;
+    }
+
+    if (wsInfo.claudeSessionId) await this.leaveClaudeSession(wsId);
+
+    wsInfo.claudeSessionId = claudeSessionId;
+    this.recordAuditEvent('join_session', wsInfo, { wsId, sessionId: claudeSessionId });
+    session.connections.add(wsId);
+    session.lastActivity = new Date();
+    session.lastAccessed = Date.now();
+
+    // Restore chat history from JSONL logs if session cache is empty
+    let chatHistory = session.chatHistory || [];
+    if (chatHistory.length === 0 && session.agentName && session.mode === 'chat') {
+      const restored = this.chatLogger.read(session.agentName, claudeSessionId);
+      if (restored.length > 0) {
+        session.chatHistory = restored;
+        chatHistory = restored;
+        if (this.dev) console.log(`[chat-logger] Restored ${restored.length} messages for session ${claudeSessionId}`);
+      }
+    }
+
+    this.sendToWebSocket(wsInfo.ws, {
+      type: 'session_joined',
+      sessionId: claudeSessionId,
+      sessionName: session.name,
+      workingDir: session.workingDir,
+      active: session.active,
+      outputBuffer: session.outputBuffer.slice(-200),
+      chatHistory,
+      ticketId: session.ticketId || null,
+    });
+
+    if (this.dev) console.log(`WebSocket ${wsId} joined session ${claudeSessionId}`);
+  }
+
+  async leaveClaudeSession(wsId) {
+    const wsInfo = this.webSocketConnections.get(wsId);
+    if (!wsInfo || !wsInfo.claudeSessionId) return;
+
+    this.recordAuditEvent('leave_session', wsInfo, { wsId, sessionId: wsInfo.claudeSessionId });
+    const session = this.claudeSessions.get(wsInfo.claudeSessionId);
+    if (session) {
+      session.connections.delete(wsId);
+      session.lastActivity = new Date();
+    }
+
+    wsInfo.claudeSessionId = null;
+    this.sendToWebSocket(wsInfo.ws, { type: 'session_left' });
+  }
+
+  async startClaude(wsId, options) {
+    const wsInfo = this.webSocketConnections.get(wsId);
+    if (!wsInfo || !wsInfo.claudeSessionId) {
+      this.sendToWebSocket(wsInfo?.ws, { type: 'error', message: 'No session joined' });
+      return;
+    }
+
+    const session = this.claudeSessions.get(wsInfo.claudeSessionId);
+    if (!session) return;
+
+    if (session.active) {
+      // Frontend may re-send start_claude on WebSocket reconnect (common
+      // through reverse proxies like Traefik). The session is already
+      // running — replay the buffer and tell the client it's attached
+      // instead of surfacing a misleading error toast.
+      this.sendToWebSocket(wsInfo.ws, { type: 'claude_started', sessionId: wsInfo.claudeSessionId });
+      return;
+    }
+
+    const sessionId = wsInfo.claudeSessionId;
+
+    try {
+      // Ensure agent name from session is passed even if options don't include it
+      const agentForSession = (options && options.agent) || session.agentName || null;
+      if (this.dev) console.log(`Starting agent: ${agentForSession} for session ${sessionId}`);
+
+      console.log(`[startClaude] Agent for session: ${agentForSession}, options.agent: ${options?.agent}`);
+      await this.claudeBridge.startSession(sessionId, {
+        ...options,
+        workingDir: session.workingDir,
+        agent: agentForSession,
+        onOutput: (data) => {
+          const currentSession = this.claudeSessions.get(sessionId);
+          if (!currentSession) return;
+          currentSession.outputBuffer.push(data);
+          if (currentSession.outputBuffer.length > currentSession.maxBufferSize) {
+            currentSession.outputBuffer.shift();
+          }
+          this.broadcastToSession(sessionId, { type: 'output', data });
+        },
+        onExit: (code, signal) => {
+          const currentSession = this.claudeSessions.get(sessionId);
+          if (currentSession) currentSession.active = false;
+          this.broadcastToSession(sessionId, { type: 'exit', code, signal });
+        },
+        onError: (error) => {
+          const currentSession = this.claudeSessions.get(sessionId);
+          if (currentSession) currentSession.active = false;
+          this.broadcastToSession(sessionId, { type: 'error', message: error.message });
+        },
+      });
+
+      session.active = true;
+      session.agent = 'claude';
+      if (options && options.agent) session.agentName = options.agent;
+      session.lastActivity = new Date();
+      if (!session.sessionStartTime) session.sessionStartTime = new Date();
+      this.recordAuditEvent('start_claude', wsInfo, { wsId, sessionId }, { agent: agentForSession || null });
+
+      this.broadcastToSession(sessionId, { type: 'claude_started', sessionId });
+    } catch (error) {
+      if (this.dev) console.error(`Error starting Claude in session ${wsInfo.claudeSessionId}:`, error);
+      this.sendToWebSocket(wsInfo.ws, { type: 'error', message: `Failed to start Claude Code: ${error.message}` });
+    }
+  }
+
+  async stopClaude(claudeSessionId) {
+    const session = this.claudeSessions.get(claudeSessionId);
+    if (!session || !session.active) return;
+
+    await this.claudeBridge.stopSession(claudeSessionId);
+    session.active = false;
+    session.agent = null;
+    session.lastActivity = new Date();
+    const wsInfo = [...this.webSocketConnections.values()].find((item) => item.claudeSessionId === claudeSessionId) || null;
+    this.recordAuditEvent('stop_claude', wsInfo, { sessionId: claudeSessionId });
+    this.requestSessionSave();
+
+    this.broadcastToSession(claudeSessionId, { type: 'claude_stopped' });
+  }
+
+  sendToWebSocket(ws, data) {
+    if (ws && ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(data));
+    }
+  }
+
+  broadcastToSession(claudeSessionId, data) {
+    const session = this.claudeSessions.get(claudeSessionId);
+    if (!session) return;
+
+    session.connections.forEach(wsId => {
+      const wsInfo = this.webSocketConnections.get(wsId);
+      if (wsInfo && wsInfo.claudeSessionId === claudeSessionId && wsInfo.ws.readyState === WebSocket.OPEN) {
+        this.sendToWebSocket(wsInfo.ws, data);
+      }
+    });
+  }
+
+  /**
+   * Broadcast a notification to all global subscribers.
+   * Skips subscribers that are already watching the originating session
+   * (they see events inline and don't need a global notification).
+   *
+   * @param {object} data - Notification payload
+   * @param {string} [originSessionId] - Session that generated the event (used for suppression)
+   */
+  broadcastToGlobalSubscribers(data, originSessionId) {
+    for (const wsId of this.globalSubscribers) {
+      const wsInfo = this.webSocketConnections.get(wsId);
+      if (!wsInfo || wsInfo.ws.readyState !== WebSocket.OPEN) continue;
+      // Suppress if this subscriber is already watching the origin session
+      if (originSessionId && wsInfo.claudeSessionId === originSessionId) continue;
+      this.sendToWebSocket(wsInfo.ws, data);
+    }
+  }
+
+  cleanupWebSocketConnection(wsId) {
+    const wsInfo = this.webSocketConnections.get(wsId);
+    if (!wsInfo) return;
+
+    if (wsInfo.claudeSessionId) {
+      const session = this.claudeSessions.get(wsInfo.claudeSessionId);
+      if (session) {
+        session.connections.delete(wsId);
+        session.lastActivity = new Date();
+        if (session.connections.size === 0 && this.dev) {
+          console.log(`No more connections to session ${wsInfo.claudeSessionId}`);
+        }
+      }
+    }
+
+    this.globalSubscribers.delete(wsId);
+    this.webSocketConnections.delete(wsId);
+  }
+
+  close() {
+    if (this._sessionSaveTimer) {
+      clearTimeout(this._sessionSaveTimer);
+      this._sessionSaveTimer = null;
+      this._sessionSaveResolve = null;
+      this._sessionSavePromise = null;
+    }
+    process.removeListener('SIGINT', this._handleSigint);
+    process.removeListener('SIGTERM', this._handleSigterm);
+    process.removeListener('beforeExit', this._handleBeforeExit);
+    this._beforeExitSaved = true;
+    if (this.autoSaveInterval) clearInterval(this.autoSaveInterval);
+    if (this.sessionGcInterval) clearInterval(this.sessionGcInterval);
+    if (this.wsHeartbeatInterval) clearInterval(this.wsHeartbeatInterval);
+    if (this.platformEventBroker) this.platformEventBroker.stop();
+    if (this.wss) this.wss.close();
+    if (this.server) this.server.close();
+
+    for (const [sessionId, session] of this.claudeSessions.entries()) {
+      if (session.active) this.claudeBridge.stopSession(sessionId);
+    }
+
+    this.claudeSessions.clear();
+    this.webSocketConnections.clear();
+  }
+}
+
+async function startServer(options) {
+  const server = new TerminalServer(options);
+  return await server.start();
+}
+
+module.exports = { startServer, TerminalServer };
diff --git a/dashboard/terminal-server/src/utils/structured-logger.js b/dashboard/terminal-server/src/utils/structured-logger.js
new file mode 100644
index 00000000..804c2c5a
--- /dev/null
+++ b/dashboard/terminal-server/src/utils/structured-logger.js
@@ -0,0 +1,77 @@
+const util = require('util');
+
+function serializeValue(value) {
+  if (value instanceof Error) {
+    return {
+      name: value.name,
+      message: value.message,
+      stack: value.stack,
+    };
+  }
+
+  if (value === null || value === undefined) {
+    return value;
+  }
+
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    return value;
+  }
+
+  if (Buffer.isBuffer(value)) {
+    return {
+      type: 'Buffer',
+      length: value.length,
+    };
+  }
+
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return util.inspect(value, { depth: 4, breakLength: 120 });
+  }
+}
+
+function formatLogEntry(level, args, context = {}) {
+  const normalizedArgs = args.map(serializeValue);
+  const message = normalizedArgs
+    .map((arg) => (typeof arg === 'string' ? arg : JSON.stringify(arg)))
+    .join(' ');
+
+  return {
+    ts: new Date().toISOString(),
+    level,
+    service: context.service || 'terminal-server',
+    component: context.component || 'console',
+    pid: process.pid,
+    message,
+    args: normalizedArgs.length > 1 ? normalizedArgs : undefined,
+  };
+}
+
+function installStructuredConsole(context = {}) {
+  if (process.env.EVONEXUS_STRUCTURED_LOGS === '0') {
+    return;
+  }
+  if (console.__evonexusStructuredInstalled) {
+    return;
+  }
+
+  const writeEntry = (level, args) => {
+    const entry = formatLogEntry(level, args, context);
+    const target = level === 'error' || level === 'warn' ? process.stderr : process.stdout;
+    target.write(`${JSON.stringify(entry)}\n`);
+  };
+
+  console.log = (...args) => writeEntry('info', args);
+  console.info = (...args) => writeEntry('info', args);
+  console.warn = (...args) => writeEntry('warn', args);
+  console.error = (...args) => writeEntry('error', args);
+  console.debug = (...args) => writeEntry('debug', args);
+  console.__evonexusStructuredInstalled = true;
+}
+
+module.exports = {
+  formatLogEntry,
+  installStructuredConsole,
+  serializeValue,
+};
diff --git a/dashboard/terminal-server/src/utils/terminal-audit-log.js b/dashboard/terminal-server/src/utils/terminal-audit-log.js
new file mode 100644
index 00000000..f7d5b831
--- /dev/null
+++ b/dashboard/terminal-server/src/utils/terminal-audit-log.js
@@ -0,0 +1,32 @@
+const fs = require('fs');
+const path = require('path');
+
+class TerminalAuditLog {
+  constructor(workspaceRoot) {
+    this.logsDir = path.join(workspaceRoot || process.cwd(), 'workspace', 'ADWs', 'logs');
+    this.logFile = path.join(this.logsDir, 'terminal-audit.jsonl');
+    this._ensureDir();
+  }
+
+  _ensureDir() {
+    try {
+      fs.mkdirSync(this.logsDir, { recursive: true });
+    } catch {}
+  }
+
+  append(entry) {
+    try {
+      const payload = {
+        ts: new Date().toISOString(),
+        ...entry,
+      };
+      fs.appendFileSync(this.logFile, JSON.stringify(payload) + '\n', 'utf8');
+      return payload;
+    } catch (err) {
+      console.error(`[terminal-audit] Failed to append: ${err.message}`);
+      return null;
+    }
+  }
+}
+
+module.exports = TerminalAuditLog;
diff --git a/dashboard/terminal-server/test/platform-event-broker.test.js b/dashboard/terminal-server/test/platform-event-broker.test.js
new file mode 100644
index 00000000..2ac9999e
--- /dev/null
+++ b/dashboard/terminal-server/test/platform-event-broker.test.js
@@ -0,0 +1,44 @@
+const assert = require('assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const test = require('node:test');
+
+const { createPlatformEventBroker } = require('../src/platform-event-broker');
+
+function makeTempDir(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+test('PlatformEventBroker emits newly appended JSONL events', () => {
+  const tempDir = makeTempDir('evonexus-platform-broker-');
+  const eventsPath = path.join(tempDir, 'events.jsonl');
+  fs.writeFileSync(eventsPath, '', 'utf8');
+
+  const seen = [];
+  const broker = createPlatformEventBroker({
+    eventsPath,
+    pollIntervalMs: 0,
+    onEvent: (event) => {
+      seen.push(event);
+    },
+  });
+
+  fs.appendFileSync(
+    eventsPath,
+    `${JSON.stringify({
+      ts: new Date().toISOString(),
+      topic: 'provider-active-updated',
+      source: 'dashboard',
+      payload: { provider_id: 'openai' },
+    })}\n`,
+    'utf8'
+  );
+
+  broker.flush();
+  broker.stop();
+
+  assert.equal(seen.length, 1);
+  assert.equal(seen[0].topic, 'provider-active-updated');
+  assert.equal(seen[0].payload.provider_id, 'openai');
+});
diff --git a/dashboard/terminal-server/test/provider-config.test.js b/dashboard/terminal-server/test/provider-config.test.js
new file mode 100644
index 00000000..cbe17213
--- /dev/null
+++ b/dashboard/terminal-server/test/provider-config.test.js
@@ -0,0 +1,85 @@
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const test = require('node:test');
+
+const CONFIG_PATH = path.resolve(__dirname, '..', '..', '..', 'config', 'providers.json');
+
+function withProviderConfig(config, fn) {
+  const hadOriginal = fs.existsSync(CONFIG_PATH);
+  const original = hadOriginal ? fs.readFileSync(CONFIG_PATH, 'utf8') : null;
+  fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), 'utf8');
+
+  try {
+    return fn();
+  } finally {
+    if (hadOriginal) {
+      fs.writeFileSync(CONFIG_PATH, original, 'utf8');
+    } else if (fs.existsSync(CONFIG_PATH)) {
+      fs.unlinkSync(CONFIG_PATH);
+    }
+  }
+}
+
+test('provider config resolves routing and ready chat candidates', () => {
+  const config = {
+    active_provider: 'anthropic',
+    routing: {
+      enabled: true,
+      failover_order: ['anthropic', 'openrouter', 'openai'],
+    },
+    providers: {
+      anthropic: {
+        name: 'Anthropic',
+        cli_command: 'claude',
+        env_vars: {},
+      },
+      openrouter: {
+        name: 'OpenRouter',
+        cli_command: 'openclaude',
+        default_model: 'gpt-4.1',
+        env_vars: {
+          CLAUDE_CODE_USE_OPENAI: '1',
+          OPENAI_API_KEY: 'sk-test',
+          OPENAI_MODEL: '',
+        },
+      },
+      openai: {
+        name: 'OpenAI',
+        cli_command: 'openclaude',
+        default_model: 'gpt-4.1',
+        env_vars: {
+          CLAUDE_CODE_USE_OPENAI: '1',
+          OPENAI_API_KEY: '',
+          OPENAI_MODEL: '',
+        },
+      },
+    },
+  };
+
+  withProviderConfig(config, () => {
+    const {
+      getProviderCandidates,
+      getProviderMode,
+      loadProviderConfig,
+      resolveProviderChain,
+      resolveProviderModel,
+    } = require('../src/provider-config');
+
+    const active = loadProviderConfig();
+    assert.equal(active.provider_id, 'anthropic');
+    assert.equal(active.routing.enabled, true);
+    assert.deepEqual(active.routing.failover_order[0], 'anthropic');
+
+    const openrouter = loadProviderConfig('openrouter');
+    assert.equal(resolveProviderModel(openrouter), 'gpt-4.1');
+    assert.equal(getProviderMode(openrouter), 'chat');
+
+    const chain = resolveProviderChain('code', 'openrouter');
+    assert.equal(chain[0].provider_id, 'anthropic');
+
+    const candidates = getProviderCandidates('chat', 'anthropic');
+    assert.deepEqual(candidates.map((candidate) => candidate.provider_id), ['openrouter']);
+  });
+});
diff --git a/dashboard/terminal-server/test/runtime-config.test.js b/dashboard/terminal-server/test/runtime-config.test.js
new file mode 100644
index 00000000..aa27ca38
--- /dev/null
+++ b/dashboard/terminal-server/test/runtime-config.test.js
@@ -0,0 +1,50 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  parsePositiveNumber,
+  resolveTerminalServerConfig,
+} = require('../src/runtime-config');
+
+test('parsePositiveNumber falls back on invalid values', () => {
+  assert.equal(parsePositiveNumber('12', 1), 12);
+  assert.equal(parsePositiveNumber('foo', 1), 1);
+  assert.equal(parsePositiveNumber('-1', 1), 1);
+});
+
+test('resolveTerminalServerConfig reads env overrides', () => {
+  const keys = [
+    'TERMINAL_SESSION_TTL_HOURS',
+    'TERMINAL_SESSION_GC_INTERVAL_MINUTES',
+    'TERMINAL_WS_HEARTBEAT_TIMEOUT_MS',
+    'TERMINAL_WS_HEARTBEAT_SWEEP_INTERVAL_MS',
+    'TERMINAL_SERVER_BASE_FOLDER',
+  ];
+  const snapshot = Object.fromEntries(keys.map((key) => [key, process.env[key]]));
+
+  try {
+    process.env.TERMINAL_SESSION_TTL_HOURS = '36';
+    process.env.TERMINAL_SESSION_GC_INTERVAL_MINUTES = '5';
+    process.env.TERMINAL_WS_HEARTBEAT_TIMEOUT_MS = '45000';
+    process.env.TERMINAL_WS_HEARTBEAT_SWEEP_INTERVAL_MS = '7000';
+    process.env.TERMINAL_SERVER_BASE_FOLDER = 'D:/workspace';
+
+    const config = resolveTerminalServerConfig({ port: 4000, dev: true });
+
+    assert.equal(config.port, 4000);
+    assert.equal(config.dev, true);
+    assert.equal(config.baseFolder, 'D:/workspace');
+    assert.equal(config.sessionTtlMs, 36 * 60 * 60 * 1000);
+    assert.equal(config.sessionGcIntervalMs, 5 * 60 * 1000);
+    assert.equal(config.wsHeartbeatTimeoutMs, 45000);
+    assert.equal(config.wsHeartbeatSweepIntervalMs, 7000);
+  } finally {
+    for (const key of keys) {
+      if (snapshot[key] === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = snapshot[key];
+      }
+    }
+  }
+});
diff --git a/tests/backend/test_auth_security.py b/tests/backend/test_auth_security.py
index 403d6dfc..04e23642 100644
--- a/tests/backend/test_auth_security.py
+++ b/tests/backend/test_auth_security.py
@@ -14,6 +14,8 @@
 BACKEND_DIR = REPO_ROOT / "dashboard" / "backend"
 sys.path.insert(0, str(BACKEND_DIR))
 
+XHR_HEADERS = {"X-Requested-With": "XMLHttpRequest"}
+
 
 @pytest.fixture
 def app():
@@ -81,8 +83,18 @@ def client(app):
         yield c
 
 
+def csrf_headers(client):
+    response = client.get("/api/auth/csrf")
+    token = response.get_json()["csrf_token"]
+    return {**XHR_HEADERS, "X-CSRF-Token": token}
+
+
 def login_admin(client):
-    response = client.post("/api/auth/login", json={"username": "admin", "password": "Valid!123"})
+    response = client.post(
+        "/api/auth/login",
+        json={"username": "admin", "password": "Valid!123"},
+        headers=csrf_headers(client),
+    )
     assert response.status_code == 200
 
 
@@ -119,12 +131,32 @@ def test_create_user_rejects_weak_password(client):
             "password": "weak",
             "role": "viewer",
         },
+        headers=csrf_headers(client),
     )
 
     assert response.status_code == 400
     assert b"Password must be at least 8 characters" in response.data
 
 
+def test_login_requires_xhr_header(client):
+    response = client.post(
+        "/api/auth/login",
+        json={"username": "admin", "password": "Valid!123"},
+    )
+
+    assert response.status_code == 403
+
+
+def test_login_requires_csrf_token(client):
+    response = client.post(
+        "/api/auth/login",
+        json={"username": "admin", "password": "Valid!123"},
+        headers=XHR_HEADERS,
+    )
+
+    assert response.status_code == 403
+
+
 def test_change_password_rejects_weak_password(client):
     login_admin(client)
 
@@ -134,6 +166,7 @@ def test_change_password_rejects_weak_password(client):
             "old_password": "Valid!123",
             "new_password": "weak",
         },
+        headers=csrf_headers(client),
     )
 
     assert response.status_code == 400
@@ -145,12 +178,14 @@ def test_login_locks_after_repeated_failures(client, app):
         response = client.post(
             "/api/auth/login",
             json={"username": "alice", "password": f"wrong-{attempt}"},
+            headers=csrf_headers(client),
         )
         assert response.status_code == 401
 
     locked_response = client.post(
         "/api/auth/login",
         json={"username": "alice", "password": "wrong-final"},
+        headers=csrf_headers(client),
     )
     assert locked_response.status_code == 429
 
@@ -166,8 +201,37 @@ def test_login_locks_after_repeated_failures(client, app):
     success = client.post(
         "/api/auth/login",
         json={"username": "alice", "password": "Strong!234"},
+        headers=csrf_headers(client),
     )
     assert success.status_code == 200
 
     with app.app_context():
         assert LoginThrottle.query.count() == 0
+
+
+def test_login_requires_totp_when_enabled(client, app):
+    from totp_security import generate_totp_code, generate_totp_secret
+    from models import User, db
+
+    secret = generate_totp_secret()
+    with app.app_context():
+      user = User.query.filter_by(username="alice").first()
+      assert user is not None
+      user.enable_totp(secret)
+      db.session.commit()
+
+    response = client.post(
+        "/api/auth/login",
+        json={"username": "alice", "password": "Strong!234"},
+        headers=csrf_headers(client),
+    )
+    assert response.status_code == 412
+    assert response.get_json()["requires_totp"] is True
+
+    code = generate_totp_code(secret)
+    success = client.post(
+        "/api/auth/login",
+        json={"username": "alice", "password": "Strong!234", "totp_code": code},
+        headers=csrf_headers(client),
+    )
+    assert success.status_code == 200
diff --git a/tests/backend/test_health_routes.py b/tests/backend/test_health_routes.py
index 63012bb9..36a0d961 100644
--- a/tests/backend/test_health_routes.py
+++ b/tests/backend/test_health_routes.py
@@ -4,6 +4,7 @@
 
 import importlib
 import json
+import os
 import sys
 from pathlib import Path
 
@@ -36,7 +37,6 @@ def workspace(tmp_path, monkeypatch):
 @pytest.fixture
 def app(workspace, monkeypatch):
     import flask
-    from flask_login import LoginManager
     import models as _models
     import routes.health as _health
 
@@ -51,43 +51,10 @@ def app(workspace, monkeypatch):
     _app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
 
     _models.db.init_app(_app)
-
-    login_manager = LoginManager()
-    login_manager.init_app(_app)
-
-    @login_manager.user_loader
-    def load_user(user_id):
-        return _models.User.query.get(int(user_id))
-
-    @login_manager.unauthorized_handler
-    def unauthorized():
-        return flask.jsonify({"error": "Authentication required"}), 401
-
     _app.register_blueprint(_health.bp)
 
     with _app.app_context():
         _models.db.create_all()
-        _models.seed_roles()
-
-        admin = _models.User(
-            username="admin",
-            email="admin@example.com",
-            display_name="Admin",
-            role="admin",
-        )
-        admin.set_password("Strong!234")
-        _models.db.session.add(admin)
-
-        viewer = _models.User(
-            username="viewer",
-            email="viewer@example.com",
-            display_name="Viewer",
-            role="viewer",
-        )
-        viewer.set_password("Strong!234")
-        _models.db.session.add(viewer)
-
-        _models.db.session.commit()
 
     return _app
 
@@ -98,55 +65,40 @@ def client(app):
         yield c
 
 
-def _login_as(client, username):
-    # Seed a valid flask-login session via the test client without routing
-    # through the full auth blueprint (not registered in this test app).
-    with client.session_transaction() as session:
-        from models import User
-        user = User.query.filter_by(username=username).one()
-        session["_user_id"] = str(user.id)
-        session["_fresh"] = True
-
-
-def test_public_health_returns_only_status(client):
+def test_health_endpoint_reports_ok(client):
     response = client.get("/api/health")
     payload = response.get_json()
 
     assert response.status_code == 200
-    assert payload == {"status": "ok"}
-    # Public endpoint must not leak internal structure.
-    assert "checks" not in payload
-    assert "timestamp" not in payload
+    assert payload["status"] == "ok"
+    assert payload["checks"]["database"]["status"] == "ok"
+    assert payload["checks"]["filesystem"]["status"] == "ok"
+    assert payload["checks"]["workspace"]["status"] == "ok"
+    assert payload["checks"]["secret_key"]["status"] == "ok"
 
 
-def test_deep_health_requires_auth(client):
-    response = client.get("/api/health/deep")
-    assert response.status_code == 401
+def test_live_health_endpoint(client):
+    response = client.get("/api/health/live")
+    payload = response.get_json()
 
+    assert response.status_code == 200
+    assert payload["status"] == "ok"
+    assert payload["checks"]["process"]["status"] == "ok"
 
-def test_deep_health_rejects_non_admin(client, app):
-    with app.test_request_context():
-        _login_as(client, "viewer")
 
-    response = client.get("/api/health/deep")
-    assert response.status_code == 403
+def test_ready_health_endpoint_includes_providers(client):
+    response = client.get("/api/health/ready")
+    payload = response.get_json()
 
+    assert response.status_code == 200
+    assert payload["checks"]["providers"]["status"] == "ok"
+    assert payload["checks"]["providers"]["active"] == "anthropic"
 
-def test_deep_health_includes_providers_for_admin(client, app):
-    with app.test_request_context():
-        _login_as(client, "admin")
 
+def test_deep_health_includes_providers(client):
     response = client.get("/api/health/deep")
     payload = response.get_json()
 
     assert response.status_code == 200
-    assert payload["status"] == "ok"
-    assert payload["checks"]["database"]["status"] == "ok"
-    assert payload["checks"]["filesystem"]["status"] == "ok"
-    assert payload["checks"]["workspace"]["status"] == "ok"
-    assert payload["checks"]["secret_key"]["status"] == "ok"
     assert payload["checks"]["providers"]["status"] == "ok"
     assert payload["checks"]["providers"]["active"] == "anthropic"
-    # Per-check detail must not leak absolute filesystem paths.
-    for check in payload["checks"].values():
-        assert "path" not in check
diff --git a/tests/backend/test_provider_routing.py b/tests/backend/test_provider_routing.py
new file mode 100644
index 00000000..53b938d3
--- /dev/null
+++ b/tests/backend/test_provider_routing.py
@@ -0,0 +1,31 @@
+"""Tests for provider routing helpers."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+BACKEND_DIR = REPO_ROOT / "dashboard" / "backend"
+sys.path.insert(0, str(BACKEND_DIR))
+
+import routes.providers as providers
+
+
+def test_normalize_failover_order_prioritizes_active_provider():
+    provider_map = {
+        "anthropic": {"name": "Anthropic"},
+        "openrouter": {"name": "OpenRouter"},
+        "gemini": {"name": "Gemini", "coming_soon": True},
+    }
+
+    order = providers._normalize_failover_order(  # type: ignore[attr-defined]
+        ["openrouter", "gemini", "anthropic"],
+        provider_map,
+        "anthropic",
+    )
+
+    assert order[0] == "anthropic"
+    assert order[1] == "openrouter"
+    assert "gemini" not in order
diff --git a/tests/backend/test_runtime_config.py b/tests/backend/test_runtime_config.py
new file mode 100644
index 00000000..aa98263b
--- /dev/null
+++ b/tests/backend/test_runtime_config.py
@@ -0,0 +1,90 @@
+"""Tests for backend runtime config helpers."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+
+import pytest
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+BACKEND_DIR = REPO_ROOT / "dashboard" / "backend"
+sys.path.insert(0, str(BACKEND_DIR))
+
+import runtime_config as _runtime_config
+
+
+def test_cors_allowed_origins_from_env(monkeypatch):
+    monkeypatch.setenv("CORS_ALLOWED_ORIGINS", "https://a.example, https://b.example")
+    importlib.reload(_runtime_config)
+
+    assert _runtime_config.cors_allowed_origins() == ["https://a.example", "https://b.example"]
+
+
+def test_load_dashboard_runtime_config_creates_secret_file(tmp_path, monkeypatch):
+    monkeypatch.delenv("EVONEXUS_SECRET_KEY", raising=False)
+    monkeypatch.delenv("EVONEXUS_ENV", raising=False)
+    monkeypatch.delenv("FLASK_ENV", raising=False)
+    monkeypatch.delenv("ENV", raising=False)
+
+    config = _runtime_config.load_dashboard_runtime_config(tmp_path)
+
+    assert _runtime_config.sqlite_path_from_uri(config.database_uri) == tmp_path / "dashboard" / "data" / "evonexus.db"
+    assert config.database_backend == "sqlite"
+    assert config.cors_allowed_origins == "*"
+    assert config.dashboard_port == 8080
+    assert len(config.secret_key) == 64
+    assert (tmp_path / "dashboard" / "data" / ".secret_key").exists()
+
+
+def test_database_uri_prefers_sqlite_env(monkeypatch):
+    monkeypatch.setenv("SQLALCHEMY_DATABASE_URI", "sqlite:///D:/tmp/custom.db")
+
+    assert _runtime_config.database_uri() == "sqlite:///D:/tmp/custom.db"
+
+
+def test_database_uri_prefers_database_url(monkeypatch):
+    monkeypatch.delenv("SQLALCHEMY_DATABASE_URI", raising=False)
+    monkeypatch.delenv("EVONEXUS_DATABASE_URL", raising=False)
+    monkeypatch.setenv("DATABASE_URL", "postgresql://user:pass@localhost:5432/evonexus")
+
+    importlib.reload(_runtime_config)
+
+    assert _runtime_config.database_uri() == "postgresql://user:pass@localhost:5432/evonexus"
+
+
+def test_database_backend_accepts_postgres_uri():
+    assert _runtime_config.database_backend("postgresql://user:pass@localhost:5432/evonexus") == "postgresql"
+    assert _runtime_config.database_backend("D:/tmp/custom.db") == "sqlite"
+
+
+def test_resolve_secret_key_requires_env_in_production(tmp_path, monkeypatch):
+    monkeypatch.setenv("EVONEXUS_ENV", "production")
+    monkeypatch.delenv("EVONEXUS_SECRET_KEY", raising=False)
+
+    with pytest.raises(RuntimeError):
+        _runtime_config.resolve_secret_key(tmp_path)
+
+
+def test_sqlite_path_from_uri():
+    result = _runtime_config.sqlite_path_from_uri("sqlite:///D:/tmp/evonexus.db")
+
+    assert result == Path("D:/tmp/evonexus.db")
+
+
+def test_dashboard_port_prefers_env(monkeypatch, tmp_path):
+    monkeypatch.setenv("EVONEXUS_PORT", "9090")
+    importlib.reload(_runtime_config)
+
+    assert _runtime_config.dashboard_port(tmp_path) == 9090
+
+
+def test_dashboard_port_prefers_port(monkeypatch, tmp_path):
+    monkeypatch.delenv("EVONEXUS_PORT", raising=False)
+    monkeypatch.delenv("DASHBOARD_PORT", raising=False)
+    monkeypatch.setenv("PORT", "8181")
+    importlib.reload(_runtime_config)
+
+    assert _runtime_config.dashboard_port(tmp_path) == 8181

From 19b72b3c10f0b8d7d95e9d40053b3cc7e4569c13 Mon Sep 17 00:00:00 2001
From: jbmendonca <jbmendonca@users.noreply.github.com>
Date: Mon, 27 Apr 2026 16:22:49 -0400
Subject: [PATCH 07/12] fix: export PageSkeleton

---
 .../frontend/src/components/PageStates.tsx      | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/dashboard/frontend/src/components/PageStates.tsx b/dashboard/frontend/src/components/PageStates.tsx
index 2fd856f0..9dba449a 100644
--- a/dashboard/frontend/src/components/PageStates.tsx
+++ b/dashboard/frontend/src/components/PageStates.tsx
@@ -12,6 +12,23 @@ export function FullPageLoader({ label = 'Loading...' }: { label?: string }) {
   )
 }
 
+export function PageSkeleton({ rows = 3, cards = 0 }: { rows?: number; cards?: number }) {
+  return (
+    <div className="animate-pulse space-y-6">
+      {cards > 0 && (
+        <div className="grid gap-4 md:grid-cols-2 xl:grid-cols-4">
+          {Array.from({ length: cards }).map((_, i) => (
+            <div key={i} className="h-24 rounded-2xl bg-[#0f1520]" />
+          ))}
+        </div>
+      )}
+      {Array.from({ length: rows }).map((_, i) => (
+        <div key={i} className="h-16 rounded-2xl bg-[#0f1520]" />
+      ))}
+    </div>
+  )
+}
+
 export function SectionLoader({ label = 'Loading section...' }: { label?: string }) {
   return (
     <div className="flex min-h-[40vh] items-center justify-center px-6 py-12">

From 0ff3ab061249437afc7a12cfbe38d95b4ba322f9 Mon Sep 17 00:00:00 2001
From: jbmendonca <jbmendonca@users.noreply.github.com>
Date: Wed, 29 Apr 2026 21:35:57 -0400
Subject: [PATCH 08/12] fix(onboarding): multi-user auto-skip + 3-layer defense

- Add /api/onboarding/workspace-status endpoint to detect configured workspace
- Auto-skip onboarding in create_user() when workspace is ready
- Fix false positive: check providers.json file exists (not _read_config fallback)
- Auto-skip in OnboardingRouter for pre-existing users with state=null
- Add 'Use existing workspace' button to Welcome screen
- Add translation keys for workspace-ready banner
---
 dashboard/backend/routes/auth_routes.py       | 18 ++++++
 dashboard/backend/routes/onboarding.py        | 54 ++++++++++++++++++
 .../frontend/src/i18n/locales/en-US/index.ts  |  4 ++
 .../src/pages/onboarding/OnboardingRouter.tsx | 56 +++++++++++++++++--
 .../frontend/src/pages/onboarding/Welcome.tsx | 52 +++++++++++++++--
 5 files changed, 175 insertions(+), 9 deletions(-)

diff --git a/dashboard/backend/routes/auth_routes.py b/dashboard/backend/routes/auth_routes.py
index 42160cdb..52934bde 100644
--- a/dashboard/backend/routes/auth_routes.py
+++ b/dashboard/backend/routes/auth_routes.py
@@ -303,6 +303,24 @@ def create_user():
         role=role,
         created_by=current_user.id,
     )
+    # Auto-skip onboarding when the workspace is already configured.
+    # This prevents new team members from being forced through the full
+    # setup wizard when the system is already operational.
+    # NOTE: _read_config() returns a fallback default with
+    # active_provider="anthropic" even when providers.json doesn't exist.
+    # We must check the FILE itself to avoid false positives.
+    try:
+        from routes.providers import _read_config, PROVIDERS_CONFIG
+        from routes._helpers import WORKSPACE
+        if PROVIDERS_CONFIG.is_file():
+            config = _read_config()
+            active_provider = config.get("active_provider")
+            has_provider = bool(active_provider and active_provider != "none")
+            has_workspace = (WORKSPACE / "config" / "workspace.yaml").exists()
+            if has_provider and has_workspace:
+                user.onboarding_state = "skipped"
+    except Exception:
+        pass  # Never block user creation if check fails
     user.set_password(password)
     db.session.add(user)
     db.session.commit()
diff --git a/dashboard/backend/routes/onboarding.py b/dashboard/backend/routes/onboarding.py
index bdc688c6..87fb69f0 100644
--- a/dashboard/backend/routes/onboarding.py
+++ b/dashboard/backend/routes/onboarding.py
@@ -71,6 +71,60 @@ def skip():
     db.session.commit()
     return jsonify({"onboarding_state": "skipped"})
 
+
+@bp.route("/api/onboarding/workspace-status")
+@login_required
+def workspace_status():
+    """Check if the workspace is already configured by another user.
+
+    Returns a JSON object indicating whether the workspace is ready for use
+    without requiring the full onboarding wizard. This is the key endpoint
+    that enables multi-user onboarding: if the workspace is already set up
+    by an admin, new users can skip straight to the dashboard.
+
+    IMPORTANT: _read_config() returns a default fallback of
+    {"active_provider": "anthropic"} even when no providers.json exists on
+    disk.  We must check the FILE exists to avoid false positives.
+    """
+    from pathlib import Path
+    from routes._helpers import WORKSPACE
+    from routes.providers import PROVIDERS_CONFIG
+
+    # Only trust the config if providers.json actually exists on disk.
+    # The fallback default makes active_provider="anthropic" even when
+    # nobody has configured anything yet.
+    providers_file_exists = PROVIDERS_CONFIG.is_file()
+    config = _read_config() if providers_file_exists else {}
+    active_provider = config.get("active_provider")
+    has_provider = bool(
+        providers_file_exists
+        and active_provider
+        and active_provider != "none"
+    )
+
+    # Check if any other user has completed onboarding
+    other_completed = User.query.filter(
+        User.id != current_user.id,
+        User.onboarding_state.in_(["completed", "skipped"])
+    ).count() > 0
+
+    # Check if workspace.yaml exists (created during initial setup)
+    workspace_yaml = WORKSPACE / "config" / "workspace.yaml"
+    has_workspace = workspace_yaml.exists()
+
+    # Workspace is ready if the providers.json FILE truly exists with a
+    # non-none active_provider AND either another user completed onboarding
+    # or the workspace config file exists.
+    workspace_ready = has_provider and (other_completed or has_workspace)
+
+    return jsonify({
+        "workspace_ready": workspace_ready,
+        "has_provider": has_provider,
+        "active_provider": active_provider,
+        "other_users_configured": other_completed,
+        "has_workspace_config": has_workspace,
+    })
+
 @bp.route("/api/onboarding/provider", methods=["POST"])
 @login_required
 def set_provider():
diff --git a/dashboard/frontend/src/i18n/locales/en-US/index.ts b/dashboard/frontend/src/i18n/locales/en-US/index.ts
index 675e120e..2cd3b16e 100644
--- a/dashboard/frontend/src/i18n/locales/en-US/index.ts
+++ b/dashboard/frontend/src/i18n/locales/en-US/index.ts
@@ -196,6 +196,7 @@ const translations = {
       issues: 'Topics',
       reports: 'Reports',
       mempalace: 'MemPalace',
+      agentKnowledge: 'Agent RAG',
       systems: 'Systems',
       templates: 'Templates',
       shareLinks: 'Share Links',
@@ -925,6 +926,9 @@ const translations = {
         configureFromScratch: 'Configure from scratch',
         restoreBrainRepo: 'Restore brain repo',
         restoreHint: "If you've previously set up EvoNexus with a brain repo, use \"Restore\" to recover your configuration.",
+        useExistingWorkspace: 'Use existing workspace',
+        workspaceReadyBanner: 'This workspace is already configured by your team. You can start using it right away — no setup needed.',
+        orSetupManually: 'or set up manually',
       },
       provider: {
         title: 'Choose your AI provider',
diff --git a/dashboard/frontend/src/pages/onboarding/OnboardingRouter.tsx b/dashboard/frontend/src/pages/onboarding/OnboardingRouter.tsx
index b4b15c1e..ac9393a6 100644
--- a/dashboard/frontend/src/pages/onboarding/OnboardingRouter.tsx
+++ b/dashboard/frontend/src/pages/onboarding/OnboardingRouter.tsx
@@ -20,6 +20,14 @@ interface OnboardingState {
   brain_repo: string | null
 }
 
+interface WorkspaceStatus {
+  workspace_ready: boolean
+  has_provider: boolean
+  active_provider: string | null
+  other_users_configured: boolean
+  has_workspace_config: boolean
+}
+
 export default function OnboardingRouter() {
   const navigate = useNavigate()
   const { t } = useTranslation()
@@ -30,6 +38,7 @@ export default function OnboardingRouter() {
   const [selectedProvider, setSelectedProvider] = useState<string | null>(null)
   const [wantBrainRepo, setWantBrainRepo] = useState<boolean | null>(null)
   const [loading, setLoading] = useState(true)
+  const [workspaceReady, setWorkspaceReady] = useState(false)
 
   useEffect(() => {
     // Allow re-entry into a specific sub-flow even after onboarding is completed.
@@ -39,8 +48,13 @@ export default function OnboardingRouter() {
     const params = new URLSearchParams(window.location.search)
     const reconfigure = params.get('reconfigure')
 
-    api.get('/onboarding/state')
-      .then((data: OnboardingState) => {
+    Promise.all([
+      api.get('/onboarding/state'),
+      api.get('/onboarding/workspace-status').catch(() => ({ workspace_ready: false } as WorkspaceStatus)),
+    ])
+      .then(async ([data, wsStatus]: [OnboardingState, WorkspaceStatus]) => {
+        setWorkspaceReady(wsStatus.workspace_ready)
+
         if (reconfigure === 'brain') {
           setFlow('first-time')
           setWantBrainRepo(true)
@@ -52,6 +66,21 @@ export default function OnboardingRouter() {
           navigate('/agents', { replace: true })
           return
         }
+
+        // AUTO-SKIP: If the workspace is already configured by another
+        // user/admin and this user has never started onboarding (state is
+        // null), skip transparently — no wizard needed.  This covers users
+        // created BEFORE the auto-skip logic was added to create_user().
+        if (
+          wsStatus.workspace_ready &&
+          (data.onboarding_state === null || data.onboarding_state === undefined)
+        ) {
+          try { await api.post('/onboarding/skip') } catch { /* ignore */ }
+          await refreshUser()
+          navigate('/agents', { replace: true })
+          return
+        }
+
         if (data.onboarding_state === 'pending') {
           setFlow('first-time')
           setStep(1)
@@ -61,7 +90,7 @@ export default function OnboardingRouter() {
         // No state yet — show welcome
       })
       .finally(() => setLoading(false))
-  }, [navigate])
+  }, [navigate, refreshUser])
 
   const startFirstTime = async () => {
     try {
@@ -101,6 +130,17 @@ export default function OnboardingRouter() {
     navigate('/agents', { replace: true })
   }
 
+  /** "Use existing workspace" — skip onboarding entirely */
+  const handleUseExisting = async () => {
+    try {
+      await api.post('/onboarding/skip')
+    } catch {
+      // ignore
+    }
+    await refreshUser()
+    navigate('/agents', { replace: true })
+  }
+
   if (loading) {
     return (
       <div className="min-h-screen bg-[#080c14] flex items-center justify-center">
@@ -111,7 +151,14 @@ export default function OnboardingRouter() {
 
   // Welcome screen (no flow chosen yet)
   if (flow === null) {
-    return <Welcome onFirstTime={startFirstTime} onRestore={startRestore} />
+    return (
+      <Welcome
+        onFirstTime={startFirstTime}
+        onRestore={startRestore}
+        onUseExisting={handleUseExisting}
+        workspaceReady={workspaceReady}
+      />
+    )
   }
 
   // Restore flow
@@ -184,3 +231,4 @@ export default function OnboardingRouter() {
 
   return null
 }
+
diff --git a/dashboard/frontend/src/pages/onboarding/Welcome.tsx b/dashboard/frontend/src/pages/onboarding/Welcome.tsx
index 52dd58db..f39eb1ed 100644
--- a/dashboard/frontend/src/pages/onboarding/Welcome.tsx
+++ b/dashboard/frontend/src/pages/onboarding/Welcome.tsx
@@ -1,5 +1,6 @@
 import { useRef, useEffect } from 'react'
 import { useTranslation } from 'react-i18next'
+import { CheckCircle2 } from 'lucide-react'
 
 /* ── Animated mesh background (reused from Login.tsx) ── */
 function NetworkCanvas() {
@@ -79,9 +80,11 @@ function NetworkCanvas() {
 interface WelcomeProps {
   onFirstTime: () => void
   onRestore: () => void
+  onUseExisting: () => void
+  workspaceReady: boolean
 }
 
-export default function Welcome({ onFirstTime, onRestore }: WelcomeProps) {
+export default function Welcome({ onFirstTime, onRestore, onUseExisting, workspaceReady }: WelcomeProps) {
   const { t } = useTranslation()
   return (
     <div className="min-h-screen bg-[#080c14] flex items-center justify-center px-4 font-[Inter,-apple-system,sans-serif] relative">
@@ -103,18 +106,56 @@ export default function Welcome({ onFirstTime, onRestore }: WelcomeProps) {
 
           {/* Content */}
           <div className="px-7 py-6 space-y-3">
-            <p className="text-[12px] text-[#5a6b7f] text-center mb-5">
-              {t('onboarding.welcome.chooseHowToStart')}
-            </p>
+
+            {/* Workspace ready banner + primary action */}
+            {workspaceReady && (
+              <>
+                <div className="flex items-start gap-2.5 p-3 rounded-lg bg-[#00FFA7]/8 border border-[#00FFA7]/20">
+                  <CheckCircle2 size={16} className="text-[#00FFA7] flex-shrink-0 mt-0.5" />
+                  <p className="text-[11px] text-[#a0d8c0] leading-relaxed">
+                    {t('onboarding.welcome.workspaceReadyBanner')}
+                  </p>
+                </div>
+
+                <button
+                  id="btn-use-existing-workspace"
+                  onClick={onUseExisting}
+                  className="w-full py-3.5 px-4 rounded-lg bg-[#00FFA7] text-[#080c14] hover:bg-[#00e69a] text-sm font-semibold transition-colors flex items-center justify-center gap-2"
+                >
+                  <CheckCircle2 size={16} />
+                  {t('onboarding.welcome.useExistingWorkspace')}
+                </button>
+
+                <div className="flex items-center gap-3 py-1">
+                  <div className="flex-1 h-px bg-[#152030]" />
+                  <span className="text-[10px] text-[#2d3d4f] uppercase tracking-wider">
+                    {t('onboarding.welcome.orSetupManually')}
+                  </span>
+                  <div className="flex-1 h-px bg-[#152030]" />
+                </div>
+              </>
+            )}
+
+            {!workspaceReady && (
+              <p className="text-[12px] text-[#5a6b7f] text-center mb-5">
+                {t('onboarding.welcome.chooseHowToStart')}
+              </p>
+            )}
 
             <button
+              id="btn-configure-from-scratch"
               onClick={onFirstTime}
-              className="w-full py-3 px-4 rounded-lg bg-[#00FFA7] text-[#080c14] hover:bg-[#00e69a] text-sm font-semibold transition-colors"
+              className={`w-full py-3 px-4 rounded-lg text-sm font-semibold transition-colors ${
+                workspaceReady
+                  ? 'border border-[#152030] text-[#5a6b7f] hover:border-[#00FFA7]/30 hover:text-[#e2e8f0]'
+                  : 'bg-[#00FFA7] text-[#080c14] hover:bg-[#00e69a]'
+              }`}
             >
               {t('onboarding.welcome.configureFromScratch')}
             </button>
 
             <button
+              id="btn-restore-brain-repo"
               onClick={onRestore}
               className="w-full py-3 px-4 rounded-lg border border-[#152030] text-[#5a6b7f] hover:border-[#00FFA7]/30 hover:text-[#e2e8f0] text-sm font-medium transition-colors"
             >
@@ -137,3 +178,4 @@ export default function Welcome({ onFirstTime, onRestore }: WelcomeProps) {
     </div>
   )
 }
+

From 5db7fa7dcc694d42e304888d7649c98840bd0f78 Mon Sep 17 00:00:00 2001
From: jbmendonca <jbmendonca@users.noreply.github.com>
Date: Wed, 29 Apr 2026 22:26:24 -0400
Subject: [PATCH 09/12] fix(users): add reactivation, fix delete feedback, fix
 username conflict

---
 dashboard/backend/routes/auth_routes.py | 55 ++++++++++++++++++++++++-
 dashboard/frontend/src/pages/Users.tsx  | 45 ++++++++++++++++----
 2 files changed, 91 insertions(+), 9 deletions(-)

diff --git a/dashboard/backend/routes/auth_routes.py b/dashboard/backend/routes/auth_routes.py
index 52934bde..e8f941ef 100644
--- a/dashboard/backend/routes/auth_routes.py
+++ b/dashboard/backend/routes/auth_routes.py
@@ -289,7 +289,31 @@ def create_user():
 
     if not username or not password:
         abort(400, description="Username and password required")
-    if User.query.filter_by(username=username).first():
+    existing = User.query.filter_by(username=username).first()
+    if existing:
+        if not existing.is_active:
+            # Reactivate a previously deactivated user instead of blocking
+            existing.is_active = True
+            existing.display_name = _as_text(data.get("display_name")).strip() or username
+            existing.email = _as_text(data.get("email")).strip() or existing.email
+            existing.role = role
+            existing.set_password(password)
+            # Auto-skip onboarding for reactivated users in configured workspaces
+            try:
+                from routes.providers import _read_config, PROVIDERS_CONFIG
+                from routes._helpers import WORKSPACE
+                if PROVIDERS_CONFIG.is_file():
+                    config = _read_config()
+                    active_provider = config.get("active_provider")
+                    has_provider = bool(active_provider and active_provider != "none")
+                    has_workspace = (WORKSPACE / "config" / "workspace.yaml").exists()
+                    if has_provider and has_workspace:
+                        existing.onboarding_state = "skipped"
+            except Exception:
+                pass
+            db.session.commit()
+            audit(current_user, "user_reactivated", f"user:{existing.id}", f"role={role}")
+            return jsonify(existing.to_dict()), 200
         abort(400, description="Username already exists")
     valid_roles = [r.name for r in Role.query.all()]
     if role not in valid_roles:
@@ -368,7 +392,34 @@ def deactivate_user(user_id):
     user.is_active = False
     db.session.commit()
     audit(current_user, "user_deactivated", f"user:{user.id}")
-    return jsonify({"message": "User deactivated"})
+    return jsonify({"status": "ok", "message": "User deactivated", "user": user.to_dict()})
+
+
+@bp.route("/api/users/<int:user_id>/reactivate", methods=["POST"])
+@login_required
+@require_permission("users", "manage")
+def reactivate_user(user_id):
+    """Reactivate a previously deactivated user."""
+    user = User.query.get_or_404(user_id)
+    if user.is_active:
+        return jsonify({"status": "ok", "message": "User is already active", "user": user.to_dict()})
+    user.is_active = True
+    # Auto-skip onboarding for reactivated users in configured workspaces
+    try:
+        from routes.providers import _read_config, PROVIDERS_CONFIG
+        from routes._helpers import WORKSPACE
+        if PROVIDERS_CONFIG.is_file():
+            config = _read_config()
+            active_provider = config.get("active_provider")
+            has_provider = bool(active_provider and active_provider != "none")
+            has_workspace = (WORKSPACE / "config" / "workspace.yaml").exists()
+            if has_provider and has_workspace:
+                user.onboarding_state = "skipped"
+    except Exception:
+        pass
+    db.session.commit()
+    audit(current_user, "user_reactivated", f"user:{user.id}")
+    return jsonify({"status": "ok", "message": "User reactivated", "user": user.to_dict()})
 
 
 # ── Audit (admin only) ───────────────────────────────
diff --git a/dashboard/frontend/src/pages/Users.tsx b/dashboard/frontend/src/pages/Users.tsx
index e0c8ad84..7501cf10 100644
--- a/dashboard/frontend/src/pages/Users.tsx
+++ b/dashboard/frontend/src/pages/Users.tsx
@@ -1,7 +1,7 @@
 import { useEffect, useState, useCallback } from 'react'
 import { useConfirm } from '../components/ConfirmDialog'
 import { api } from '../lib/api'
-import { Users as UsersIcon, Plus, Pencil, Trash2, X } from 'lucide-react'
+import { Users as UsersIcon, Plus, Pencil, Trash2, X, RotateCcw } from 'lucide-react'
 
 interface User {
   id: string
@@ -139,7 +139,7 @@ export default function UsersPage() {
   const handleDeactivate = async (u: User) => {
     const ok = await confirm({
       title: 'Desativar usuário',
-      description: `Desativar "${u.username}"?`,
+      description: `Desativar "${u.username}"? O usuário não poderá fazer login, mas seus dados serão preservados.`,
       confirmText: 'Desativar',
       variant: 'danger',
     })
@@ -147,8 +147,23 @@ export default function UsersPage() {
     try {
       await api.delete(`/users/${u.id}`)
       fetchUsers()
-    } catch {
-      /* ignore */
+    } catch (ex: unknown) {
+      setError(ex instanceof Error ? ex.message : 'Falha ao desativar')
+    }
+  }
+
+  const handleReactivate = async (u: User) => {
+    const ok = await confirm({
+      title: 'Reativar usuário',
+      description: `Reativar "${u.username}"? O usuário poderá fazer login novamente.`,
+      confirmText: 'Reativar',
+    })
+    if (!ok) return
+    try {
+      await api.post(`/users/${u.id}/reactivate`)
+      fetchUsers()
+    } catch (ex: unknown) {
+      setError(ex instanceof Error ? ex.message : 'Falha ao reativar')
     }
   }
 
@@ -172,6 +187,14 @@ export default function UsersPage() {
         </button>
       </div>
 
+      {/* Global error banner */}
+      {error && !modalOpen && (
+        <div className="mb-4 px-4 py-3 rounded-lg bg-red-500/10 border border-red-500/30 text-red-400 text-sm flex items-center justify-between">
+          <span>{error}</span>
+          <button onClick={() => setError('')} className="text-red-400 hover:text-red-300 ml-4"><X size={14} /></button>
+        </div>
+      )}
+
       {loading ? (
         <div className="space-y-2">
           {[...Array(3)].map((_, i) => <div key={i} className="skeleton h-16 rounded-xl" />)}
@@ -229,18 +252,26 @@ export default function UsersPage() {
                         <button
                           onClick={() => openEdit(u)}
                           className="p-1.5 rounded-lg text-[#667085] hover:text-[#e6edf3] hover:bg-white/5 transition-colors"
-                          title="Edit"
+                          title="Editar"
                         >
                           <Pencil size={14} />
                         </button>
-                        {u.is_active && (
+                        {u.is_active ? (
                           <button
                             onClick={() => handleDeactivate(u)}
                             className="p-1.5 rounded-lg text-[#667085] hover:text-red-400 hover:bg-red-500/10 transition-colors"
-                            title="Deactivate"
+                            title="Desativar"
                           >
                             <Trash2 size={14} />
                           </button>
+                        ) : (
+                          <button
+                            onClick={() => handleReactivate(u)}
+                            className="p-1.5 rounded-lg text-[#667085] hover:text-[#00FFA7] hover:bg-[#00FFA7]/10 transition-colors"
+                            title="Reativar"
+                          >
+                            <RotateCcw size={14} />
+                          </button>
                         )}
                       </div>
                     </td>

From db6b72100eedf7bded5da74a175d7495e1a18358 Mon Sep 17 00:00:00 2001
From: jbmendonca <jbmendonca@users.noreply.github.com>
Date: Thu, 30 Apr 2026 10:11:45 -0400
Subject: [PATCH 10/12] feat(core): implement global SPEC and fix provider
 routing failover

---
 Dockerfile.dashboard                          |   2 +-
 Dockerfile.swarm.dashboard                    |   2 +-
 SPEC.json                                     |  84 +++
 SPEC.md                                       |  57 ++
 config/providers.example.json                 |  14 +-
 dashboard/backend/app.py                      |   2 +
 dashboard/backend/blueprint_registry.py       |   1 +
 dashboard/backend/brain_repo/job_runner.py    | 180 ++++-
 dashboard/backend/knowledge/auto_migrator.py  |  12 +-
 dashboard/backend/knowledge/documents.py      |  22 +-
 dashboard/backend/knowledge/embedders/base.py |   2 +-
 .../knowledge/embedders/gemini_embedder.py    |  60 +-
 dashboard/backend/knowledge/ingestion.py      |   4 +-
 .../migrations/versions/001_initial_schema.py |  13 +-
 .../knowledge/parsers/marker_parser.py        |  84 ++-
 dashboard/backend/knowledge/search.py         |   5 +-
 dashboard/backend/knowledge/spaces.py         |  19 +-
 .../knowledge/tests/test_gemini_embedder.py   |  29 +-
 .../tests/test_migration_dim_from_env.py      |  10 +-
 .../backend/knowledge/tests/test_parsers.py   |  38 +-
 .../knowledge/tests/test_settings_routes.py   |   6 +-
 dashboard/backend/routes/agent_knowledge.py   | 426 +++++++++++
 dashboard/backend/routes/brain_repo.py        | 219 +++++-
 dashboard/backend/routes/knowledge.py         |  13 +-
 dashboard/backend/routes/providers.py         | 100 ++-
 dashboard/backend/routes/terminal_proxy.py    |   9 +-
 dashboard/frontend/index.html                 |   7 +-
 dashboard/frontend/src/App.tsx                |   2 +
 .../frontend/src/components/AgentChat.tsx     |  43 +-
 .../frontend/src/components/AgentTerminal.tsx | 118 ++-
 dashboard/frontend/src/components/Sidebar.tsx |   1 +
 .../frontend/src/i18n/locales/es/index.ts     |   1 +
 .../frontend/src/i18n/locales/pt-BR/index.ts  |   1 +
 dashboard/frontend/src/lib/navigation.ts      |   1 +
 dashboard/frontend/src/lib/terminal-url.ts    |  61 +-
 dashboard/frontend/src/pages/AgentDetail.tsx  |  11 +-
 .../frontend/src/pages/AgentKnowledge.tsx     | 670 ++++++++++++++++++
 .../frontend/src/pages/Knowledge/Settings.tsx |   2 +-
 .../onboarding/restore/RestoreExecute.tsx     |  43 +-
 .../onboarding/restore/RestoreSelectRepo.tsx  |  26 +-
 .../terminal-server/src/claude-bridge.js      | 112 ++-
 dashboard/terminal-server/src/http-routes.js  |  64 ++
 .../terminal-server/src/provider-config.js    | 134 +++-
 .../src/terminal-server-runtime.js            |  60 +-
 .../test/provider-config.test.js              |  60 +-
 pyproject.toml                                |   1 +
 uv.lock                                       | 151 +++-
 47 files changed, 2695 insertions(+), 287 deletions(-)
 create mode 100644 SPEC.json
 create mode 100644 SPEC.md
 create mode 100644 dashboard/backend/routes/agent_knowledge.py
 create mode 100644 dashboard/frontend/src/pages/AgentKnowledge.tsx

diff --git a/Dockerfile.dashboard b/Dockerfile.dashboard
index 523f16d0..c23f48b0 100644
--- a/Dockerfile.dashboard
+++ b/Dockerfile.dashboard
@@ -18,7 +18,7 @@ FROM python:3.12-slim AS runtime
 
 # System deps
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    curl \
+    curl git \
     && rm -rf /var/lib/apt/lists/*
 
 # Install uv
diff --git a/Dockerfile.swarm.dashboard b/Dockerfile.swarm.dashboard
index e19a2f23..8b725806 100644
--- a/Dockerfile.swarm.dashboard
+++ b/Dockerfile.swarm.dashboard
@@ -43,7 +43,7 @@ FROM python:3.12-slim AS runtime
 # System deps: curl for healthcheck + Node.js 22 for terminal-server binary.
 # We use NodeSource so the final image is clean (no build toolchain).
 RUN apt-get update && apt-get install -y --no-install-recommends \
-        curl ca-certificates gnupg openssl \
+        curl ca-certificates gnupg openssl git \
     && curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
     && apt-get install -y --no-install-recommends nodejs \
     && apt-get clean \
diff --git a/SPEC.json b/SPEC.json
new file mode 100644
index 00000000..e8ee71f1
--- /dev/null
+++ b/SPEC.json
@@ -0,0 +1,84 @@
+{
+  "projeto": "EvoNexus Multiagentes - Agro Roraima Contábil",
+  "descricao": "Sistema Multiagentes Autônomos (SMA) local-first baseado no framework OpenClaw, focado na gestão contábil, tributária e administrativa do Agronegócio.",
+  "sprints": [
+    {
+      "id": 1,
+      "nome": "Roteamento e Escala de IA",
+      "descricao": "Implementação do Smart Router com suporte a falha e painel de controle.",
+      "entregavel": "Backend, Frontend e Terminal Server integrados com troca de provedor dinâmica.",
+      "risco": "alto",
+      "pre_requisito": null,
+      "features": [
+        {
+          "categoria": "ia_agent",
+          "descricao": "O sistema suporta troca dinâmica de provedores em tempo real.",
+          "steps": [
+            "Usuário seleciona provedor (OpenRouter, Anthropic, Google, etc) no painel administrativo.",
+            "Backend (Flask) recebe a requisição HTTP POST.",
+            "Backend aciona webhook interno de notificação para o Terminal Server.",
+            "Terminal Server invoca `ClaudeBridge.invalidateAllSessions()` e recarrega `providers.json`.",
+            "Novas sub-chamadas passam a utilizar o novo provedor escolhido."
+          ],
+          "edge_cases": [
+            "E se o Provedor 1 e Provedor 2 caírem: Iniciar Roteamento em Cascata (Waterfall Fallback), saltando automaticamente para a próxima API da lista (Google, OpenAI) sem descartar a transação do cliente.",
+            "E se atingir Rate Limit da API: Backend implementa Retry com Backoff Exponencial automático.",
+            "E se houver timeout na API: Interromper a chamada após 60 segundos (Graceful Shutdown) e avançar para o provedor de fallback.",
+            "E se as permissões falharem: Apenas usuários com a role 'Admin' têm permissão de realizar esta troca (Status Code 403 Forbidden para não-admins)."
+          ]
+        }
+      ]
+    },
+    {
+      "id": 2,
+      "nome": "Auth Hardening e Segurança",
+      "descricao": "Blindagem da API contra ataques de força bruta e controle de acesso.",
+      "entregavel": "Autenticação robusta operando no banco de dados com lockouts gerenciais.",
+      "risco": "medio",
+      "pre_requisito": null,
+      "features": [
+        {
+          "categoria": "auth",
+          "descricao": "Limitação de tentativas de login falhas por usuário ou IP.",
+          "steps": [
+            "Sistema recebe requisição POST /api/login com validação restrita de Input.",
+            "Em caso de senha errada, registro é inserido na tabela `login_throttles` do banco de dados (SQLite/PostgreSQL).",
+            "Bloquear endpoint por 5 minutos após 5 erros seguidos (Status Code 429 Too Many Requests).",
+            "Bloquear endpoint por 30 minutos após 10 erros seguidos (Status Code 429 Too Many Requests)."
+          ],
+          "edge_cases": [
+            "E se houver concorrência massiva no login: O ORM gerencia o pool de conexões para evitar DB Lock.",
+            "E se usuário usar token CSRF expirado: Retornar Status Code 403 (Invalid Token).",
+            "E se a payload for gigantesca num ataque: O servidor barra payloads > 5MB nas rotas públicas de login (Status Code 413 Payload Too Large)."
+          ]
+        }
+      ]
+    },
+    {
+      "id": 3,
+      "nome": "SPED EFD-Contribuições",
+      "descricao": "Automação massiva via agente fiscal com base na IN RFB nº 2.305/2024.",
+      "entregavel": "Skill de automação `sped_cli.py` integrada aos agentes de IA com leitura em lote.",
+      "risco": "alto",
+      "pre_requisito": 1,
+      "features": [
+        {
+          "categoria": "api_endpoint",
+          "descricao": "Extração inteligente e massiva de arquivos com compilação de layout padrão SPED.",
+          "steps": [
+            "Agente recebe arquivo ou pasta contendo faturas e recibos.",
+            "Invocação da skill local `sped_cli.py batch-process`.",
+            "Validação automática dos blocos estruturais (ex: 0000, 0001, 0100) via script determinístico.",
+            "Geração de arquivo formatado com delimitador pipe (|)."
+          ],
+          "edge_cases": [
+            "E se os arquivos de faturamento somarem 80MB: O limite configurado para este processamento massivo é de 100MB+, garantindo o parse do lote mensal completo.",
+            "E se faltar metadados num bloco: Aplicar regras de auto-fill ou usar separadores vazios (||) conforme a sintaxe legislativa.",
+            "E se o modelo de IA alucinar nos blocos matemáticos: A execução binária intercepta e o script de conferência (`validate`) emite Status 500 Interno pedindo correção humana.",
+            "E se o servidor ficar sem memória (OOM) devido aos 100MB: Implementar stream de parsing (chunks) no script Python para não sobrecarregar a RAM da VPS."
+          ]
+        }
+      ]
+    }
+  ]
+}
diff --git a/SPEC.md b/SPEC.md
new file mode 100644
index 00000000..7d63c7c2
--- /dev/null
+++ b/SPEC.md
@@ -0,0 +1,57 @@
+# SPEC: EvoNexus & Agro Roraima Contábil
+
+## Visão Geral
+Sistema Multiagentes Autônomos (SMA) local-first baseado no framework OpenClaw, voltado para automação de processos contábeis, tributários e burocráticos do Agronegócio (Agro Roraima Contábil). O painel administrativo (Dashboard) integra gestão de usuários, observabilidade de integrações (WhatsApp, Telegram) e controle total do pipeline de agentes.
+
+## Sprint Atual: Configuração e Escala
+**Entregável:** Sistema estável com normalização de variáveis de ambiente, roteamento de provedores (OpenRouter) e painéis de observabilidade operacionais.
+**Risco:** Alto (Lida com dados sensíveis de folha de pagamento e impostos federais).
+
+---
+
+### Feature 1: Roteamento de Provedores de IA (Smart Router)
+**Categoria:** ia_agent
+**Descrição:** O sistema deve suportar falha e troca dinâmica de provedores (ex: OpenRouter para Anthropic), derrubando sessões antigas para evitar loops e travamentos.
+
+**Steps:**
+1. Painel frontend permite alteração do provedor principal.
+2. Backend (Flask) notifica o Terminal Server via rota HTTP.
+3. Terminal Server invalida sessões PTY ativas (`ClaudeBridge.invalidateAllSessions()`).
+4. Agentes reconectam usando as novas chaves.
+
+**Edge cases (Tratamento Automático):**
+- E se o novo provedor estiver fora do ar: Fallback configurado no `provider-config.js`.
+- Limite de tokens (Rate Limit do provedor): Backoff exponencial e retry.
+- Modelo indisponível: Reverter para o modelo secundário definido na configuração.
+
+---
+
+### Feature 2: Proteção Contra Força Bruta (Auth Hardening)
+**Categoria:** auth
+**Descrição:** Limitar tentativas de login falhas por usuário/IP para proteger contra ataques de força bruta.
+
+**Steps:**
+1. Usuário tenta login com credenciais inválidas.
+2. Registro de `login_throttles` é incrementado no banco de dados.
+3. Se tentativas falhas == 5, aplicar bloqueio de 5 minutos.
+4. Se tentativas falhas >= 10, aplicar bloqueio de 30 minutos.
+
+**Edge cases (Tratamento Automático):**
+- Sessão expirada no meio da navegação: Redirecionar para login sem crashar o app.
+- Proteção CSRF ausente: Rejeitar a mutação com status 403.
+
+---
+
+### Feature 3: Automação EFD-Contribuições (Integração SPED)
+**Categoria:** api_endpoint
+**Descrição:** Agente Fiscal deve extrair dados estruturados (notas fiscais) e gerar arquivo no formato SPED delimitado por *pipe* (|).
+
+**Steps:**
+1. Agente aciona ferramenta (skill) `sped_cli.py`.
+2. Leitura massiva de diretório de faturas via OCR/JSON.
+3. Validação dos blocos (0000, 0001, 0100).
+4. Emissão de relatório de aprovação.
+
+**Edge cases:**
+- Falha na leitura do OCR (fatura borrada): Alertar o Humano (Human-in-the-loop) para input manual.
+- E se a alíquota for alterada por nova lei: Bloquear emissão até que a tabela seja atualizada.
diff --git a/config/providers.example.json b/config/providers.example.json
index 17a4d61f..25a747ae 100644
--- a/config/providers.example.json
+++ b/config/providers.example.json
@@ -1,5 +1,17 @@
 {
-  "active_provider": "anthropic",
+  "active_provider": "openrouter",
+  "routing": {
+    "enabled": true,
+    "failover_order": [
+      "openrouter",
+      "anthropic",
+      "openai",
+      "codex_auth",
+      "gemini",
+      "bedrock",
+      "vertex"
+    ]
+  },
   "providers": {
     "anthropic": {
       "name": "Anthropic (Claude nativo)",
diff --git a/dashboard/backend/app.py b/dashboard/backend/app.py
index 1159dfc3..ed3aa6aa 100644
--- a/dashboard/backend/app.py
+++ b/dashboard/backend/app.py
@@ -915,6 +915,7 @@ def attach_security_headers(response):
 from routes.knowledge_public import bp as knowledge_public_bp
 from routes.knowledge_proxy import bp as knowledge_proxy_bp
 from routes.knowledge_v1 import bp as knowledge_v1_bp
+from routes.agent_knowledge import bp as agent_knowledge_bp
 from routes.databases import bp as databases_bp
 from routes.plugins import bp as plugins_bp
 from routes.mcp_servers import bp as mcp_servers_bp
@@ -988,6 +989,7 @@ def attach_security_headers(response):
 app.register_blueprint(knowledge_public_bp)
 app.register_blueprint(knowledge_proxy_bp)
 app.register_blueprint(knowledge_v1_bp)
+app.register_blueprint(agent_knowledge_bp)
 app.register_blueprint(databases_bp)
 app.register_blueprint(plugins_bp)
 app.register_blueprint(mcp_servers_bp)
diff --git a/dashboard/backend/blueprint_registry.py b/dashboard/backend/blueprint_registry.py
index 2ed22c83..a6cf21d2 100644
--- a/dashboard/backend/blueprint_registry.py
+++ b/dashboard/backend/blueprint_registry.py
@@ -35,6 +35,7 @@
     "routes.knowledge_public",
     "routes.knowledge_proxy",
     "routes.knowledge_v1",
+    "routes.agent_knowledge",
     "routes.databases",
 ]
 
diff --git a/dashboard/backend/brain_repo/job_runner.py b/dashboard/backend/brain_repo/job_runner.py
index 3099b558..3fb81e50 100644
--- a/dashboard/backend/brain_repo/job_runner.py
+++ b/dashboard/backend/brain_repo/job_runner.py
@@ -37,6 +37,7 @@
 
 import logging
 import shutil
+import subprocess
 import threading
 from datetime import datetime, timezone
 from pathlib import Path
@@ -338,6 +339,87 @@ def _decrypt_snapshot_token(encrypted: bytes) -> str:
 # Top-level pipelines
 # ────────────────────────────────────────────────────────────────────────
 
+def _authenticated_url(repo_url: str, token: str) -> str:
+    """Return repo_url with a one-shot token for git network commands."""
+    if token and "://" in repo_url:
+        scheme, rest = repo_url.split("://", 1)
+        if "@" in rest:
+            rest = rest.split("@", 1)[1]
+        return f"{scheme}://{token}@{rest}"
+    return repo_url
+
+
+def _run_git_checked(
+    args: list[str],
+    *,
+    cwd: Path | None = None,
+    timeout: int = 60,
+    token: str = "",
+) -> subprocess.CompletedProcess:
+    """Run git and raise a compact, token-masked error on failure."""
+    result = subprocess.run(
+        ["git", *args],
+        cwd=cwd,
+        check=False,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+    )
+    if result.returncode != 0:
+        stderr = (result.stderr or result.stdout or "")[:500]
+        command = " ".join(args)
+        if token:
+            stderr = stderr.replace(token, "***")
+            command = command.replace(token, "***")
+        raise RuntimeError(f"git {command} failed: {stderr}")
+    return result
+
+
+def _set_clean_origin(repo_dir: Path, repo_url: str) -> None:
+    """Ensure origin is configured without credentials persisted in .git/config."""
+    remotes = _run_git_checked(["remote"], cwd=repo_dir).stdout.splitlines()
+    if "origin" in remotes:
+        _run_git_checked(["remote", "set-url", "origin", repo_url], cwd=repo_dir)
+    else:
+        _run_git_checked(["remote", "add", "origin", repo_url], cwd=repo_dir)
+
+
+def _ensure_checkout_branch(repo_dir: Path) -> None:
+    """Make an empty clone usable without disturbing a normal cloned branch."""
+    head = subprocess.run(
+        ["git", "rev-parse", "--verify", "HEAD"],
+        cwd=repo_dir,
+        check=False,
+        capture_output=True,
+        text=True,
+        timeout=10,
+    )
+    if head.returncode == 0:
+        branch = _run_git_checked(["branch", "--show-current"], cwd=repo_dir).stdout.strip()
+        if branch:
+            return
+
+    # Empty repositories and detached HEAD checkouts need a branch before the
+    # skeleton commit can be created. GitHub-created repos default to main.
+    _run_git_checked(["checkout", "-B", "main"], cwd=repo_dir)
+
+
+def _clone_brain_repo(repo_url: str, token: str, local_path: Path) -> None:
+    """Create a fresh local working tree for an existing or empty remote repo."""
+    if local_path.exists():
+        shutil.rmtree(local_path, ignore_errors=True)
+    local_path.parent.mkdir(parents=True, exist_ok=True)
+
+    auth_url = _authenticated_url(repo_url, token)
+    _run_git_checked(
+        ["clone", auth_url, str(local_path)],
+        timeout=180,
+        token=token,
+    )
+    _set_clean_origin(local_path, repo_url)
+    _ensure_checkout_branch(local_path)
+
+
 def run_sync_pipeline(
     flask_app,
     user_id: int,
@@ -428,58 +510,42 @@ def run_bootstrap_pipeline(
     repo_name: str,
     owner_username: str,
     github_username: str,
+    sync_after: bool = False,
+    workspace: Path | None = None,
+    tag_name: str | None = None,
+    commit_message: str | None = None,
 ) -> None:
-    """Bootstrap a freshly-created empty GitHub repo with the skeleton.
+    """Clone/bootstrap a GitHub brain repo and persist the local working tree.
 
-    Runs the same logic as routes.brain_repo._initialize_remote_brain_repo
-    but inside the job_runner lock so it serializes with sync operations,
-    and persists the final local_path into BrainRepoConfig so the UI stops
-    showing "initializing…".
+    Existing valid brain repos are cloned as-is. Empty or incomplete repos get
+    the standard skeleton before local_path is persisted to BrainRepoConfig.
     """
-    import subprocess
     from models import BrainRepoConfig, db  # type: ignore[import]
 
     with _job_lock:
         error: str | None = None
         local_path_str: str | None = None
         try:
-            workspace = Path(__file__).resolve().parent.parent.parent.parent
-            base_dir = workspace / "dashboard" / "data" / "brain-repos"
+            repo_root = Path(__file__).resolve().parent.parent.parent.parent
+            workspace_root = workspace or repo_root
+            base_dir = repo_root / "dashboard" / "data" / "brain-repos"
             base_dir.mkdir(parents=True, exist_ok=True)
             local_path = base_dir / repo_name
 
-            if local_path.exists():
-                shutil.rmtree(local_path, ignore_errors=True)
-
             from brain_repo import git_ops, manifest  # type: ignore[import]
 
-            local_path.mkdir(parents=True, exist_ok=True)
-
-            subprocess.run(
-                ["git", "init", "-b", "main"],
-                cwd=local_path, check=True, capture_output=True, timeout=30,
-            )
+            _clone_brain_repo(repo_url, token, local_path)
             _check_cancel(flask_app, user_id)
 
-            # Token-embedded remote for the bootstrap push. A later follow-up
-            # should move this to `git credential helper` so the PAT never
-            # hits .git/config, but that's a separate change.
-            if "://" in repo_url:
-                scheme, rest = repo_url.split("://", 1)
-                auth_url = f"{scheme}://{token}@{rest}"
-            else:
-                auth_url = repo_url
-            subprocess.run(
-                ["git", "remote", "add", "origin", auth_url],
-                cwd=local_path, check=True, capture_output=True, timeout=30,
-            )
-            _check_cancel(flask_app, user_id)
-
-            manifest.initialize_brain_repo(local_path, {
-                "workspace_name": owner_username or "",
-                "owner_username": owner_username or "",
-                "github_username": github_username or "",
-            })
+            manifest_data = manifest.read_manifest(local_path)
+            schema_ok, _migration_needed = manifest.validate_schema(manifest_data)
+            marker_exists = (local_path / ".evo-brain").exists()
+            if not marker_exists or not schema_ok:
+                manifest.initialize_brain_repo(local_path, {
+                    "workspace_name": owner_username or "",
+                    "owner_username": owner_username or "",
+                    "github_username": github_username or "",
+                })
 
             author_name = github_username or owner_username or "EvoNexus"
             author_email = (
@@ -496,10 +562,38 @@ def run_bootstrap_pipeline(
             )
             _check_cancel(flask_app, user_id)
 
-            committed = git_ops.commit_all(local_path, "feat(brain-repo): initial structure")
-            if committed:
+            if sync_after:
+                copied, dropped = _mirror_workspace(
+                    flask_app,
+                    user_id,
+                    workspace_root,
+                    local_path,
+                )
+                log.info(
+                    "bootstrap+sync: mirrored %d files, removed %d with secrets",
+                    copied,
+                    dropped,
+                )
+
+            msg = commit_message or (
+                f"manual sync {datetime.now(timezone.utc).isoformat()}"
+                if sync_after
+                else "feat(brain-repo): initial structure"
+            )
+            committed = git_ops.commit_all(local_path, msg)
+
+            if tag_name:
                 _check_cancel(flask_app, user_id)
-                pushed, push_err = git_ops.push(local_path, token, with_tags=False)
+                git_ops.create_tag(
+                    local_path,
+                    tag_name,
+                    f"Bootstrap sync: {tag_name} ({datetime.now(timezone.utc).isoformat()})",
+                    force=True,
+                )
+
+            if committed or tag_name:
+                _check_cancel(flask_app, user_id)
+                pushed, push_err = git_ops.push(local_path, token, with_tags=bool(tag_name))
                 if not pushed:
                     log.warning("bootstrap push failed for %s: %s", repo_name, push_err)
                     error = f"bootstrap push failed: {push_err}"
@@ -564,6 +658,10 @@ def enqueue_bootstrap(
     repo_name: str,
     owner_username: str,
     github_username: str,
+    sync_after: bool = False,
+    workspace: Path | None = None,
+    tag_name: str | None = None,
+    commit_message: str | None = None,
 ) -> bool:
     """Spawn daemon thread running run_bootstrap_pipeline. Returns False if busy."""
     if not _acquire_db_lock(flask_app, user_id, JOB_KIND_BOOTSTRAP):
@@ -578,6 +676,10 @@ def enqueue_bootstrap(
             "repo_name": repo_name,
             "owner_username": owner_username,
             "github_username": github_username,
+            "sync_after": sync_after,
+            "workspace": workspace,
+            "tag_name": tag_name,
+            "commit_message": commit_message,
         },
         name=f"brain-repo-bootstrap-{user_id}",
         daemon=True,
diff --git a/dashboard/backend/knowledge/auto_migrator.py b/dashboard/backend/knowledge/auto_migrator.py
index 29ba9298..03f8c04a 100644
--- a/dashboard/backend/knowledge/auto_migrator.py
+++ b/dashboard/backend/knowledge/auto_migrator.py
@@ -331,7 +331,7 @@ def configure_connection(
     "text-embedding-3-large": 3072,
     "text-embedding-ada-002": 1536,
 }
-_PROVIDER_DEFAULT_DIMS = {"local": 768, "openai": 1536}
+_PROVIDER_DEFAULT_DIMS = {"local": 768, "openai": 1536, "gemini": 768}
 
 
 def _clean(name: str) -> str:
@@ -345,6 +345,16 @@ def _get_evonexus_dim(conn) -> int:
     if provider == "openai":
         model = _clean("KNOWLEDGE_OPENAI_MODEL") or "text-embedding-3-small"
         return _OPENAI_MODEL_DIMS.get(model, 1536)
+    if provider == "gemini":
+        raw_dim = _clean("KNOWLEDGE_GEMINI_DIM")
+        if raw_dim:
+            try:
+                dim = int(raw_dim)
+                if dim in {768, 1536, 3072}:
+                    return dim
+            except ValueError:
+                pass
+        return 768
     return _PROVIDER_DEFAULT_DIMS.get(provider, 768)
 
 
diff --git a/dashboard/backend/knowledge/documents.py b/dashboard/backend/knowledge/documents.py
index 2a69f79f..8cd20c84 100644
--- a/dashboard/backend/knowledge/documents.py
+++ b/dashboard/backend/knowledge/documents.py
@@ -17,7 +17,7 @@
 import subprocess
 import sys
 import uuid
-from datetime import datetime, timezone
+from datetime import date, datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
@@ -34,6 +34,21 @@ def _sql(stmt: str):
     return text(stmt)
 
 
+def _json_safe(value: Any) -> Any:
+    """Return a JSON-serializable copy of values commonly returned by psycopg."""
+    if isinstance(value, uuid.UUID):
+        return str(value)
+    if isinstance(value, (datetime, date)):
+        return value.isoformat()
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, dict):
+        return {str(k): _json_safe(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple, set)):
+        return [_json_safe(v) for v in value]
+    return value
+
+
 def _row_to_dict(row) -> Dict[str, Any]:
     d = dict(row._mapping)
     for col in ("tags", "metadata"):
@@ -42,7 +57,7 @@ def _row_to_dict(row) -> Dict[str, Any]:
                 d[col] = json.loads(d[col])
             except (ValueError, TypeError):
                 pass
-    return d
+    return _json_safe(d)
 
 
 def _get_engine(connection_id: str):
@@ -81,6 +96,9 @@ def upload_document(
     file_path = Path(file_path)
     if metadata is None:
         metadata = {}
+    metadata = _json_safe(metadata)
+    space_id = str(space_id)
+    unit_id = str(unit_id) if unit_id is not None else None
 
     document_id = str(uuid.uuid4())
     doc_title = metadata.get("title") or file_path.stem
diff --git a/dashboard/backend/knowledge/embedders/base.py b/dashboard/backend/knowledge/embedders/base.py
index ae0eb358..6850f402 100644
--- a/dashboard/backend/knowledge/embedders/base.py
+++ b/dashboard/backend/knowledge/embedders/base.py
@@ -3,7 +3,7 @@
 Registry logic:
     get_embedder("local")   → LocalEmbedder (sentence-transformers, 768 dim)
     get_embedder("openai")  → OpenAIEmbedder (text-embedding-3-small, 1536 dim)
-    get_embedder("gemini")  → GeminiEmbedder (gemini-embedding-001, MRL 768/1536/3072)
+    get_embedder("gemini")  → GeminiEmbedder (gemini-embedding-2, MRL 768/1536/3072)
     get_embedder()          → reads KNOWLEDGE_EMBEDDER_PROVIDER env var (default "local")
 """
 
diff --git a/dashboard/backend/knowledge/embedders/gemini_embedder.py b/dashboard/backend/knowledge/embedders/gemini_embedder.py
index 17b4fec0..da964f58 100644
--- a/dashboard/backend/knowledge/embedders/gemini_embedder.py
+++ b/dashboard/backend/knowledge/embedders/gemini_embedder.py
@@ -41,7 +41,7 @@
     genai_types = None  # type: ignore[assignment,misc]
 
 
-_DEFAULT_MODEL = "gemini-embedding-001"
+_DEFAULT_MODEL = "gemini-embedding-2"
 _DEFAULT_DIM = 768
 
 # Allowed dimensions per Gemini MRL guidance.
@@ -53,13 +53,14 @@
 # output_dimensionality is omitted). Kept separate from _DEFAULT_DIM so the
 # evo-nexus default stays at 768 across both models for storage alignment.
 _MODEL_NATIVE_DIMS = {
-    "gemini-embedding-001": 768,
-    "gemini-embedding-2-preview": 768,
+    "gemini-embedding-2": 3072,
+    "gemini-embedding-001": 3072,
 }
 
 # Models that accept the ``task_type`` parameter. The 2-preview model does
 # not — task optimisation is expressed inline in the prompt instead.
 _MODELS_WITH_TASK_TYPE = {"gemini-embedding-001"}
+_MODELS_WITH_AGGREGATED_INPUTS = {"gemini-embedding-2"}
 
 # Conservative client-side batch size. gemini-embedding-001 has a 2048-token
 # input limit; at ~50 tokens/chunk that's ~40 chunks/call. We stay at 20 for
@@ -106,9 +107,9 @@ def __init__(self) -> None:
             try:
                 dim = int(raw_dim)
             except ValueError:
-                dim = _MODEL_NATIVE_DIMS.get(self._model, _DEFAULT_DIM)
+                dim = _DEFAULT_DIM
         else:
-            dim = _MODEL_NATIVE_DIMS.get(self._model, _DEFAULT_DIM)
+            dim = _DEFAULT_DIM
 
         # Silently coerce invalid dims to the default — we must not raise
         # in __init__ because the settings UI instantiates embedders just to
@@ -164,6 +165,9 @@ def embed(
         client = genai.Client(api_key=api_key)
         config = self._build_config(task_type)
 
+        if self._model in _MODELS_WITH_AGGREGATED_INPUTS:
+            return self._embed_aggregating_model(client, texts, task_type, config)
+
         all_vectors: List[List[float]] = []
         for i in range(0, len(texts), _BATCH_SIZE):
             batch = texts[i : i + _BATCH_SIZE]
@@ -184,6 +188,31 @@ def embed(
     # Internals
     # ------------------------------------------------------------------
 
+    def _embed_aggregating_model(
+        self,
+        client: Any,
+        texts: List[str],
+        task_type: Optional[str],
+        config: Optional[Any],
+    ) -> List[List[float]]:
+        """Embed one text per request for Gemini Embedding 2.
+
+        Gemini Embedding 2 aggregates multiple inputs in one request into a
+        single vector. RAG indexing needs one vector per chunk, so this method
+        intentionally performs a separate embed_content call per text.
+        """
+        vectors: List[List[float]] = []
+        for text in texts:
+            response = client.models.embed_content(
+                model=self._model,
+                contents=_format_embedding_2_text(text, task_type),
+                config=config,
+            )
+            if not response.embeddings:
+                raise RuntimeError("Gemini returned no embeddings.")
+            vectors.append(list(response.embeddings[0].values))
+        return vectors
+
     def _build_config(self, task_type: Optional[str]) -> Optional[Any]:
         """Assemble ``EmbedContentConfig`` only when we need to override defaults."""
         kwargs: dict = {}
@@ -202,6 +231,27 @@ def _build_config(self, task_type: Optional[str]) -> Optional[Any]:
         return genai_types.EmbedContentConfig(**kwargs)
 
 
+def _format_embedding_2_text(text: str, task_type: Optional[str]) -> str:
+    """Apply Google's text-only task prefixes for Gemini Embedding 2."""
+    if task_type == "RETRIEVAL_QUERY":
+        return f"task: search result | query: {text}"
+    if task_type == "RETRIEVAL_DOCUMENT":
+        return f"title: none | text: {text}"
+    if task_type == "QUESTION_ANSWERING":
+        return f"task: question answering | query: {text}"
+    if task_type == "FACT_VERIFICATION":
+        return f"task: fact checking | query: {text}"
+    if task_type == "CODE_RETRIEVAL_QUERY":
+        return f"task: code retrieval | query: {text}"
+    if task_type == "SEMANTIC_SIMILARITY":
+        return f"task: sentence similarity | query: {text}"
+    if task_type == "CLASSIFICATION":
+        return f"task: classification | query: {text}"
+    if task_type == "CLUSTERING":
+        return f"task: clustering | query: {text}"
+    return text
+
+
 def _l2_normalize(vec: List[float]) -> List[float]:
     """Unit-length-normalize *vec* in L2 norm.
 
diff --git a/dashboard/backend/knowledge/ingestion.py b/dashboard/backend/knowledge/ingestion.py
index 000e6e16..fe3915c4 100644
--- a/dashboard/backend/knowledge/ingestion.py
+++ b/dashboard/backend/knowledge/ingestion.py
@@ -144,8 +144,8 @@ def _emit(phase: str) -> None:
     try:
         embedder = get_embedder()
         texts = [c["content"] for c in chunks]
-        # task_type is honoured by providers that support it (e.g. Gemini's
-        # gemini-embedding-001). Others (local MPNet, OpenAI) ignore it.
+        # task_type is honoured by providers that support it. Gemini
+        # Embedding 2 converts it into Google's text prefix format.
         vectors = embedder.embed(texts, task_type="RETRIEVAL_DOCUMENT")
     except Exception as exc:
         _mark_error(engine, doc_id, f"Embed error: {exc}")
diff --git a/dashboard/backend/knowledge/migrations/versions/001_initial_schema.py b/dashboard/backend/knowledge/migrations/versions/001_initial_schema.py
index 823a4940..6da8a024 100644
--- a/dashboard/backend/knowledge/migrations/versions/001_initial_schema.py
+++ b/dashboard/backend/knowledge/migrations/versions/001_initial_schema.py
@@ -28,7 +28,7 @@
 _PROVIDER_DEFAULTS = {
     "local": ("sentence-transformers/paraphrase-multilingual-mpnet-base-v2", 768),
     "openai": ("text-embedding-3-small", 1536),
-    "gemini": ("gemini-embedding-001", 768),
+    "gemini": ("gemini-embedding-2", 768),
 }
 
 _OPENAI_MODEL_DIMS = {
@@ -41,8 +41,8 @@
 # 768, 1536, or 3072-dim vectors. Dim is controlled by KNOWLEDGE_GEMINI_DIM
 # (default 768 to align storage/index cost with the local provider).
 _GEMINI_MODEL_NATIVE_DIMS = {
-    "gemini-embedding-001": 768,
-    "gemini-embedding-2-preview": 768,
+    "gemini-embedding-2": 3072,
+    "gemini-embedding-001": 3072,
 }
 _GEMINI_ALLOWED_DIMS = {768, 1536, 3072}
 
@@ -67,16 +67,15 @@ def _resolve_embedder_config() -> tuple[str, str, int]:
     elif provider == "gemini":
         model = _clean_env("KNOWLEDGE_GEMINI_MODEL") or default_model
         raw_dim = _clean_env("KNOWLEDGE_GEMINI_DIM")
-        native = _GEMINI_MODEL_NATIVE_DIMS.get(model, default_dim)
         if raw_dim:
             try:
                 dim = int(raw_dim)
                 if dim not in _GEMINI_ALLOWED_DIMS:
-                    dim = native
+                    dim = default_dim
             except ValueError:
-                dim = native
+                dim = default_dim
         else:
-            dim = native
+            dim = default_dim
     else:
         model = default_model
         dim = default_dim
diff --git a/dashboard/backend/knowledge/parsers/marker_parser.py b/dashboard/backend/knowledge/parsers/marker_parser.py
index b8c91e5f..267fd3ec 100644
--- a/dashboard/backend/knowledge/parsers/marker_parser.py
+++ b/dashboard/backend/knowledge/parsers/marker_parser.py
@@ -77,6 +77,16 @@ def parse(self, file_path: Path) -> ParseResult:
         """
         file_path = Path(file_path)
 
+        if not file_path.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        if file_path.suffix.lower() == ".pdf":
+            try:
+                return _parse_pdf_text_fallback(file_path)
+            except Exception:
+                # No searchable text was available; fall through to Marker OCR.
+                pass
+
         try:
             from marker.converters.pdf import PdfConverter  # noqa: F401
         except ImportError as exc:
@@ -85,9 +95,6 @@ def parse(self, file_path: Path) -> ParseResult:
                 "Run: pip install marker-pdf  (or: uv add marker-pdf)"
             ) from exc
 
-        if not file_path.exists():
-            raise FileNotFoundError(f"File not found: {file_path}")
-
         # Run conversion in a thread so we can enforce a timeout
         result_holder: Dict[str, Any] = {}
         error_holder: Dict[str, Exception] = {}
@@ -105,12 +112,13 @@ def _run() -> None:
         t.join(timeout=_MARKER_TIMEOUT_SECONDS)
 
         if t.is_alive():
-            raise TimeoutError(
+            timeout_error = TimeoutError(
                 f"Marker timed out after {_MARKER_TIMEOUT_SECONDS}s parsing {file_path.name}. "
                 f"Increase MARKER_TIMEOUT_SECONDS to allow more time."
             )
+            return _maybe_parse_pdf_fallback(file_path, timeout_error)
         if "exc" in error_holder:
-            raise error_holder["exc"]
+            return _maybe_parse_pdf_fallback(file_path, error_holder["exc"])
 
         rendered = result_holder["rendered"]
         return _to_parse_result(rendered, file_path)
@@ -148,6 +156,72 @@ def _to_parse_result(rendered: Any, file_path: Path) -> ParseResult:
     return ParseResult(markdown=md, pages=pages, metadata=metadata)
 
 
+def _maybe_parse_pdf_fallback(file_path: Path, marker_error: Exception) -> ParseResult:
+    """Use a lightweight PDF text extractor when Marker fails on a PDF."""
+    if file_path.suffix.lower() != ".pdf":
+        raise marker_error
+
+    try:
+        return _parse_pdf_text_fallback(file_path, marker_error)
+    except Exception as fallback_error:
+        raise RuntimeError(
+            f"{marker_error}. PDF text fallback also failed: {fallback_error}"
+        ) from marker_error
+
+
+def _parse_pdf_text_fallback(file_path: Path, marker_error: Optional[Exception] = None) -> ParseResult:
+    """Extract text from searchable PDFs without invoking Marker/Surya models."""
+    try:
+        import pypdfium2 as pdfium
+    except ImportError as exc:
+        raise RuntimeError("pypdfium2 is not installed") from exc
+
+    pdf = pdfium.PdfDocument(str(file_path))
+    pages: List[PageInfo] = []
+    markdown_parts: List[str] = []
+
+    try:
+        page_count = len(pdf)
+        for page_index in range(page_count):
+            page = pdf[page_index]
+            textpage = None
+            try:
+                textpage = page.get_textpage()
+                text = (textpage.get_text_range() or "").strip()
+            finally:
+                if textpage is not None and hasattr(textpage, "close"):
+                    textpage.close()
+                if hasattr(page, "close"):
+                    page.close()
+
+            if not text:
+                continue
+
+            page_number = page_index + 1
+            page_markdown = f"## Page {page_number}\n\n{text}"
+            pages.append({"page_number": page_number, "markdown": page_markdown})
+            markdown_parts.append(page_markdown)
+    finally:
+        if hasattr(pdf, "close"):
+            pdf.close()
+
+    markdown = "\n\n".join(markdown_parts).strip()
+    if not markdown:
+        raise ValueError("No extractable PDF text was found")
+
+    metadata: Dict[str, Any] = {
+        "title": file_path.stem,
+        "author": None,
+        "page_count": len(pages),
+        "source_mime": "application/pdf",
+        "parser_fallback": "pypdfium2",
+    }
+    if marker_error is not None:
+        metadata["marker_error"] = str(marker_error)[:500]
+
+    return ParseResult(markdown=markdown, pages=pages, metadata=metadata)
+
+
 def _guess_mime(path: Path) -> Optional[str]:
     _map = {
         ".pdf": "application/pdf",
diff --git a/dashboard/backend/knowledge/search.py b/dashboard/backend/knowledge/search.py
index 9a72450e..753348ca 100644
--- a/dashboard/backend/knowledge/search.py
+++ b/dashboard/backend/knowledge/search.py
@@ -70,9 +70,8 @@ def _get_query_vector(connection_id: str, query: str) -> List[float]:
 
     embedder = get_embedder()
     # task_type=RETRIEVAL_QUERY pairs with RETRIEVAL_DOCUMENT used during
-    # ingestion for providers that support it (e.g. Gemini's
-    # gemini-embedding-001). Providers that don't support task hints (local
-    # MPNet, OpenAI) ignore this parameter silently.
+    # ingestion. Gemini Embedding 2 converts it into Google's text prefix
+    # format; providers that do not support hints ignore it.
     vectors = embedder.embed([query], task_type="RETRIEVAL_QUERY")
     vector = vectors[0]
 
diff --git a/dashboard/backend/knowledge/spaces.py b/dashboard/backend/knowledge/spaces.py
index 19a11ad5..e9ff8898 100644
--- a/dashboard/backend/knowledge/spaces.py
+++ b/dashboard/backend/knowledge/spaces.py
@@ -12,6 +12,8 @@
 
 import json
 import uuid
+from datetime import date, datetime
+from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 from sqlalchemy import text
@@ -27,6 +29,21 @@ def _sql(stmt: str):
     return text(stmt)
 
 
+def _json_safe(value: Any) -> Any:
+    """Return a JSON-serializable copy of values commonly returned by psycopg."""
+    if isinstance(value, uuid.UUID):
+        return str(value)
+    if isinstance(value, (datetime, date)):
+        return value.isoformat()
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, dict):
+        return {str(k): _json_safe(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple, set)):
+        return [_json_safe(v) for v in value]
+    return value
+
+
 def _row_to_dict(row) -> Dict[str, Any]:
     """Convert a SQLAlchemy Row to a plain dict."""
     d = dict(row._mapping)
@@ -37,7 +54,7 @@ def _row_to_dict(row) -> Dict[str, Any]:
                 d[col] = json.loads(d[col])
             except (ValueError, TypeError):
                 pass
-    return d
+    return _json_safe(d)
 
 
 def _get_engine(connection_id: str):
diff --git a/dashboard/backend/knowledge/tests/test_gemini_embedder.py b/dashboard/backend/knowledge/tests/test_gemini_embedder.py
index 1aac5554..f49a3070 100644
--- a/dashboard/backend/knowledge/tests/test_gemini_embedder.py
+++ b/dashboard/backend/knowledge/tests/test_gemini_embedder.py
@@ -4,7 +4,7 @@
   * Env-driven configuration (model, dim, API key resolution)
   * Input validation (empty list, missing key, missing SDK)
   * L2 normalization for dim < 3072
-  * Model-specific task_type handling (001 honours it, 2-preview skips)
+  * Model-specific task_type handling (001 honours it, Embedding 2 prefixes text)
   * Client-side batching
 """
 
@@ -58,7 +58,7 @@ def test_default_dim_is_768(self, monkeypatch):
         mod = _fresh_module()
         e = mod.GeminiEmbedder()
         assert e.dim == 768
-        assert e._model == "gemini-embedding-001"
+        assert e._model == "gemini-embedding-2"
 
     def test_custom_dim_1536(self, monkeypatch):
         monkeypatch.setenv("KNOWLEDGE_GEMINI_DIM", "1536")
@@ -88,10 +88,10 @@ def test_dim_with_quotes_is_cleaned(self, monkeypatch):
         assert mod.GeminiEmbedder().dim == 1536
 
     def test_custom_model(self, monkeypatch):
-        monkeypatch.setenv("KNOWLEDGE_GEMINI_MODEL", "gemini-embedding-2-preview")
+        monkeypatch.setenv("KNOWLEDGE_GEMINI_MODEL", "gemini-embedding-001")
         mod = _fresh_module()
         e = mod.GeminiEmbedder()
-        assert e._model == "gemini-embedding-2-preview"
+        assert e._model == "gemini-embedding-001"
         assert e.dim == 768
 
 
@@ -249,11 +249,10 @@ def test_001_passes_task_type_when_set(self, monkeypatch):
             kwargs = mock_types.EmbedContentConfig.call_args.kwargs
             assert kwargs.get("task_type") == "RETRIEVAL_QUERY"
 
-    def test_2_preview_skips_task_type(self, monkeypatch):
-        """gemini-embedding-2-preview does not support task_type per the
-        Google docs; our code must not pass it."""
+    def test_embedding_2_prefixes_task_type_and_uses_one_call_per_text(self, monkeypatch):
+        """gemini-embedding-2 prefixes task hints and avoids aggregate calls."""
         monkeypatch.setenv("GEMINI_API_KEY", "AIzaSy" + "x" * 33)
-        monkeypatch.setenv("KNOWLEDGE_GEMINI_MODEL", "gemini-embedding-2-preview")
+        monkeypatch.setenv("KNOWLEDGE_GEMINI_MODEL", "gemini-embedding-2")
         monkeypatch.setenv("KNOWLEDGE_GEMINI_DIM", "768")
         mod = _fresh_module()
         with patch.object(mod, "genai") as mock_genai, \
@@ -261,15 +260,22 @@ def test_2_preview_skips_task_type(self, monkeypatch):
             client = MagicMock()
             client.models.embed_content.return_value = _mock_embeddings_response(1)
             mock_genai.Client.return_value = client
-            mod.GeminiEmbedder().embed(["q"], task_type="RETRIEVAL_QUERY")
+            result = mod.GeminiEmbedder().embed(["q1", "q2"], task_type="RETRIEVAL_QUERY")
+            assert len(result) == 2
+            assert client.models.embed_content.call_count == 2
+            assert client.models.embed_content.call_args_list[0].kwargs["contents"] == "task: search result | query: q1"
+            assert client.models.embed_content.call_args_list[1].kwargs["contents"] == "task: search result | query: q2"
             # Since dim=768 is the native dim AND task_type is skipped,
             # there is no config to build at all → config=None.
             config = self._captured_config(
                 client.models.embed_content.call_args
             )
-            assert config is None
+            assert config is not None
+            kwargs = mock_types.EmbedContentConfig.call_args.kwargs
+            assert kwargs.get("output_dimensionality") == 768
+            assert "task_type" not in kwargs
             # And EmbedContentConfig was never constructed
-            mock_types.EmbedContentConfig.assert_not_called()
+            mock_types.EmbedContentConfig.assert_called_once()
 
     def test_001_without_task_type_omits_kwarg(self, monkeypatch):
         monkeypatch.setenv("GEMINI_API_KEY", "AIzaSy" + "x" * 33)
@@ -295,6 +301,7 @@ def test_001_without_task_type_omits_kwarg(self, monkeypatch):
 class TestBatching:
     def test_large_input_is_batched(self, monkeypatch):
         monkeypatch.setenv("GEMINI_API_KEY", "AIzaSy" + "x" * 33)
+        monkeypatch.setenv("KNOWLEDGE_GEMINI_MODEL", "gemini-embedding-001")
         monkeypatch.setenv("KNOWLEDGE_GEMINI_DIM", "768")
         mod = _fresh_module()
         # 50 texts with _BATCH_SIZE=20 → 3 calls (20, 20, 10)
diff --git a/dashboard/backend/knowledge/tests/test_migration_dim_from_env.py b/dashboard/backend/knowledge/tests/test_migration_dim_from_env.py
index f0dee97d..b54fa310 100644
--- a/dashboard/backend/knowledge/tests/test_migration_dim_from_env.py
+++ b/dashboard/backend/knowledge/tests/test_migration_dim_from_env.py
@@ -101,7 +101,7 @@ def test_gemini_default_is_768(self, monkeypatch):
         fn = self._fn()
         provider, model, dim = fn()
         assert provider == "gemini"
-        assert model == "gemini-embedding-001"
+        assert model == "gemini-embedding-2"
         assert dim == 768
 
     def test_gemini_custom_dim_1536(self, monkeypatch):
@@ -132,11 +132,11 @@ def test_gemini_non_numeric_dim_falls_back(self, monkeypatch):
         _, _, dim = fn()
         assert dim == 768
 
-    def test_gemini_2_preview_model(self, monkeypatch):
+    def test_gemini_001_model(self, monkeypatch):
         monkeypatch.setenv("KNOWLEDGE_EMBEDDER_PROVIDER", "gemini")
-        monkeypatch.setenv("KNOWLEDGE_GEMINI_MODEL", "gemini-embedding-2-preview")
+        monkeypatch.setenv("KNOWLEDGE_GEMINI_MODEL", "gemini-embedding-001")
         monkeypatch.delenv("KNOWLEDGE_GEMINI_DIM", raising=False)
         fn = self._fn()
         _, model, dim = fn()
-        assert model == "gemini-embedding-2-preview"
-        assert dim == 768  # native default for 2-preview in our config
+        assert model == "gemini-embedding-001"
+        assert dim == 768
diff --git a/dashboard/backend/knowledge/tests/test_parsers.py b/dashboard/backend/knowledge/tests/test_parsers.py
index 76216206..afd3d6c4 100644
--- a/dashboard/backend/knowledge/tests/test_parsers.py
+++ b/dashboard/backend/knowledge/tests/test_parsers.py
@@ -158,7 +158,7 @@ def test_parse_returns_pages_list(self, sample_pdf):
 
 
 class TestMarkerNotInstalled:
-    def test_parse_raises_actionable_error(self, monkeypatch):
+    def test_parse_raises_actionable_error(self, monkeypatch, tmp_path):
         _add_backend()
         import builtins
         real_import = builtins.__import__
@@ -175,14 +175,48 @@ def mock_import(name, *args, **kwargs):
         import knowledge.parsers.marker_parser as mod
         original_converter = mod._converter
         mod._converter = None
+        docx_path = tmp_path / "test.docx"
+        docx_path.write_bytes(b"fake docx")
         try:
             parser = MarkerParser()
             with pytest.raises(MarkerNotInstalledError, match="pip install marker-pdf"):
-                parser.parse(Path("/tmp/test.pdf"))
+                parser.parse(docx_path)
         finally:
             mod._converter = original_converter
 
 
+class TestPdfTextFallback:
+    def test_pdf_text_fallback_runs_before_marker_import(self, monkeypatch, sample_pdf):
+        _add_backend()
+        pytest.importorskip("pypdfium2")
+        import builtins
+        real_import = builtins.__import__
+
+        def mock_import(name, *args, **kwargs):
+            if name == "marker" or name.startswith("marker."):
+                raise AssertionError("marker should not be imported for searchable PDFs")
+            return real_import(name, *args, **kwargs)
+
+        monkeypatch.setattr(builtins, "__import__", mock_import)
+
+        from knowledge.parsers.marker_parser import MarkerParser
+        result = MarkerParser().parse(sample_pdf)
+
+        assert "Hello World" in result["markdown"]
+        assert result["metadata"]["parser_fallback"] == "pypdfium2"
+
+    def test_pypdfium_fallback_records_marker_error(self, sample_pdf):
+        _add_backend()
+        pytest.importorskip("pypdfium2")
+
+        import knowledge.parsers.marker_parser as mod
+        result = mod._maybe_parse_pdf_fallback(sample_pdf, RuntimeError("marker crashed"))
+
+        assert "Hello World" in result["markdown"]
+        assert result["metadata"]["parser_fallback"] == "pypdfium2"
+        assert "marker crashed" in result["metadata"]["marker_error"]
+
+
 # ---------------------------------------------------------------------------
 # LlamaParseParser stub
 # ---------------------------------------------------------------------------
diff --git a/dashboard/backend/knowledge/tests/test_settings_routes.py b/dashboard/backend/knowledge/tests/test_settings_routes.py
index 4ba6b26e..d5a4b72f 100644
--- a/dashboard/backend/knowledge/tests/test_settings_routes.py
+++ b/dashboard/backend/knowledge/tests/test_settings_routes.py
@@ -181,8 +181,8 @@ def test_gemini_provider_lists_both_models(self, client):
         data = resp.get_json()
         assert data["provider"] == "gemini"
         model_ids = [m["id"] for m in data["models"]]
+        assert "gemini-embedding-2" in model_ids
         assert "gemini-embedding-001" in model_ids
-        assert "gemini-embedding-2-preview" in model_ids
 
     def test_filter_by_openai_provider(self, client):
         with patch("routes.knowledge._assert_key", return_value=None):
@@ -353,7 +353,7 @@ def test_gemini_dim_invalid_value_rejected(self, client, monkeypatch):
             )
         assert resp.status_code == 400
 
-    def test_gemini_model_2_preview_accepted(self, client, monkeypatch, tmp_path):
+    def test_gemini_model_2_accepted(self, client, monkeypatch, tmp_path):
         monkeypatch.setenv("KNOWLEDGE_EMBEDDER_PROVIDER", "gemini")
         env_file = tmp_path / ".env"
         env_file.write_text("")
@@ -368,7 +368,7 @@ def test_gemini_model_2_preview_accepted(self, client, monkeypatch, tmp_path):
                 "/api/knowledge/settings",
                 json={
                     "embedder_provider": "gemini",
-                    "embedder_model": "gemini-embedding-2-preview",
+                    "embedder_model": "gemini-embedding-2",
                 },
                 headers=_WRITE_HEADERS,
             )
diff --git a/dashboard/backend/routes/agent_knowledge.py b/dashboard/backend/routes/agent_knowledge.py
new file mode 100644
index 00000000..5c7d2787
--- /dev/null
+++ b/dashboard/backend/routes/agent_knowledge.py
@@ -0,0 +1,426 @@
+"""Agent Knowledge routes.
+
+This module provides an accounting-friendly facade over the pgvector Knowledge
+engine. It keeps the canonical RAG divisions aligned with the custom accounting
+agents while reusing the existing Knowledge ingestion/search pipeline.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from flask import Blueprint, jsonify, request
+from flask_login import current_user
+from sqlalchemy import text
+from werkzeug.utils import secure_filename
+
+from routes.auth_routes import require_permission
+from routes.knowledge import _assert_key, _get_sqlite, _require_xhr
+
+from knowledge import documents as documents_mod
+from knowledge import search as search_mod
+from knowledge import spaces as spaces_mod
+from knowledge.connection_pool import get_dsn, get_engine
+
+bp = Blueprint("agent_knowledge", __name__)
+
+_UPLOAD_DIR = Path(__file__).resolve().parents[2] / "data" / "knowledge" / "uploads"
+
+
+AGENT_KNOWLEDGE_DIVISIONS: list[dict[str, Any]] = [
+    {
+        "slug": "geral",
+        "label": "Geral",
+        "agent": None,
+        "description": "Base compartilhada entre todos os agentes contabeis.",
+        "color": "#00FFA7",
+    },
+    {
+        "slug": "custom-atendimento",
+        "label": "Atendimento",
+        "agent": "custom-atendimento",
+        "description": "Triagem, comunicacao com clientes, pendencias e protocolos.",
+        "color": "#38BDF8",
+    },
+    {
+        "slug": "custom-controladoria",
+        "label": "Controladoria",
+        "agent": "custom-controladoria",
+        "description": "Indicadores, fechamentos gerenciais, controles e analises.",
+        "color": "#A78BFA",
+    },
+    {
+        "slug": "custom-fiscal",
+        "label": "Fiscal",
+        "agent": "custom-fiscal",
+        "description": "Tributos, notas, apuracoes, obrigacoes e legislacao fiscal.",
+        "color": "#F59E0B",
+    },
+    {
+        "slug": "custom-orquestrador",
+        "label": "Orquestrador",
+        "agent": "custom-orquestrador",
+        "description": "Procedimentos gerais, roteamento de demandas e regras de operacao.",
+        "color": "#00FFA7",
+    },
+    {
+        "slug": "custom-rh",
+        "label": "RH",
+        "agent": "custom-rh",
+        "description": "Folha, admissao, desligamento, beneficios e rotinas trabalhistas.",
+        "color": "#F472B6",
+    },
+    {
+        "slug": "custom-societario",
+        "label": "Societario",
+        "agent": "custom-societario",
+        "description": "Contratos sociais, alteracoes, CNPJ, licencas e Junta Comercial.",
+        "color": "#34D399",
+    },
+]
+
+_DIVISION_BY_SLUG = {d["slug"]: d for d in AGENT_KNOWLEDGE_DIVISIONS}
+
+
+def _error(code: str, message: str, status: int = 400):
+    return jsonify({"error": code, "message": message}), status
+
+
+def _connections() -> list[dict[str, Any]]:
+    _assert_key()
+    from knowledge.connections import list_connections
+
+    conn = _get_sqlite()
+    try:
+        return list_connections(conn)
+    finally:
+        conn.close()
+
+
+def _ready_connections() -> list[dict[str, Any]]:
+    return [c for c in _connections() if c.get("status") == "ready"]
+
+
+def _resolve_connection_id(preferred: str | None = None) -> tuple[str | None, list[dict[str, Any]]]:
+    ready = _ready_connections()
+    if preferred:
+        for conn in ready:
+            if preferred in {conn.get("id"), conn.get("slug")}:
+                return conn["id"], ready
+        raise ValueError(f"Knowledge connection '{preferred}' is not ready or does not exist.")
+    if not ready:
+        return None, ready
+    return ready[0]["id"], ready
+
+
+def _space_stats(connection_id: str, space_id: str) -> dict[str, int]:
+    engine = get_engine(connection_id, get_dsn(connection_id))
+    with engine.connect() as pg:
+        row = pg.execute(
+            text(
+                """
+                SELECT
+                    COUNT(DISTINCT d.id) AS documents_count,
+                    COUNT(c.id)          AS chunks_count
+                FROM knowledge_spaces s
+                LEFT JOIN knowledge_documents d ON d.space_id = s.id
+                LEFT JOIN knowledge_chunks c ON c.space_id = s.id
+                WHERE s.id = :space_id
+                """
+            ),
+            {"space_id": space_id},
+        ).fetchone()
+    if row is None:
+        return {"documents_count": 0, "chunks_count": 0}
+    data = dict(row._mapping)
+    return {
+        "documents_count": int(data.get("documents_count") or 0),
+        "chunks_count": int(data.get("chunks_count") or 0),
+    }
+
+
+def _space_payload(connection_id: str, division: dict[str, Any]) -> dict[str, Any]:
+    space = spaces_mod.get_space_by_slug(connection_id, division["slug"])
+    payload = {
+        **division,
+        "ready": bool(space),
+        "space": space,
+        "documents_count": 0,
+        "chunks_count": 0,
+    }
+    if space:
+        payload.update(_space_stats(connection_id, space["id"]))
+    return payload
+
+
+def _ensure_space(connection_id: str, division: dict[str, Any]) -> dict[str, Any]:
+    existing = spaces_mod.get_space_by_slug(connection_id, division["slug"])
+    if existing:
+        return existing
+
+    try:
+        return spaces_mod.create_space(
+            connection_id,
+            {
+                "slug": division["slug"],
+                "name": division["label"],
+                "description": division["description"],
+                "visibility": "shared",
+                "access_rules": {
+                    "agent_knowledge": True,
+                    "agent": division["agent"],
+                },
+                "content_type_boosts": {
+                    "faq": 1.25,
+                    "reference": 1.20,
+                    "decision": 1.15,
+                    "tutorial": 1.10,
+                    "article": 1.00,
+                    "note": 0.95,
+                    "transcript": 0.85,
+                },
+            },
+        )
+    except Exception:
+        # Concurrent first-run bootstrap may create the same slug between the
+        # read and insert. Re-read before surfacing the original error.
+        existing = spaces_mod.get_space_by_slug(connection_id, division["slug"])
+        if existing:
+            return existing
+        raise
+
+
+def _ensure_division(connection_id: str, slug: str) -> tuple[dict[str, Any], dict[str, Any]]:
+    division = _DIVISION_BY_SLUG.get(slug)
+    if not division:
+        raise KeyError(f"Unknown division '{slug}'")
+    return division, _ensure_space(connection_id, division)
+
+
+def _get_division_space(connection_id: str, slug: str) -> tuple[dict[str, Any], dict[str, Any] | None]:
+    division = _DIVISION_BY_SLUG.get(slug)
+    if not division:
+        raise KeyError(f"Unknown division '{slug}'")
+    return division, spaces_mod.get_space_by_slug(connection_id, division["slug"])
+
+
+def _document_status(document_id: str) -> dict[str, Any]:
+    return documents_mod.get_ingestion_status(document_id) or {"document_id": document_id, "phase": "pending"}
+
+
+@bp.route("/api/agent-knowledge/divisions", methods=["GET"])
+@require_permission("knowledge", "view")
+def divisions():
+    try:
+        connection_id, ready = _resolve_connection_id(request.args.get("connection_id"))
+    except Exception as exc:
+        return _error("connection_error", str(exc), 400)
+
+    if not connection_id:
+        return jsonify(
+            {
+                "connections": ready,
+                "active_connection_id": None,
+                "divisions": AGENT_KNOWLEDGE_DIVISIONS,
+                "ready": False,
+                "message": "No ready pgvector Knowledge connection configured.",
+            }
+        )
+
+    try:
+        return jsonify(
+            {
+                "connections": ready,
+                "active_connection_id": connection_id,
+                "divisions": [_space_payload(connection_id, d) for d in AGENT_KNOWLEDGE_DIVISIONS],
+                "ready": True,
+            }
+        )
+    except Exception as exc:
+        return _error("divisions_failed", str(exc), 500)
+
+
+@bp.route("/api/agent-knowledge/bootstrap", methods=["POST"])
+@require_permission("knowledge", "manage")
+def bootstrap():
+    _require_xhr()
+    data = request.get_json(silent=True) or {}
+    try:
+        connection_id, _ready = _resolve_connection_id(data.get("connection_id"))
+        if not connection_id:
+            return _error("no_connection", "No ready pgvector Knowledge connection configured.", 400)
+        created = []
+        for division in AGENT_KNOWLEDGE_DIVISIONS:
+            before = spaces_mod.get_space_by_slug(connection_id, division["slug"])
+            space = _ensure_space(connection_id, division)
+            if before is None:
+                created.append(space["slug"])
+        return jsonify(
+            {
+                "status": "ready",
+                "created": created,
+                "divisions": [_space_payload(connection_id, d) for d in AGENT_KNOWLEDGE_DIVISIONS],
+            }
+        )
+    except Exception as exc:
+        return _error("bootstrap_failed", str(exc), 500)
+
+
+@bp.route("/api/agent-knowledge/documents", methods=["GET"])
+@require_permission("knowledge", "view")
+def list_documents():
+    try:
+        connection_id, _ready = _resolve_connection_id(request.args.get("connection_id"))
+        if not connection_id:
+            return _error("no_connection", "No ready pgvector Knowledge connection configured.", 400)
+        division_slug = request.args.get("division") or "all"
+        limit = min(int(request.args.get("limit", 25)), 100)
+
+        if division_slug == "all":
+            documents = []
+            for division in AGENT_KNOWLEDGE_DIVISIONS:
+                space = spaces_mod.get_space_by_slug(connection_id, division["slug"])
+                if not space:
+                    continue
+                for doc in documents_mod.list_documents(connection_id, space_id=space["id"], limit=limit):
+                    documents.append({**doc, "division": division["slug"], "division_label": division["label"]})
+            documents.sort(key=lambda d: str(d.get("created_at") or ""), reverse=True)
+            return jsonify({"documents": documents[:limit]})
+
+        division, space = _get_division_space(connection_id, division_slug)
+        if not space:
+            return jsonify({"documents": []})
+        documents = [
+            {**doc, "division": division["slug"], "division_label": division["label"]}
+            for doc in documents_mod.list_documents(connection_id, space_id=space["id"], limit=limit)
+        ]
+        return jsonify({"documents": documents})
+    except KeyError as exc:
+        return _error("bad_division", str(exc), 404)
+    except Exception as exc:
+        return _error("documents_failed", str(exc), 500)
+
+
+@bp.route("/api/agent-knowledge/upload", methods=["POST"])
+@require_permission("knowledge", "manage")
+def upload():
+    _require_xhr()
+    try:
+        connection_id, _ready = _resolve_connection_id(request.form.get("connection_id"))
+        if not connection_id:
+            return _error("no_connection", "No ready pgvector Knowledge connection configured.", 400)
+        division_slug = request.form.get("division") or ""
+        division, space = _ensure_division(connection_id, division_slug)
+    except KeyError as exc:
+        return _error("bad_division", str(exc), 404)
+    except Exception as exc:
+        return _error("upload_failed", str(exc), 500)
+
+    files = request.files.getlist("files") or request.files.getlist("file")
+    if not files:
+        return _error("bad_request", "Missing uploaded files.", 400)
+
+    raw_tags = request.form.get("tags") or ""
+    extra_tags = [t.strip() for t in raw_tags.split(",") if t.strip()]
+    uploads = []
+    tmp_dir = _UPLOAD_DIR
+    tmp_dir.mkdir(parents=True, exist_ok=True)
+
+    for f in files:
+        original_name = f.filename or "document"
+        safe_name = secure_filename(original_name) or f"document-{uuid4().hex}"
+        tmp_path = tmp_dir / f"{uuid4().hex}-{safe_name}"
+        f.save(str(tmp_path))
+
+        metadata = {
+            "title": request.form.get("title") or Path(original_name).stem,
+            "tags": ["agent-knowledge", division["slug"], *(extra_tags or [])],
+            "owner_id": str(getattr(current_user, "id", "") or ""),
+            "agent": division["agent"],
+            "division": division["slug"],
+            "mime_type": f.mimetype or None,
+        }
+        doc = documents_mod.upload_document(connection_id, space["id"], str(tmp_path), metadata)
+        uploads.append(
+            {
+                "document": doc,
+                "document_id": doc.get("id"),
+                "filename": original_name,
+                "division": division["slug"],
+                "division_label": division["label"],
+                "status": _document_status(doc.get("id")),
+            }
+        )
+
+    return jsonify({"uploads": uploads}), 202
+
+
+@bp.route("/api/agent-knowledge/documents/<document_id>/status", methods=["GET"])
+@require_permission("knowledge", "view")
+def status(document_id: str):
+    return jsonify(_document_status(document_id))
+
+
+@bp.route("/api/agent-knowledge/documents/<document_id>", methods=["DELETE"])
+@require_permission("knowledge", "manage")
+def delete_document(document_id: str):
+    _require_xhr()
+    try:
+        connection_id, _ready = _resolve_connection_id(request.args.get("connection_id"))
+        if not connection_id:
+            return _error("no_connection", "No ready pgvector Knowledge connection configured.", 400)
+        ok = documents_mod.delete_document(connection_id, document_id)
+        if not ok:
+            return _error("not_found", f"Document {document_id} not found.", 404)
+        return jsonify({"status": "deleted", "document_id": document_id})
+    except Exception as exc:
+        return _error("delete_failed", str(exc), 500)
+
+
+@bp.route("/api/agent-knowledge/search", methods=["GET"])
+@require_permission("knowledge", "view")
+def search():
+    query = (request.args.get("q") or request.args.get("query") or "").strip()
+    if not query:
+        return _error("bad_request", "query is required", 400)
+
+    try:
+        connection_id, _ready = _resolve_connection_id(request.args.get("connection_id"))
+        if not connection_id:
+            return _error("no_connection", "No ready pgvector Knowledge connection configured.", 400)
+        division_slug = request.args.get("division") or "all"
+        top_k = min(int(request.args.get("top_k", 10)), 50)
+
+        targets = []
+        if division_slug == "all":
+            for division in AGENT_KNOWLEDGE_DIVISIONS:
+                space = spaces_mod.get_space_by_slug(connection_id, division["slug"])
+                if space:
+                    targets.append((division, space))
+        else:
+            division, space = _get_division_space(connection_id, division_slug)
+            if not space:
+                return jsonify({"query": query, "results": [], "total": 0})
+            targets.append((division, space))
+
+        results = []
+        per_target_k = top_k if len(targets) <= 1 else max(3, top_k)
+        for division, space in targets:
+            hits = search_mod.hybrid_search(
+                connection_id=connection_id,
+                space_id=space["id"],
+                query=query,
+                top_k=per_target_k,
+                filters={},
+            )
+            for hit in hits:
+                results.append({**hit, "division": division["slug"], "division_label": division["label"]})
+
+        results.sort(key=lambda r: float(r.get("final_score") or 0), reverse=True)
+        return jsonify({"query": query, "results": results[:top_k], "total": len(results[:top_k])})
+    except KeyError as exc:
+        return _error("bad_division", str(exc), 404)
+    except Exception as exc:
+        return _error("search_failed", str(exc), 500)
diff --git a/dashboard/backend/routes/brain_repo.py b/dashboard/backend/routes/brain_repo.py
index 5bd8dd03..b47703ba 100644
--- a/dashboard/backend/routes/brain_repo.py
+++ b/dashboard/backend/routes/brain_repo.py
@@ -240,6 +240,76 @@ def _decrypt_token(config: BrainRepoConfig) -> str:
 
 # ── Status ────────────────────────────────────────────
 
+def _repo_name_from_url(repo_url: str) -> str:
+    cleaned = repo_url.strip().rstrip("/")
+    if cleaned.endswith(".git"):
+        cleaned = cleaned[:-4]
+    return cleaned.rsplit("/", 1)[-1] if cleaned else ""
+
+
+def _repo_owner_from_url(repo_url: str) -> str:
+    cleaned = repo_url.strip().rstrip("/")
+    if cleaned.endswith(".git"):
+        cleaned = cleaned[:-4]
+    if "/" not in cleaned:
+        return ""
+    owner = cleaned.rsplit("/", 2)[-2]
+    if ":" in owner:
+        owner = owner.rsplit(":", 1)[-1]
+    return owner
+
+
+def _enqueue_bootstrap_for_config(
+    config: BrainRepoConfig,
+    token: str,
+    *,
+    sync_after: bool = False,
+    workspace: Path | None = None,
+    tag_name: str | None = None,
+    commit_message: str | None = None,
+) -> bool:
+    """Repair/init the local clone for a connected Brain Repo config."""
+    if not config.repo_url:
+        abort(400, description="Brain repo URL not configured")
+
+    repo_name = config.repo_name or _repo_name_from_url(config.repo_url)
+    if not repo_name:
+        abort(400, description="Brain repo name not configured")
+
+    repo_owner = config.repo_owner or _repo_owner_from_url(config.repo_url)
+    try:
+        from brain_repo.github_api import get_github_username
+        github_username = get_github_username(token)
+    except Exception:
+        github_username = repo_owner
+
+    config.repo_name = repo_name
+    config.repo_owner = repo_owner
+    config.local_path = None
+    config.last_error = None
+    db.session.commit()
+
+    try:
+        from brain_repo import job_runner
+        from flask import current_app
+    except ImportError:
+        abort(500, description="job_runner module unavailable")
+
+    return job_runner.enqueue_bootstrap(
+        current_app._get_current_object(),  # type: ignore[attr-defined]
+        current_user.id,
+        token=token,
+        repo_url=config.repo_url,
+        repo_name=repo_name,
+        owner_username=current_user.username or repo_owner,
+        github_username=github_username,
+        sync_after=sync_after,
+        workspace=workspace,
+        tag_name=tag_name,
+        commit_message=commit_message,
+    )
+
+
 @bp.route("/api/brain-repo/status")
 @login_required
 def status():
@@ -392,15 +462,27 @@ def connect():
     else:
         # Validate existing repo is private
         try:
-            from brain_repo.github_api import get_repo_info
+            from brain_repo.github_api import get_repo_info, get_github_username
             ok_private, repo_info = get_repo_info(token, repo_url)
         except ImportError:
             ok_private, repo_info = True, {}  # graceful fallback
 
         if not ok_private:
             abort(400, description="Repository must be private")
-        repo_owner = repo_info.get("owner", {}).get("login", "")
-        repo_name = repo_info.get("name", "")
+        repo_owner = repo_info.get("owner", {}).get("login", "") or _repo_owner_from_url(repo_url)
+        repo_name = repo_info.get("name", "") or _repo_name_from_url(repo_url)
+        try:
+            github_username = get_github_username(token)
+        except Exception:
+            github_username = repo_owner
+        bootstrap_pending = True
+        bootstrap_params = {
+            "token": token,
+            "repo_url": repo_url,
+            "repo_name": repo_name,
+            "owner_username": current_user.username or repo_owner,
+            "github_username": github_username,
+        }
 
     # Encrypt and store token.
     #
@@ -451,6 +533,8 @@ def connect():
     config.repo_url = repo_url
     config.repo_owner = repo_owner
     config.repo_name = repo_name
+    if bootstrap_pending:
+        config.local_path = None
     # local_path stays NULL when bootstrap is deferred — it gets filled in by
     # job_runner.run_bootstrap_pipeline after the push succeeds. UI reads
     # sync_in_progress + local_path==null as "initializing".
@@ -628,31 +712,67 @@ def sync_force():
     if not config or not config.github_token_encrypted:
         abort(400, description="Brain repo not connected")
 
+    token = _decrypt_token(config)
+    if not token:
+        abort(500, description="Could not decrypt stored token - re-connect the brain repo")
+
+    workspace = Path(__file__).resolve().parent.parent.parent.parent
+    now = datetime.now(timezone.utc)
+    # Seconds in the tag name avoids "tag already exists" on rapid re-clicks
+    tag_name = f"milestone/manual-{now.strftime('%Y-%m-%d-%H-%M-%S')}"
+    sync_commit_message = f"manual sync {now.isoformat()}"
+
     local_path = config.local_path
     if not local_path:
-        abort(400, description="local_path not configured — repo not yet cloned")
+        enqueued = _enqueue_bootstrap_for_config(
+            config,
+            token,
+            sync_after=True,
+            workspace=workspace,
+            tag_name=tag_name,
+            commit_message=sync_commit_message,
+        )
+        if not enqueued:
+            return jsonify({
+                "ok": False,
+                "error": "Another sync is already running for this user.",
+                "code": "SYNC_IN_PROGRESS",
+            }), 409
+        return jsonify({
+            "ok": True,
+            "status": "queued",
+            "job": "bootstrap",
+            "message": "Local brain repo clone queued. Sync will run after initialization.",
+        }), 202
 
     repo_dir = Path(local_path)
     if not repo_dir.is_dir() or not (repo_dir / ".git").is_dir():
-        abort(500, description=f"Local brain repo at {local_path} is missing or corrupt — re-connect")
-
-    # Quick token-decryption probe so bad keys fail fast (before enqueueing).
-    # The pipeline re-decrypts inside the thread — we just surface the error
-    # synchronously here so the UI can react inline.
-    token = _decrypt_token(config)
-    if not token:
-        abort(500, description="Could not decrypt stored token — re-connect the brain repo")
+        enqueued = _enqueue_bootstrap_for_config(
+            config,
+            token,
+            sync_after=True,
+            workspace=workspace,
+            tag_name=tag_name,
+            commit_message=sync_commit_message,
+        )
+        if not enqueued:
+            return jsonify({
+                "ok": False,
+                "error": "Another sync is already running for this user.",
+                "code": "SYNC_IN_PROGRESS",
+            }), 409
+        return jsonify({
+            "ok": True,
+            "status": "queued",
+            "job": "bootstrap",
+            "message": "Local brain repo clone repaired. Sync will run after initialization.",
+        }), 202
 
     try:
         from brain_repo import job_runner
     except ImportError:
         abort(500, description="job_runner module unavailable")
 
-    workspace = Path(__file__).resolve().parent.parent.parent.parent
-    now = datetime.now(timezone.utc)
-    # Seconds in the tag name avoids "tag already exists" on rapid re-clicks
-    tag_name = f"milestone/manual-{now.strftime('%Y-%m-%d-%H-%M-%S')}"
-
     from flask import current_app
     enqueued = job_runner.enqueue_sync(
         current_app._get_current_object(),  # type: ignore[attr-defined]
@@ -660,7 +780,7 @@ def sync_force():
         workspace,
         kind=job_runner.JOB_KIND_SYNC,
         tag_name=tag_name,
-        commit_message=f"manual sync {now.isoformat()}",
+        commit_message=sync_commit_message,
     )
     if not enqueued:
         return jsonify({
@@ -699,27 +819,68 @@ def tag_milestone():
     if not config or not config.github_token_encrypted:
         abort(400, description="Brain repo not connected")
 
+    token = _decrypt_token(config)
+    if not token:
+        abort(500, description="Could not decrypt stored token - re-connect the brain repo")
+
+    workspace = Path(__file__).resolve().parent.parent.parent.parent
+    tag = f"milestone/{name}"
+    now = datetime.now(timezone.utc)
+    milestone_commit_message = f"milestone: {name} ({now.isoformat()})"
+
     local_path = config.local_path
     if not local_path:
-        abort(400, description="local_path not configured — repo not yet cloned")
+        enqueued = _enqueue_bootstrap_for_config(
+            config,
+            token,
+            sync_after=True,
+            workspace=workspace,
+            tag_name=tag,
+            commit_message=milestone_commit_message,
+        )
+        if not enqueued:
+            return jsonify({
+                "ok": False,
+                "error": "Another sync is already running for this user.",
+                "code": "SYNC_IN_PROGRESS",
+            }), 409
+        return jsonify({
+            "ok": True,
+            "status": "queued",
+            "job": "bootstrap",
+            "tag": tag,
+            "message": "Local brain repo clone queued. Milestone sync will run after initialization.",
+        }), 202
 
     repo_dir = Path(local_path)
     if not repo_dir.is_dir() or not (repo_dir / ".git").is_dir():
-        abort(500, description=f"Local brain repo at {local_path} is missing or corrupt — re-connect")
-
-    token = _decrypt_token(config)
-    if not token:
-        abort(500, description="Could not decrypt stored token — re-connect the brain repo")
+        enqueued = _enqueue_bootstrap_for_config(
+            config,
+            token,
+            sync_after=True,
+            workspace=workspace,
+            tag_name=tag,
+            commit_message=milestone_commit_message,
+        )
+        if not enqueued:
+            return jsonify({
+                "ok": False,
+                "error": "Another sync is already running for this user.",
+                "code": "SYNC_IN_PROGRESS",
+            }), 409
+        return jsonify({
+            "ok": True,
+            "status": "queued",
+            "job": "bootstrap",
+            "tag": tag,
+            "message": "Local brain repo clone repaired. Milestone sync will run after initialization.",
+        }), 202
 
     try:
         from brain_repo import job_runner
     except ImportError:
         abort(500, description="job_runner module unavailable")
 
-    workspace = Path(__file__).resolve().parent.parent.parent.parent
-    tag = f"milestone/{name}"
-    now = datetime.now(timezone.utc)
-
     from flask import current_app
     enqueued = job_runner.enqueue_sync(
         current_app._get_current_object(),  # type: ignore[attr-defined]
@@ -727,7 +888,7 @@ def tag_milestone():
         workspace,
         kind=job_runner.JOB_KIND_MILESTONE,
         tag_name=tag,
-        commit_message=f"milestone: {name} ({now.isoformat()})",
+        commit_message=milestone_commit_message,
     )
     if not enqueued:
         return jsonify({
diff --git a/dashboard/backend/routes/knowledge.py b/dashboard/backend/routes/knowledge.py
index 1d5ecfd1..f6c2e807 100644
--- a/dashboard/backend/routes/knowledge.py
+++ b/dashboard/backend/routes/knowledge.py
@@ -68,7 +68,7 @@ def _require_xhr() -> None:
         "vector_dim": 1536,
     },
     "gemini": {
-        "model": "gemini-embedding-001",
+        "model": "gemini-embedding-2",
         "vector_dim": 768,
     },
 }
@@ -90,13 +90,12 @@ def _require_xhr() -> None:
         {"id": "text-embedding-ada-002", "dim": 1536, "legacy": True},
     ],
     "gemini": [
-        {"id": "gemini-embedding-001", "dim": 768, "recommended": True,
-         "supports_task_type": True,
-         "note": "Text-only. Supports task_type for retrieval optimization."},
-        {"id": "gemini-embedding-2-preview", "dim": 768,
+        {"id": "gemini-embedding-2", "dim": 768, "recommended": True,
          "supports_task_type": False,
-         "preview": True,
-         "note": "Multimodal preview. Task hint must be inline in the prompt."},
+         "note": "Stable multimodal Embedding 2. Task hints are encoded as text prefixes for RAG."},
+        {"id": "gemini-embedding-001", "dim": 768,
+         "supports_task_type": True,
+         "note": "Legacy text-only model. Supports task_type for retrieval optimization."},
     ],
 }
 
diff --git a/dashboard/backend/routes/providers.py b/dashboard/backend/routes/providers.py
index a2127ef8..c7ec03ef 100644
--- a/dashboard/backend/routes/providers.py
+++ b/dashboard/backend/routes/providers.py
@@ -55,6 +55,16 @@
     "CLOUD_ML_REGION",
 })
 
+DEFAULT_FAILOVER_ORDER = [
+    "openrouter",
+    "anthropic",
+    "openai",
+    "codex_auth",
+    "gemini",
+    "bedrock",
+    "vertex",
+]
+
 
 def _read_config() -> dict:
     """Read providers.json. If missing, copy from providers.example.json."""
@@ -68,7 +78,7 @@ def _read_config() -> dict:
             return json.loads(PROVIDERS_CONFIG.read_text(encoding="utf-8"))
     except (json.JSONDecodeError, OSError):
         pass
-    return {"active_provider": "anthropic", "providers": {}}
+    return {"active_provider": "openrouter", "providers": {}}
 
 
 def _write_config(config: dict):
@@ -80,6 +90,45 @@ def _write_config(config: dict):
     )
 
 
+def _normalize_failover_order(order: list[str] | tuple[str, ...] | None, provider_map: dict, active_provider: str) -> list[str]:
+    """Return a stable failover order with active first and unavailable ids removed."""
+    seen: set[str] = set()
+    normalized: list[str] = []
+
+    def append(provider_id: str | None):
+        if not provider_id or provider_id in seen:
+            return
+        provider = provider_map.get(provider_id)
+        if provider is None or provider.get("coming_soon"):
+            return
+        seen.add(provider_id)
+        normalized.append(provider_id)
+
+    append(active_provider)
+    for provider_id in order or []:
+        append(provider_id)
+    for provider_id in DEFAULT_FAILOVER_ORDER:
+        append(provider_id)
+    for provider_id in provider_map:
+        append(provider_id)
+    return normalized
+
+
+def _ensure_routing(config: dict) -> dict:
+    providers = config.get("providers", {}) or {}
+    active = config.get("active_provider", "openrouter")
+    routing = config.get("routing") if isinstance(config.get("routing"), dict) else {}
+    raw_order = routing.get("failover_order")
+    if not isinstance(raw_order, list):
+        raw_order = DEFAULT_FAILOVER_ORDER
+    normalized = {
+        "enabled": routing.get("enabled", True) is not False,
+        "failover_order": _normalize_failover_order(raw_order, providers, active),
+    }
+    config["routing"] = normalized
+    return normalized
+
+
 def _mask_secret(value: str) -> str:
     """Mask an API key for safe display: sk-or-v1-abc...xyz → sk-or-****xyz."""
     if not value or len(value) < 8:
@@ -87,6 +136,10 @@ def _mask_secret(value: str) -> str:
     return value[:6] + "****" + value[-4:]
 
 
+def _is_secret_env_var(name: str) -> bool:
+    return "KEY" in name or "SECRET" in name or "TOKEN" in name
+
+
 def _run_cli_version(command: str, env: dict | None = None) -> dict:
     """Run '<command> --version' safely using hardcoded dispatch.
 
@@ -169,6 +222,32 @@ def _save_codex_auth(tokens: dict):
     CODEX_AUTH_FILE.write_text(json.dumps(auth_data, indent=2), encoding="utf-8")
 
 
+def _notify_terminal_server_provider_change(new_provider: str, old_provider: str):
+    """Notify the terminal-server that the active provider has changed.
+
+    Fire-and-forget: the UI response should not be blocked by this call.
+    The terminal-server will invalidate stale PTY sessions and broadcast
+    a WebSocket event to all connected clients.
+    """
+    import threading
+
+    def _do_notify():
+        import requests as http_req
+        try:
+            http_req.post(
+                "http://localhost:32352/api/provider-changed",
+                json={"new_provider": new_provider, "old_provider": old_provider},
+                timeout=5,
+            )
+        except Exception as e:
+            import logging
+            logging.getLogger(__name__).warning(
+                "Failed to notify terminal-server of provider change: %s", e
+            )
+
+    threading.Thread(target=_do_notify, daemon=True).start()
+
+
 # ── Endpoints ──────────────────────────────────────────────
 
 
@@ -177,8 +256,9 @@ def _save_codex_auth(tokens: dict):
 def list_providers():
     """List all providers with status info."""
     config = _read_config()
-    active = config.get("active_provider", "anthropic")
+    active = config.get("active_provider", "openrouter")
     providers = config.get("providers", {})
+    routing = _ensure_routing(config)
 
     # Check CLI installation status for both binaries
     claude_status = _check_cli("claude")
@@ -228,6 +308,7 @@ def list_providers():
     return jsonify({
         "providers": result,
         "active_provider": active,
+        "routing": routing,
         "claude_installed": claude_status["installed"],
         "openclaude_installed": openclaude_status["installed"],
     })
@@ -238,7 +319,7 @@ def list_providers():
 def get_active_provider():
     """Get the active provider."""
     config = _read_config()
-    active = config.get("active_provider", "anthropic")
+    active = config.get("active_provider", "openrouter")
     provider = config.get("providers", {}).get(active, {})
     return jsonify({
         "active_provider": active,
@@ -261,9 +342,15 @@ def set_active_provider():
     if provider_id != "none" and provider_id not in config.get("providers", {}):
         return jsonify({"error": f"Unknown provider: {provider_id}"}), 400
 
+    old_provider = config.get("active_provider", "openrouter")
     config["active_provider"] = provider_id
+    _ensure_routing(config)
     _write_config(config)
 
+    # Notify terminal-server so it can invalidate stale PTY sessions immediately.
+    if provider_id != old_provider:
+        _notify_terminal_server_provider_change(provider_id, old_provider)
+
     return jsonify({"status": "ok", "active_provider": provider_id})
 
 
@@ -314,6 +401,11 @@ def update_provider_config(provider_id):
         # Skip if value looks masked (contains ****)
         if "****" in str(value):
             continue
+        # Secret inputs are rendered blank when the UI only has a masked value.
+        # Treat blank secret fields as "unchanged" so saving another provider
+        # field does not erase an existing API key/token.
+        if _is_secret_env_var(key) and str(value).strip() == "" and existing.get(key):
+            continue
         # Reject values with shell metacharacters
         if not isinstance(value, str) or re.search(r'[;&|`$\n\r]', value):
             continue
@@ -685,6 +777,6 @@ def openai_logout():
     if CODEX_AUTH_FILE.is_file():
         CODEX_AUTH_FILE.unlink()
     config = _read_config()
-    config["active_provider"] = "anthropic"
+    config["active_provider"] = "openrouter"
     _write_config(config)
     return jsonify({"status": "ok"})
diff --git a/dashboard/backend/routes/terminal_proxy.py b/dashboard/backend/routes/terminal_proxy.py
index 17b5a6af..12ef780b 100644
--- a/dashboard/backend/routes/terminal_proxy.py
+++ b/dashboard/backend/routes/terminal_proxy.py
@@ -156,6 +156,10 @@ def proxy_ws(client_ws):
         target = f"{TERMINAL_WS_BASE}/ws"
         try:
             upstream = create_connection(target, timeout=10)
+            # `timeout` above should only bound the initial connection. The
+            # websocket-client library keeps it as the socket read timeout too,
+            # so an otherwise healthy but quiet terminal closes after 10s.
+            upstream.settimeout(None)
         except Exception as exc:
             log.warning("terminal_proxy: upstream WS connect failed: %s", exc)
             try:
@@ -190,7 +194,10 @@ def _pump_upstream_to_client():
 
         try:
             while not stop.is_set():
-                msg = client_ws.receive(timeout=30)
+                # Keep the tunnel open while the browser is idle. A fixed
+                # receive timeout closes valid agent sessions when the user is
+                # reading output or a hidden tab has throttled timers.
+                msg = client_ws.receive()
                 if msg is None:
                     break
                 upstream.send(msg)
diff --git a/dashboard/frontend/index.html b/dashboard/frontend/index.html
index 9f57cf68..aca0738d 100644
--- a/dashboard/frontend/index.html
+++ b/dashboard/frontend/index.html
@@ -9,12 +9,13 @@
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
     <!--
       Wave 2.1 CSP hardening (connect-src):
-      - 'self' covers all /api/* and /plugins/* fetch calls
-      - ws://localhost:5173 is needed for Vite HMR in dev (removed by build pipeline in prod)
+      - 'self' covers all /api/*, /plugins/*, and same-origin terminal proxy calls
+      - ws:/wss: are required for browser WebSocket implementations that do
+        not treat ws(s)://same-host as 'self' for connect-src
       - Google Fonts are loaded via <link rel="stylesheet"> (style-src / font-src, not connect-src)
     -->
     <meta http-equiv="Content-Security-Policy"
-      content="connect-src 'self' ws://localhost:5173 ws://localhost:8080" />
+      content="connect-src 'self' ws: wss:" />
     <title>Evo Workspace</title>
   </head>
   <body class="bg-[#0C111D] text-[#F9FAFB]">
diff --git a/dashboard/frontend/src/App.tsx b/dashboard/frontend/src/App.tsx
index d6f411a2..58206445 100644
--- a/dashboard/frontend/src/App.tsx
+++ b/dashboard/frontend/src/App.tsx
@@ -57,6 +57,7 @@ const KnowledgeUpload = lazyDefault(() => import('./pages/Knowledge/Upload'))
 const KnowledgeBrowse = lazyDefault(() => import('./pages/Knowledge/Browse'))
 const KnowledgeSearch = lazyDefault(() => import('./pages/Knowledge/Search'))
 const KnowledgeApiKeys = lazyDefault(() => import('./pages/Knowledge/ApiKeys'))
+const AgentKnowledge = lazyDefault(() => import('./pages/AgentKnowledge'))
 
 function FullPageRoute({
   locationKey,
@@ -256,6 +257,7 @@ function AppContent() {
               {hasPermission('heartbeats', 'view') && <Route path="/heartbeats/:id" element={<HeartbeatDetail />} />}
               <Route path="/memory" element={<Memory />} />
               <Route path="/mempalace" element={<MemPalace />} />
+              {hasPermission('knowledge', 'view') && <Route path="/agent-knowledge" element={<AgentKnowledge />} />}
               <Route path="/systems" element={<Systems />} />
               {hasPermission('config', 'view') && <Route path="/settings" element={<Settings />} />}
               {hasPermission('config', 'view') && <Route path="/backups" element={<Backups />} />}
diff --git a/dashboard/frontend/src/components/AgentChat.tsx b/dashboard/frontend/src/components/AgentChat.tsx
index b60ff664..e4d9442d 100644
--- a/dashboard/frontend/src/components/AgentChat.tsx
+++ b/dashboard/frontend/src/components/AgentChat.tsx
@@ -138,8 +138,17 @@ export default function AgentChat({ agent, sessionId, accentColor = '#00FFA7', e
     setErrorMsg(null)
     let cancelled = false
     let ws: WebSocket | null = null
+    let reconnectTimer: ReturnType<typeof setTimeout> | null = null
+
+    const scheduleReconnect = () => {
+      if (cancelled || reconnectTimer) return
+      reconnectTimer = setTimeout(() => {
+        reconnectTimer = null
+        if (!cancelled) connectSocket()
+      }, 1000)
+    }
 
-    ;(async () => {
+    async function connectSocket() {
       // 1) HTTP preflight — fails fast on ECONNREFUSED so we can show a real error
       //    instead of hanging in 'connecting' forever (same pattern as AgentTerminal).
       try {
@@ -156,14 +165,21 @@ export default function AgentChat({ agent, sessionId, accentColor = '#00FFA7', e
       // 2) Open WS
       ws = new WebSocket(`${TS_WS}/ws`)
       wsRef.current = ws
+      let opened = false
+
+      const isCurrentSocket = () => !cancelled && wsRef.current === ws
 
       ws.onopen = () => {
+        if (!isCurrentSocket()) return
+        opened = true
+        setErrorMsg(null)
         ws!.send(JSON.stringify({ type: 'join_session', sessionId }))
         setStatus('idle')
       }
 
       ws.onmessage = (ev) => {
-        if (cancelled) return
+        if (!isCurrentSocket()) return
+        setErrorMsg(null)
         let msg: any
         try { msg = JSON.parse(ev.data) } catch { return }
 
@@ -273,13 +289,25 @@ export default function AgentChat({ agent, sessionId, accentColor = '#00FFA7', e
       }
 
       ws.onerror = () => {
-        if (cancelled) return
-        setStatus('error')
-        setErrorMsg('WebSocket error')
+        if (!isCurrentSocket()) return
+        if (!opened) {
+          setStatus('error')
+          setErrorMsg(`Could not open WebSocket at ${TS_WS}/ws`)
+        }
       }
 
       ws.onclose = () => {
         if (pingRef.current) { clearInterval(pingRef.current); pingRef.current = null }
+        if (wsRef.current === ws) {
+          wsRef.current = null
+        } else {
+          return
+        }
+        if (!cancelled) {
+          setStatus('connecting')
+          setErrorMsg(opened ? 'WebSocket disconnected. Reconnecting...' : `Could not open WebSocket at ${TS_WS}/ws`)
+          scheduleReconnect()
+        }
       }
 
       pingRef.current = setInterval(() => {
@@ -287,10 +315,13 @@ export default function AgentChat({ agent, sessionId, accentColor = '#00FFA7', e
           ws!.send(JSON.stringify({ type: 'ping' }))
         }
       }, 25000)
-    })()
+    }
+
+    connectSocket()
 
     return () => {
       cancelled = true
+      if (reconnectTimer) clearTimeout(reconnectTimer)
       if (pingRef.current) { clearInterval(pingRef.current); pingRef.current = null }
       try { ws?.close() } catch {}
       wsRef.current = null
diff --git a/dashboard/frontend/src/components/AgentTerminal.tsx b/dashboard/frontend/src/components/AgentTerminal.tsx
index ef438a0a..352b2ec8 100644
--- a/dashboard/frontend/src/components/AgentTerminal.tsx
+++ b/dashboard/frontend/src/components/AgentTerminal.tsx
@@ -3,6 +3,7 @@ import { Terminal } from '@xterm/xterm'
 import { FitAddon } from '@xterm/addon-fit'
 import { WebLinksAddon } from '@xterm/addon-web-links'
 import '@xterm/xterm/css/xterm.css'
+import { TS_HTTP, TS_WS } from '../lib/terminal-url'
 
 interface AgentTerminalProps {
   agent: string
@@ -11,65 +12,8 @@ interface AgentTerminalProps {
   accentColor?: string
 }
 
-// Terminal connection URL resolution.
-//
-// We always go through the dashboard's /terminal proxy in production builds.
-// Direct cross-port fetches (e.g. localhost:32352 from a page served at
-// localhost:8080) are blocked by the dashboard's `connect-src 'self'` CSP
-// directive even when the network path would work. The proxy gives us:
-//   1. Same-origin requests pass CSP `'self'`.
-//   2. No CORS preflight (same origin).
-//   3. Works through SSH tunnels, Tailscale Funnel, or any reverse proxy
-//      that only exposes the dashboard port.
-//
-// Escape hatch for cases where the proxy can't be used (e.g. a static
-// dashboard build hosted somewhere unrelated to the terminal-server): set
-// VITE_TERMINAL_URL at build time to force a specific base URL. When set,
-// it overrides the proxy. Trailing slash is stripped so both
-// `https://x.y/terminal` and `https://x.y/terminal/` work.
-//
-// In Vite's `npm run dev` mode (port 5173, no proxy mounted) we fall back
-// to a direct connection to terminal-server. That path is local-only by
-// definition.
-const rawOverride = (import.meta.env.VITE_TERMINAL_URL as string | undefined)?.trim()
-const terminalOverride = rawOverride ? rawOverride.replace(/\/+$/, '') : null
-
-const hostname = window.location.hostname
-const isViteDev = import.meta.env.DEV
-
-// Resolve an override URL into the (httpBase, wsBase) pair the rest of the
-// component expects. Accepts either http(s):// or ws(s):// — both schemes
-// are mapped to their counterpart so users can paste whichever they have
-// on hand. Invalid input falls back to the heuristic.
-function resolveOverride(raw: string): { http: string; ws: string } | null {
-  try {
-    const u = new URL(raw)
-    const isSecure = u.protocol === 'https:' || u.protocol === 'wss:'
-    const httpProto = isSecure ? 'https:' : 'http:'
-    const wsProto = isSecure ? 'wss:' : 'ws:'
-    const path = u.pathname.replace(/\/+$/, '') + u.search
-    return {
-      http: `${httpProto}//${u.host}${path}`,
-      ws: `${wsProto}//${u.host}${path}`,
-    }
-  } catch {
-    return null
-  }
-}
-
-const override = terminalOverride ? resolveOverride(terminalOverride) : null
-
-const CC_WEB_HTTP = override
-  ? override.http
-  : isViteDev
-    ? `http://${hostname}:32352`
-    : `${window.location.origin}/terminal`
-
-const CC_WEB_WS = override
-  ? override.ws
-  : isViteDev
-    ? `ws://${hostname}:32352`
-    : `${window.location.protocol === 'https:' ? 'wss:' : 'ws:'}//${window.location.host}/terminal`
+const CC_WEB_HTTP = TS_HTTP
+const CC_WEB_WS = TS_WS
 
 type Status = 'connecting' | 'ready' | 'starting' | 'running' | 'error' | 'exited'
 
@@ -80,6 +24,8 @@ export default function AgentTerminal({ agent, sessionId: externalSessionId, wor
   const wsRef = useRef<WebSocket | null>(null)
   const sessionIdRef = useRef<string | null>(null)
   const pingRef = useRef<ReturnType<typeof setInterval> | null>(null)
+  const reconnectTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const processEndedRef = useRef(false)
   const [status, setStatus] = useState<Status>('connecting')
   const [errorMsg, setErrorMsg] = useState<string | null>(null)
 
@@ -184,10 +130,29 @@ export default function AgentTerminal({ agent, sessionId: externalSessionId, wor
     const term = termRef.current
     if (!term) return
 
-    async function run() {
+    function clearReconnectTimer() {
+      if (reconnectTimerRef.current) {
+        clearTimeout(reconnectTimerRef.current)
+        reconnectTimerRef.current = null
+      }
+    }
+
+    function scheduleReconnect() {
+      if (cancelled || processEndedRef.current || reconnectTimerRef.current) return
+      reconnectTimerRef.current = setTimeout(() => {
+        reconnectTimerRef.current = null
+        if (!cancelled && !processEndedRef.current) {
+          run(false)
+        }
+      }, 1000)
+    }
+
+    async function run(clearTerminal = true) {
+      clearReconnectTimer()
+      processEndedRef.current = false
       setStatus('connecting')
       setErrorMsg(null)
-      term!.clear()
+      if (clearTerminal) term!.clear()
 
       // 1) Use provided sessionId or find-or-create for this agent
       let sessionId: string
@@ -226,18 +191,25 @@ export default function AgentTerminal({ agent, sessionId: externalSessionId, wor
       // 2) Open WS
       const ws = new WebSocket(`${CC_WEB_WS}/ws`)
       wsRef.current = ws
+      let opened = false
+
+      const isCurrentSocket = () => !cancelled && wsRef.current === ws
 
       ws.onopen = () => {
+        if (!isCurrentSocket()) return
+        opened = true
+        setErrorMsg(null)
         ws.send(JSON.stringify({ type: 'join_session', sessionId }))
       }
 
       ws.onmessage = (ev) => {
-        if (cancelled) return
+        if (!isCurrentSocket()) return
         let msg: any
         try { msg = JSON.parse(ev.data) } catch { return }
 
         switch (msg.type) {
           case 'session_joined': {
+            setErrorMsg(null)
             // Replay any buffered output
             if (Array.isArray(msg.outputBuffer)) {
               msg.outputBuffer.forEach((chunk: string) => term!.write(chunk))
@@ -276,9 +248,11 @@ export default function AgentTerminal({ agent, sessionId: externalSessionId, wor
             break
           }
           case 'output':
+            setErrorMsg(null)
             term!.write(msg.data)
             break
           case 'claude_started':
+            setErrorMsg(null)
             setStatus('running')
             // resize after start
             {
@@ -290,6 +264,7 @@ export default function AgentTerminal({ agent, sessionId: externalSessionId, wor
             }
             break
           case 'exit':
+            processEndedRef.current = true
             setStatus('exited')
             term!.write(`\r\n\x1b[33m[Process exited${msg.code != null ? ` with code ${msg.code}` : ''}]\x1b[0m\r\n`)
             break
@@ -304,9 +279,11 @@ export default function AgentTerminal({ agent, sessionId: externalSessionId, wor
       }
 
       ws.onerror = () => {
-        if (cancelled) return
-        setStatus('error')
-        setErrorMsg('WebSocket error')
+        if (!isCurrentSocket()) return
+        if (!opened) {
+          setStatus('error')
+          setErrorMsg(`Could not open WebSocket at ${CC_WEB_WS}/ws`)
+        }
       }
 
       ws.onclose = () => {
@@ -314,6 +291,16 @@ export default function AgentTerminal({ agent, sessionId: externalSessionId, wor
           clearInterval(pingRef.current)
           pingRef.current = null
         }
+        if (wsRef.current === ws) {
+          wsRef.current = null
+        } else {
+          return
+        }
+        if (!cancelled && !processEndedRef.current) {
+          setStatus('connecting')
+          setErrorMsg(opened ? 'WebSocket disconnected. Reconnecting...' : `Could not open WebSocket at ${CC_WEB_WS}/ws`)
+          scheduleReconnect()
+        }
       }
 
       // Keepalive
@@ -328,6 +315,7 @@ export default function AgentTerminal({ agent, sessionId: externalSessionId, wor
 
     return () => {
       cancelled = true
+      clearReconnectTimer()
       if (pingRef.current) {
         clearInterval(pingRef.current)
         pingRef.current = null
diff --git a/dashboard/frontend/src/components/Sidebar.tsx b/dashboard/frontend/src/components/Sidebar.tsx
index 42bb21eb..3bb07035 100644
--- a/dashboard/frontend/src/components/Sidebar.tsx
+++ b/dashboard/frontend/src/components/Sidebar.tsx
@@ -73,6 +73,7 @@ const navGroups: NavGroup[] = [
       { to: '/memory', labelKey: 'memory', icon: Brain, resource: 'memory' },
       { to: '/mempalace', labelKey: 'mempalace', icon: Library, resource: 'mempalace' },
       { to: '/knowledge', labelKey: 'knowledge', icon: Database, resource: 'knowledge' },
+      { to: '/agent-knowledge', labelKey: 'agentKnowledge', icon: Bot, resource: 'knowledge' },
       { to: '/costs', labelKey: 'costs', icon: DollarSign, resource: 'costs' },
     ],
   },
diff --git a/dashboard/frontend/src/i18n/locales/es/index.ts b/dashboard/frontend/src/i18n/locales/es/index.ts
index 721276f4..26ff0555 100644
--- a/dashboard/frontend/src/i18n/locales/es/index.ts
+++ b/dashboard/frontend/src/i18n/locales/es/index.ts
@@ -184,6 +184,7 @@ const translations = {
       issues: 'Temas',
       reports: 'Informes',
       mempalace: 'MemPalace',
+      agentKnowledge: 'Base RAG',
       systems: 'Sistemas',
       templates: 'Plantillas',
       shareLinks: 'Enlaces compartidos',
diff --git a/dashboard/frontend/src/i18n/locales/pt-BR/index.ts b/dashboard/frontend/src/i18n/locales/pt-BR/index.ts
index 941c612f..aac13b98 100644
--- a/dashboard/frontend/src/i18n/locales/pt-BR/index.ts
+++ b/dashboard/frontend/src/i18n/locales/pt-BR/index.ts
@@ -191,6 +191,7 @@ const translations = {
       issues: 'Tópicos',
       reports: 'Relatórios',
       mempalace: 'MemPalace',
+      agentKnowledge: 'Base RAG',
       systems: 'Sistemas',
       templates: 'Modelos',
       shareLinks: 'Links compartilhados',
diff --git a/dashboard/frontend/src/lib/navigation.ts b/dashboard/frontend/src/lib/navigation.ts
index 196df408..a7455e7a 100644
--- a/dashboard/frontend/src/lib/navigation.ts
+++ b/dashboard/frontend/src/lib/navigation.ts
@@ -79,6 +79,7 @@ export const NAV_GROUPS: NavGroup[] = [
       { to: '/memory', labelKey: 'memory', icon: Brain, resource: 'memory' },
       { to: '/mempalace', labelKey: 'mempalace', icon: Library, resource: 'mempalace' },
       { to: '/knowledge', labelKey: 'knowledge', icon: Database, resource: 'knowledge' },
+      { to: '/agent-knowledge', labelKey: 'agentKnowledge', icon: Bot, resource: 'knowledge' },
       { to: '/costs', labelKey: 'costs', icon: DollarSign, resource: 'costs' },
     ],
   },
diff --git a/dashboard/frontend/src/lib/terminal-url.ts b/dashboard/frontend/src/lib/terminal-url.ts
index fe1f3bc7..7dcba017 100644
--- a/dashboard/frontend/src/lib/terminal-url.ts
+++ b/dashboard/frontend/src/lib/terminal-url.ts
@@ -1,27 +1,52 @@
 /**
  * Shared terminal-server URL constants.
- * Exported here so AgentChat, useGlobalNotifications, and any future consumer
- * all resolve the same base URL without duplication.
+ * Exported here so AgentDetail, AgentTerminal, AgentChat,
+ * useGlobalNotifications, and any future consumer all resolve the same base
+ * URL without duplication.
  *
  * The dashboard backend mounts an HTTP+WebSocket proxy at /terminal that
- * forwards to the local terminal-server. Going through it (rather than
- * hitting :32352 directly) wins on three fronts:
- *   1. Same-origin requests pass the dashboard's CSP `connect-src 'self'`
- *      directive — direct cross-port fetches are blocked even from localhost.
- *   2. CORS preflights are avoided (same origin).
- *   3. Browsers behind SSH tunnels, Tailscale Funnel, or any reverse proxy
- *      that only exposes the dashboard port still get terminal access.
+ * forwards to the local terminal-server. Going through it keeps terminal
+ * access on the same origin as the dashboard, which works behind SSH
+ * tunnels, Tailscale Funnel, and reverse proxies that expose only the
+ * dashboard port.
  *
- * The vite dev server (port 5173) does not yet proxy /terminal, so in DEV
- * mode we fall back to a direct connection — that path is local-only by
- * definition.
+ * Escape hatch: VITE_TERMINAL_URL can point at a separate terminal-server
+ * base URL. It accepts http(s):// or ws(s):// and maps to both schemes.
+ *
+ * The Vite dev server (port 5173) does not proxy /terminal, so in DEV mode
+ * we fall back to a direct connection to terminal-server.
  */
 const isViteDev = import.meta.env.DEV
+const rawOverride = (import.meta.env.VITE_TERMINAL_URL as string | undefined)?.trim()
+const terminalOverride = rawOverride ? rawOverride.replace(/\/+$/, '') : null
+
+function resolveOverride(raw: string): { http: string; ws: string } | null {
+  try {
+    const url = new URL(raw)
+    const isSecure = url.protocol === 'https:' || url.protocol === 'wss:'
+    const httpProtocol = isSecure ? 'https:' : 'http:'
+    const wsProtocol = isSecure ? 'wss:' : 'ws:'
+    const path = url.pathname.replace(/\/+$/, '') + url.search
+
+    return {
+      http: `${httpProtocol}//${url.host}${path}`,
+      ws: `${wsProtocol}//${url.host}${path}`,
+    }
+  } catch {
+    return null
+  }
+}
+
+const override = terminalOverride ? resolveOverride(terminalOverride) : null
 
-export const TS_HTTP = isViteDev
-  ? `http://${window.location.hostname}:32352`
-  : `${window.location.protocol}//${window.location.host}/terminal`
+export const TS_HTTP = override
+  ? override.http
+  : isViteDev
+    ? `http://${window.location.hostname}:32352`
+    : `${window.location.protocol}//${window.location.host}/terminal`
 
-export const TS_WS = isViteDev
-  ? `ws://${window.location.hostname}:32352`
-  : `${window.location.protocol === 'https:' ? 'wss:' : 'ws:'}//${window.location.host}/terminal`
+export const TS_WS = override
+  ? override.ws
+  : isViteDev
+    ? `ws://${window.location.hostname}:32352`
+    : `${window.location.protocol === 'https:' ? 'wss:' : 'ws:'}//${window.location.host}/terminal`
diff --git a/dashboard/frontend/src/pages/AgentDetail.tsx b/dashboard/frontend/src/pages/AgentDetail.tsx
index 803f5cba..f5a80f88 100644
--- a/dashboard/frontend/src/pages/AgentDetail.tsx
+++ b/dashboard/frontend/src/pages/AgentDetail.tsx
@@ -11,6 +11,7 @@ import { trackAgentVisit } from './Agents'
 import { AgentAvatar } from '../components/AgentAvatar'
 import { useAuth } from '../context/AuthContext'
 import { useNotificationBadge } from '../hooks/useNotificationBadge'
+import { TS_HTTP } from '../lib/terminal-url'
 
 interface MemoryFile {
   name: string
@@ -20,16 +21,6 @@ interface MemoryFile {
 
 type Tab = 'sessions' | 'profile' | 'memory'
 
-// Terminal-server URL — always go through the dashboard's /terminal proxy in
-// production builds. Direct cross-port fetches (e.g. localhost:32352 from a
-// page served at localhost:8080) are blocked by the dashboard's
-// `connect-src 'self'` CSP directive even when the network path works.
-// In Vite dev mode (no proxy mounted) we fall back to a direct connection.
-const isViteDev = import.meta.env.DEV
-const TS_HTTP = isViteDev
-  ? `http://${window.location.hostname}:32352`
-  : `${window.location.origin}/terminal`
-
 interface TerminalTab {
   id: string       // sessionId
   name: string     // display name
diff --git a/dashboard/frontend/src/pages/AgentKnowledge.tsx b/dashboard/frontend/src/pages/AgentKnowledge.tsx
new file mode 100644
index 00000000..6696166d
--- /dev/null
+++ b/dashboard/frontend/src/pages/AgentKnowledge.tsx
@@ -0,0 +1,670 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import {
+  AlertCircle,
+  Bot,
+  CheckCircle2,
+  Database,
+  FileText,
+  Loader2,
+  RefreshCw,
+  Search,
+  Trash2,
+  Upload,
+} from 'lucide-react'
+import { useNavigate } from 'react-router-dom'
+import { api } from '../lib/api'
+import { useAuth } from '../context/AuthContext'
+
+const API_BASE = import.meta.env.DEV ? 'http://localhost:8080' : ''
+
+interface KnowledgeConnection {
+  id: string
+  slug: string
+  name: string
+  status: string
+}
+
+interface Division {
+  slug: string
+  label: string
+  agent: string | null
+  description: string
+  color: string
+  ready: boolean
+  documents_count: number
+  chunks_count: number
+  space?: { id: string; slug: string; name: string } | null
+}
+
+interface DivisionResponse {
+  connections: KnowledgeConnection[]
+  active_connection_id: string | null
+  divisions: Division[]
+  ready: boolean
+  message?: string
+}
+
+interface KnowledgeDocument {
+  id: string
+  title: string
+  status: string
+  created_at?: string
+  chunks_count?: number
+  pages_count?: number
+  division: string
+  division_label: string
+}
+
+interface UploadItem {
+  id: string
+  filename: string
+  documentId?: string
+  division: string
+  phase: string
+  error?: string
+}
+
+interface SearchHit {
+  chunk_id: string
+  document_id: string
+  doc_title?: string
+  content_type?: string
+  content: string
+  final_score?: number
+  division: string
+  division_label: string
+  chunk_metadata?: Record<string, unknown>
+}
+
+function formatDate(value?: string) {
+  if (!value) return '-'
+  try {
+    return new Intl.DateTimeFormat('pt-BR', { dateStyle: 'short', timeStyle: 'short' }).format(new Date(value))
+  } catch {
+    return value
+  }
+}
+
+function phaseLabel(phase: string) {
+  const normalized = phase || 'pending'
+  const labels: Record<string, string> = {
+    queued: 'Na fila',
+    pending: 'Pendente',
+    scanning: 'Analisando',
+    parsing: 'Lendo arquivo',
+    chunking: 'Quebrando em trechos',
+    embedding: 'Gerando vetores',
+    storing: 'Gravando',
+    classifying: 'Classificando',
+    processing: 'Processando',
+    ready: 'Pronto',
+    done: 'Pronto',
+    error: 'Erro',
+  }
+  return labels[normalized] || normalized
+}
+
+function statusColor(status: string) {
+  if (['ready', 'done'].includes(status)) return '#00FFA7'
+  if (status === 'error') return '#F87171'
+  return '#FBBF24'
+}
+
+export default function AgentKnowledge() {
+  const navigate = useNavigate()
+  const { hasPermission } = useAuth()
+  const canManage = hasPermission('knowledge', 'manage')
+
+  const [loading, setLoading] = useState(true)
+  const [bootstrapping, setBootstrapping] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [connections, setConnections] = useState<KnowledgeConnection[]>([])
+  const [activeConnectionId, setActiveConnectionId] = useState<string | null>(null)
+  const [divisions, setDivisions] = useState<Division[]>([])
+  const [selectedDivision, setSelectedDivision] = useState('geral')
+  const [documents, setDocuments] = useState<KnowledgeDocument[]>([])
+  const [documentsLoading, setDocumentsLoading] = useState(false)
+
+  const [files, setFiles] = useState<File[]>([])
+  const [dragging, setDragging] = useState(false)
+  const [uploading, setUploading] = useState(false)
+  const [uploads, setUploads] = useState<UploadItem[]>([])
+  const fileInputRef = useRef<HTMLInputElement>(null)
+  const pollers = useRef<Record<string, ReturnType<typeof setInterval>>>({})
+
+  const [query, setQuery] = useState('')
+  const [searchScope, setSearchScope] = useState('all')
+  const [searching, setSearching] = useState(false)
+  const [searchResults, setSearchResults] = useState<SearchHit[] | null>(null)
+
+  const selected = useMemo(
+    () => divisions.find((d) => d.slug === selectedDivision) || divisions[0],
+    [divisions, selectedDivision]
+  )
+
+  const allReady = divisions.length > 0 && divisions.every((d) => d.ready)
+
+  const loadDivisions = useCallback(async (connectionId?: string | null) => {
+    setError(null)
+    const suffix = connectionId ? `?connection_id=${encodeURIComponent(connectionId)}` : ''
+    const data: DivisionResponse = await api.get(`/agent-knowledge/divisions${suffix}`)
+    setConnections(data.connections || [])
+    setActiveConnectionId(data.active_connection_id)
+    setDivisions(data.divisions || [])
+    if (!selectedDivision && data.divisions?.[0]) setSelectedDivision(data.divisions[0].slug)
+    return data
+  }, [selectedDivision])
+
+  const loadDocuments = useCallback(async () => {
+    if (!activeConnectionId || !selectedDivision) return
+    setDocumentsLoading(true)
+    try {
+      const params = new URLSearchParams({
+        connection_id: activeConnectionId,
+        division: selectedDivision,
+        limit: '25',
+      })
+      const data = await api.get(`/agent-knowledge/documents?${params}`)
+      setDocuments(data.documents || [])
+    } catch {
+      setDocuments([])
+    } finally {
+      setDocumentsLoading(false)
+    }
+  }, [activeConnectionId, selectedDivision])
+
+  useEffect(() => {
+    loadDivisions()
+      .catch((e) => setError(e instanceof Error ? e.message : 'Falha ao carregar a base RAG.'))
+      .finally(() => setLoading(false))
+  }, [loadDivisions])
+
+  useEffect(() => {
+    loadDocuments()
+  }, [loadDocuments])
+
+  useEffect(() => {
+    return () => {
+      Object.values(pollers.current).forEach(clearInterval)
+    }
+  }, [])
+
+  async function handleBootstrap() {
+    if (!activeConnectionId) return
+    setBootstrapping(true)
+    setError(null)
+    try {
+      const data = await api.post('/agent-knowledge/bootstrap', { connection_id: activeConnectionId })
+      setDivisions(data.divisions || [])
+      await loadDocuments()
+    } catch (e) {
+      setError(e instanceof Error ? e.message : 'Falha ao preparar as divisões RAG.')
+    } finally {
+      setBootstrapping(false)
+    }
+  }
+
+  function addFiles(nextFiles: File[]) {
+    if (nextFiles.length === 0) return
+    setFiles((prev) => [...prev, ...nextFiles])
+  }
+
+  function updateUpload(id: string, patch: Partial<UploadItem>) {
+    setUploads((prev) => prev.map((item) => item.id === id ? { ...item, ...patch } : item))
+  }
+
+  function pollStatus(localId: string, documentId: string) {
+    const interval = setInterval(async () => {
+      try {
+        const data = await api.get(`/agent-knowledge/documents/${documentId}/status`)
+        const phase = data.phase || data.status || 'processing'
+        updateUpload(localId, { phase, error: data.error || data.error_message })
+        if (['done', 'ready', 'error'].includes(phase)) {
+          clearInterval(interval)
+          delete pollers.current[localId]
+          await loadDivisions(activeConnectionId)
+          await loadDocuments()
+        }
+      } catch {
+        updateUpload(localId, { phase: 'error', error: 'Falha ao consultar status.' })
+        clearInterval(interval)
+        delete pollers.current[localId]
+      }
+    }, 2000)
+    pollers.current[localId] = interval
+  }
+
+  async function handleUpload() {
+    if (!activeConnectionId || !selected || files.length === 0) return
+    setUploading(true)
+    setError(null)
+    try {
+      const body = new FormData()
+      body.append('connection_id', activeConnectionId)
+      body.append('division', selected.slug)
+      files.forEach((file) => body.append('files', file))
+
+      const res = await fetch(`${API_BASE}/api/agent-knowledge/upload`, {
+        method: 'POST',
+        credentials: 'include',
+        headers: { 'X-Requested-With': 'XMLHttpRequest' },
+        body,
+      })
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}))
+        throw new Error(data.message || data.error || `Upload falhou: ${res.status}`)
+      }
+      const data = await res.json()
+      const items: UploadItem[] = (data.uploads || []).map((upload: any) => ({
+        id: `${upload.document_id}-${Math.random()}`,
+        filename: upload.filename,
+        documentId: upload.document_id,
+        division: upload.division,
+        phase: upload.status?.phase || upload.document?.status || 'pending',
+      }))
+      setUploads((prev) => [...items, ...prev])
+      setFiles([])
+      items.forEach((item) => {
+        if (item.documentId) pollStatus(item.id, item.documentId)
+      })
+      await loadDivisions(activeConnectionId)
+      await loadDocuments()
+    } catch (e) {
+      setError(e instanceof Error ? e.message : 'Falha ao enviar arquivos.')
+    } finally {
+      setUploading(false)
+    }
+  }
+
+  async function handleSearch() {
+    if (!activeConnectionId || !query.trim()) return
+    setSearching(true)
+    setError(null)
+    try {
+      const params = new URLSearchParams({
+        connection_id: activeConnectionId,
+        division: searchScope,
+        q: query.trim(),
+        top_k: '12',
+      })
+      const data = await api.get(`/agent-knowledge/search?${params}`)
+      setSearchResults(data.results || [])
+    } catch (e) {
+      setError(e instanceof Error ? e.message : 'Falha ao buscar na base RAG.')
+      setSearchResults([])
+    } finally {
+      setSearching(false)
+    }
+  }
+
+  async function handleDelete(documentId: string) {
+    if (!activeConnectionId) return
+    try {
+      await api.delete(`/agent-knowledge/documents/${documentId}?connection_id=${encodeURIComponent(activeConnectionId)}`)
+      await loadDivisions(activeConnectionId)
+      await loadDocuments()
+    } catch (e) {
+      setError(e instanceof Error ? e.message : 'Falha ao excluir documento.')
+    }
+  }
+
+  if (loading) {
+    return (
+      <div className="flex items-center justify-center py-20 text-[#667085] text-sm">
+        <Loader2 size={16} className="animate-spin mr-2" /> Carregando base RAG...
+      </div>
+    )
+  }
+
+  if (!activeConnectionId) {
+    return (
+      <div className="max-w-3xl mx-auto py-16">
+        <div className="border border-[#344054] bg-[#182230] rounded-xl p-8 text-center">
+          <Database size={34} className="text-[#667085] mx-auto mb-4" />
+          <h1 className="text-xl font-semibold text-[#F9FAFB]">Base RAG dos Agentes</h1>
+          <p className="text-sm text-[#8b949e] mt-2">
+            Nenhuma conexão pgvector pronta foi encontrada.
+          </p>
+          <button
+            onClick={() => navigate('/knowledge')}
+            className="mt-5 px-4 py-2 rounded-lg bg-[#00FFA7] text-[#0C111D] text-sm font-medium"
+          >
+            Configurar pgvector
+          </button>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="max-w-[1500px] mx-auto space-y-6">
+      <div className="flex flex-col gap-4 lg:flex-row lg:items-end lg:justify-between">
+        <div>
+          <div className="flex items-center gap-3">
+            <div className="h-10 w-10 rounded-lg border border-[#00FFA7]/20 bg-[#00FFA7]/10 flex items-center justify-center">
+              <Database size={18} className="text-[#00FFA7]" />
+            </div>
+            <div>
+              <h1 className="text-2xl font-bold text-[#F9FAFB]">Base RAG dos Agentes</h1>
+              <p className="text-sm text-[#667085] mt-1">Conhecimento pgvector dividido por agente contábil</p>
+            </div>
+          </div>
+        </div>
+
+        <div className="flex items-center gap-2">
+          {connections.length > 1 && (
+            <select
+              value={activeConnectionId}
+              onChange={async (e) => {
+                setActiveConnectionId(e.target.value)
+                await loadDivisions(e.target.value)
+              }}
+              className="bg-[#182230] border border-[#344054] rounded-lg px-3 py-2 text-sm text-[#D0D5DD] focus:border-[#00FFA7] focus:outline-none"
+            >
+              {connections.map((conn) => (
+                <option key={conn.id} value={conn.id}>{conn.name || conn.slug}</option>
+              ))}
+            </select>
+          )}
+          <button
+            onClick={async () => {
+              await loadDivisions(activeConnectionId)
+              await loadDocuments()
+            }}
+            className="inline-flex items-center gap-2 px-3 py-2 rounded-lg border border-[#344054] text-sm text-[#D0D5DD] hover:bg-white/[0.03]"
+          >
+            <RefreshCw size={14} /> Atualizar
+          </button>
+        </div>
+      </div>
+
+      {error && (
+        <div className="flex items-start gap-2 rounded-xl border border-red-500/30 bg-red-500/10 px-4 py-3 text-sm text-red-300">
+          <AlertCircle size={16} className="mt-0.5 shrink-0" />
+          <span>{error}</span>
+        </div>
+      )}
+
+      {!allReady && (
+        <div className="flex flex-col gap-3 rounded-xl border border-[#F59E0B]/25 bg-[#F59E0B]/8 px-4 py-4 sm:flex-row sm:items-center sm:justify-between">
+          <div>
+            <p className="text-sm font-medium text-[#F9FAFB]">Divisões RAG pendentes</p>
+            <p className="text-xs text-[#98A2B3] mt-1">Crie os Spaces pgvector: Geral e os seis agentes customizados.</p>
+          </div>
+          {canManage && (
+            <button
+              onClick={handleBootstrap}
+              disabled={bootstrapping}
+              className="inline-flex items-center justify-center gap-2 px-4 py-2 rounded-lg bg-[#00FFA7] text-[#0C111D] text-sm font-medium disabled:opacity-60"
+            >
+              {bootstrapping ? <Loader2 size={14} className="animate-spin" /> : <CheckCircle2 size={14} />}
+              Preparar base
+            </button>
+          )}
+        </div>
+      )}
+
+      <div className="grid grid-cols-1 xl:grid-cols-[360px_minmax(0,1fr)] gap-6">
+        <div className="space-y-2">
+          {divisions.map((division) => (
+            <button
+              key={division.slug}
+              onClick={() => {
+                setSelectedDivision(division.slug)
+                setSearchScope(division.slug)
+              }}
+              className={`w-full text-left rounded-xl border px-4 py-3 transition-colors ${
+                selectedDivision === division.slug
+                  ? 'border-[#00FFA7]/50 bg-[#00FFA7]/8'
+                  : 'border-[#243044] bg-[#111827] hover:border-[#344054]'
+              }`}
+            >
+              <div className="flex items-start justify-between gap-3">
+                <div className="flex min-w-0 gap-3">
+                  <div
+                    className="mt-0.5 h-8 w-8 rounded-lg flex items-center justify-center shrink-0"
+                    style={{ backgroundColor: `${division.color}22`, border: `1px solid ${division.color}44` }}
+                  >
+                    <Bot size={15} style={{ color: division.color }} />
+                  </div>
+                  <div className="min-w-0">
+                    <p className="text-sm font-semibold text-[#F9FAFB] truncate">{division.label}</p>
+                    <p className="text-xs text-[#667085] truncate">{division.agent || 'base-geral'}</p>
+                    <p className="text-xs text-[#98A2B3] mt-1 line-clamp-2">{division.description}</p>
+                  </div>
+                </div>
+                <span
+                  className="text-[10px] px-2 py-0.5 rounded-full shrink-0"
+                  style={{
+                    color: division.ready ? '#00FFA7' : '#FBBF24',
+                    background: division.ready ? 'rgba(0,255,167,0.08)' : 'rgba(251,191,36,0.1)',
+                    border: `1px solid ${division.ready ? 'rgba(0,255,167,0.18)' : 'rgba(251,191,36,0.22)'}`,
+                  }}
+                >
+                  {division.ready ? 'pronta' : 'pendente'}
+                </span>
+              </div>
+              <div className="mt-3 grid grid-cols-2 gap-2 text-xs">
+                <span className="rounded-lg bg-[#0C111D] px-2 py-1 text-[#98A2B3]">
+                  <strong className="text-[#E6EDF3]">{division.documents_count}</strong> docs
+                </span>
+                <span className="rounded-lg bg-[#0C111D] px-2 py-1 text-[#98A2B3]">
+                  <strong className="text-[#E6EDF3]">{division.chunks_count}</strong> chunks
+                </span>
+              </div>
+            </button>
+          ))}
+        </div>
+
+        <div className="space-y-6">
+          <section className="rounded-xl border border-[#243044] bg-[#111827] p-5">
+            <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between mb-4">
+              <div>
+                <h2 className="text-base font-semibold text-[#F9FAFB]">Upload para {selected?.label}</h2>
+                <p className="text-xs text-[#667085] mt-1">{selected?.agent || 'Conhecimento comum dos agentes'}</p>
+              </div>
+              {files.length > 0 && (
+                <button
+                  onClick={() => setFiles([])}
+                  className="text-xs text-[#98A2B3] hover:text-[#F9FAFB]"
+                >
+                  Limpar seleção
+                </button>
+              )}
+            </div>
+
+            <div
+              onDragOver={(e) => { e.preventDefault(); setDragging(true) }}
+              onDragLeave={() => setDragging(false)}
+              onDrop={(e) => {
+                e.preventDefault()
+                setDragging(false)
+                addFiles(Array.from(e.dataTransfer.files))
+              }}
+              onClick={() => fileInputRef.current?.click()}
+              className={`border-2 border-dashed rounded-xl p-8 text-center cursor-pointer transition-colors ${
+                dragging ? 'border-[#00FFA7] bg-[#00FFA7]/5' : 'border-[#344054] hover:border-[#00FFA7]/40'
+              }`}
+            >
+              <Upload size={26} className={dragging ? 'text-[#00FFA7] mx-auto mb-3' : 'text-[#667085] mx-auto mb-3'} />
+              <p className="text-sm font-medium text-[#D0D5DD]">Arraste arquivos ou clique para selecionar</p>
+              <p className="text-xs text-[#667085] mt-1">PDF, DOCX, PPTX, XLSX, HTML, imagens, TXT, MD, CSV e JSON</p>
+              <input
+                ref={fileInputRef}
+                type="file"
+                multiple
+                accept=".pdf,.docx,.pptx,.xlsx,.html,.htm,.epub,.txt,.md,.markdown,.csv,.json,.png,.jpg,.jpeg,.gif,.webp,.tiff,.tif"
+                className="hidden"
+                onChange={(e) => {
+                  if (e.target.files) addFiles(Array.from(e.target.files))
+                  e.currentTarget.value = ''
+                }}
+              />
+            </div>
+
+            {files.length > 0 && (
+              <div className="mt-4 space-y-3">
+                <div className="flex flex-wrap gap-2">
+                  {files.map((file, idx) => (
+                    <span key={`${file.name}-${idx}`} className="inline-flex items-center gap-1 rounded-lg border border-[#344054] bg-[#0C111D] px-2.5 py-1 text-xs text-[#D0D5DD]">
+                      <FileText size={12} /> {file.name}
+                    </span>
+                  ))}
+                </div>
+                <button
+                  onClick={handleUpload}
+                  disabled={uploading || !canManage || !selected?.ready}
+                  className="inline-flex items-center gap-2 px-4 py-2 rounded-lg bg-[#00FFA7] text-[#0C111D] text-sm font-medium disabled:opacity-50"
+                >
+                  {uploading ? <Loader2 size={14} className="animate-spin" /> : <Upload size={14} />}
+                  Enviar para {selected?.label}
+                </button>
+                {!canManage && <p className="text-xs text-[#FBBF24]">Seu papel precisa de permissão knowledge:manage para upload.</p>}
+                {selected && !selected.ready && <p className="text-xs text-[#FBBF24]">Prepare a divisão antes de enviar arquivos.</p>}
+              </div>
+            )}
+
+            {uploads.length > 0 && (
+              <div className="mt-5 space-y-2">
+                {uploads.slice(0, 6).map((item) => (
+                  <div key={item.id} className="flex items-center justify-between gap-3 rounded-lg bg-[#0C111D] border border-[#243044] px-3 py-2">
+                    <div className="min-w-0">
+                      <p className="text-sm text-[#D0D5DD] truncate">{item.filename}</p>
+                      {item.error && <p className="text-xs text-red-300 mt-0.5">{item.error}</p>}
+                    </div>
+                    <span
+                      className="text-xs px-2 py-0.5 rounded-full shrink-0"
+                      style={{ color: statusColor(item.phase), background: `${statusColor(item.phase)}14`, border: `1px solid ${statusColor(item.phase)}33` }}
+                    >
+                      {phaseLabel(item.phase)}
+                    </span>
+                  </div>
+                ))}
+              </div>
+            )}
+          </section>
+
+          <section className="rounded-xl border border-[#243044] bg-[#111827] p-5">
+            <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between mb-4">
+              <div>
+                <h2 className="text-base font-semibold text-[#F9FAFB]">Busca RAG</h2>
+                <p className="text-xs text-[#667085] mt-1">Consulta híbrida vetorial + BM25 nos chunks prontos</p>
+              </div>
+              <select
+                value={searchScope}
+                onChange={(e) => setSearchScope(e.target.value)}
+                className="bg-[#0C111D] border border-[#344054] rounded-lg px-3 py-2 text-sm text-[#D0D5DD] focus:border-[#00FFA7] focus:outline-none"
+              >
+                <option value="all">Todas as divisões</option>
+                {divisions.map((division) => (
+                  <option key={division.slug} value={division.slug}>{division.label}</option>
+                ))}
+              </select>
+            </div>
+
+            <div className="flex gap-3">
+              <div className="relative flex-1">
+                <Search size={15} className="absolute left-3 top-1/2 -translate-y-1/2 text-[#667085]" />
+                <input
+                  value={query}
+                  onChange={(e) => setQuery(e.target.value)}
+                  onKeyDown={(e) => e.key === 'Enter' && handleSearch()}
+                  placeholder="Buscar instruções, regras, prazos ou documentos..."
+                  className="w-full bg-[#0C111D] border border-[#344054] rounded-lg pl-9 pr-3 py-2.5 text-sm text-[#F9FAFB] placeholder-[#667085] focus:border-[#00FFA7] focus:outline-none"
+                />
+              </div>
+              <button
+                onClick={handleSearch}
+                disabled={searching || !query.trim()}
+                className="px-4 py-2 rounded-lg bg-[#00FFA7] text-[#0C111D] text-sm font-medium disabled:opacity-50"
+              >
+                {searching ? 'Buscando...' : 'Buscar'}
+              </button>
+            </div>
+
+            {searchResults && (
+              <div className="mt-4 space-y-3">
+                {searchResults.length === 0 ? (
+                  <p className="text-sm text-[#667085] py-4">Nenhum resultado encontrado.</p>
+                ) : (
+                  searchResults.map((hit) => (
+                    <div key={hit.chunk_id} className="rounded-lg border border-[#243044] bg-[#0C111D] p-4">
+                      <div className="flex items-start justify-between gap-3 mb-2">
+                        <div className="min-w-0">
+                          <p className="text-sm font-medium text-[#D0D5DD] truncate">{hit.doc_title || 'Documento'}</p>
+                          <p className="text-xs text-[#667085]">{hit.division_label} {hit.content_type ? `- ${hit.content_type}` : ''}</p>
+                        </div>
+                        {hit.final_score != null && (
+                          <span className="text-xs rounded bg-[#00FFA7]/10 text-[#00FFA7] px-2 py-0.5">
+                            {hit.final_score.toFixed(4)}
+                          </span>
+                        )}
+                      </div>
+                      <p className="text-sm text-[#C7D7EA] whitespace-pre-wrap line-clamp-4">{hit.content}</p>
+                    </div>
+                  ))
+                )}
+              </div>
+            )}
+          </section>
+
+          <section className="rounded-xl border border-[#243044] bg-[#111827] p-5">
+            <div className="flex items-center justify-between mb-4">
+              <div>
+                <h2 className="text-base font-semibold text-[#F9FAFB]">Documentos em {selected?.label}</h2>
+                <p className="text-xs text-[#667085] mt-1">Últimos arquivos enviados para esta divisão</p>
+              </div>
+              {documentsLoading && <Loader2 size={15} className="animate-spin text-[#667085]" />}
+            </div>
+
+            {documents.length === 0 ? (
+              <p className="text-sm text-[#667085] py-4">Nenhum documento nesta divisão.</p>
+            ) : (
+              <div className="overflow-hidden rounded-lg border border-[#243044]">
+                <table className="w-full text-sm">
+                  <thead className="bg-[#0C111D] text-xs text-[#667085]">
+                    <tr>
+                      <th className="text-left px-3 py-2 font-medium">Documento</th>
+                      <th className="text-left px-3 py-2 font-medium">Status</th>
+                      <th className="text-left px-3 py-2 font-medium">Chunks</th>
+                      <th className="text-left px-3 py-2 font-medium">Criado</th>
+                      <th className="w-10 px-3 py-2" />
+                    </tr>
+                  </thead>
+                  <tbody>
+                    {documents.map((doc) => (
+                      <tr key={doc.id} className="border-t border-[#243044]">
+                        <td className="px-3 py-2 text-[#D0D5DD]">{doc.title}</td>
+                        <td className="px-3 py-2">
+                          <span
+                            className="text-xs px-2 py-0.5 rounded-full"
+                            style={{ color: statusColor(doc.status), background: `${statusColor(doc.status)}14`, border: `1px solid ${statusColor(doc.status)}33` }}
+                          >
+                            {phaseLabel(doc.status)}
+                          </span>
+                        </td>
+                        <td className="px-3 py-2 text-[#98A2B3]">{doc.chunks_count ?? 0}</td>
+                        <td className="px-3 py-2 text-[#98A2B3]">{formatDate(doc.created_at)}</td>
+                        <td className="px-3 py-2 text-right">
+                          {canManage && (
+                            <button
+                              onClick={() => handleDelete(doc.id)}
+                              className="p-1.5 rounded text-[#667085] hover:text-red-300 hover:bg-red-500/10"
+                              title="Excluir documento"
+                            >
+                              <Trash2 size={14} />
+                            </button>
+                          )}
+                        </td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+            )}
+          </section>
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/dashboard/frontend/src/pages/Knowledge/Settings.tsx b/dashboard/frontend/src/pages/Knowledge/Settings.tsx
index 582afb85..67fb0790 100644
--- a/dashboard/frontend/src/pages/Knowledge/Settings.tsx
+++ b/dashboard/frontend/src/pages/Knowledge/Settings.tsx
@@ -55,7 +55,7 @@ const EMBEDDER_OPTIONS: Array<{
     value: 'gemini',
     label: 'Google Gemini',
     desc: '768 / 1536 / 3072 dims (MRL) · Requires a Gemini API key · generous free tier',
-    defaultModel: 'gemini-embedding-001',
+    defaultModel: 'gemini-embedding-2',
   },
 ]
 
diff --git a/dashboard/frontend/src/pages/onboarding/restore/RestoreExecute.tsx b/dashboard/frontend/src/pages/onboarding/restore/RestoreExecute.tsx
index f2423563..fcfcf099 100644
--- a/dashboard/frontend/src/pages/onboarding/restore/RestoreExecute.tsx
+++ b/dashboard/frontend/src/pages/onboarding/restore/RestoreExecute.tsx
@@ -73,12 +73,53 @@ export default function RestoreExecute({ snapshot, onComplete, onRetry }: Restor
 
             try {
               const event = JSON.parse(raw) as {
-                type: string
+                type?: string
                 step?: string
                 label?: string
                 status?: string
                 message?: string
                 progress?: number
+                error?: boolean
+              }
+
+              if (!event.type && event.step) {
+                const stepId = event.step
+                setProgress(event.progress ?? 0)
+                if (event.message) setStatusMessage(event.message)
+                setSteps((prev) => {
+                  const status: RestoreStep['status'] = event.error
+                    ? 'error'
+                    : stepId === 'complete'
+                      ? 'done'
+                      : 'running'
+                  const existing = prev.find((s) => s.id === stepId)
+                  if (existing) {
+                    return prev.map((s) =>
+                      s.id === stepId ? { ...s, status, message: event.message } : s
+                    )
+                  }
+                  return [
+                    ...prev,
+                    {
+                      id: stepId,
+                      label: event.label || stepId,
+                      status,
+                      message: event.message,
+                    },
+                  ]
+                })
+
+                if (event.error) {
+                  setFailed(true)
+                  setStatusMessage(event.message || t('restore.execute.failedDefault'))
+                }
+                if (stepId === 'complete') {
+                  setProgress(100)
+                  setDone(true)
+                  setStatusMessage(t('restore.execute.complete'))
+                  setTimeout(() => onComplete(), 2000)
+                }
+                continue
               }
 
               if (event.type === 'step') {
diff --git a/dashboard/frontend/src/pages/onboarding/restore/RestoreSelectRepo.tsx b/dashboard/frontend/src/pages/onboarding/restore/RestoreSelectRepo.tsx
index a7dfa790..4d9b3307 100644
--- a/dashboard/frontend/src/pages/onboarding/restore/RestoreSelectRepo.tsx
+++ b/dashboard/frontend/src/pages/onboarding/restore/RestoreSelectRepo.tsx
@@ -26,6 +26,7 @@ export default function RestoreSelectRepo({ onNext, onBack }: RestoreSelectRepoP
   const [loadingRepos, setLoadingRepos] = useState(false)
   const [selectedRepo, setSelectedRepo] = useState<Repo | null>(null)
   const [error, setError] = useState('')
+  const [advancing, setAdvancing] = useState(false)
 
   const connectToken = async () => {
     if (!token.trim()) {
@@ -60,12 +61,29 @@ export default function RestoreSelectRepo({ onNext, onBack }: RestoreSelectRepoP
     }
   }
 
-  const handleNext = () => {
+  const handleNext = async () => {
     if (!selectedRepo) {
       setError(t('restore.selectRepo.selectRepo'))
       return
     }
-    onNext(selectedRepo.html_url)
+    if (!token.trim()) {
+      setError(t('restore.selectRepo.tokenRequired'))
+      return
+    }
+
+    setError('')
+    setAdvancing(true)
+    try {
+      await api.post('/brain-repo/connect', {
+        token: token.trim(),
+        repo_url: selectedRepo.html_url,
+      })
+      onNext(selectedRepo.html_url)
+    } catch (ex: unknown) {
+      setError(ex instanceof Error ? ex.message : t('restore.selectRepo.failed'))
+    } finally {
+      setAdvancing(false)
+    }
   }
 
   return (
@@ -178,10 +196,10 @@ export default function RestoreSelectRepo({ onNext, onBack }: RestoreSelectRepoP
               </button>
               <button
                 onClick={handleNext}
-                disabled={!selectedRepo}
+                disabled={!selectedRepo || advancing}
                 className="flex-1 py-3 rounded-lg bg-[#00FFA7] text-[#080c14] hover:bg-[#00e69a] text-sm font-semibold transition-colors disabled:opacity-40"
               >
-                {t('restore.next')}
+                {advancing ? <Loader2 size={14} className="animate-spin mx-auto" /> : t('restore.next')}
               </button>
             </div>
           </div>
diff --git a/dashboard/terminal-server/src/claude-bridge.js b/dashboard/terminal-server/src/claude-bridge.js
index f4d53ad0..3b812ee4 100644
--- a/dashboard/terminal-server/src/claude-bridge.js
+++ b/dashboard/terminal-server/src/claude-bridge.js
@@ -6,6 +6,7 @@ const {
   resolveProviderModel,
   getProviderMode,
   getProviderCandidates,
+  isProviderReady,
 } = require('./provider-config');
 
 class ClaudeBridge {
@@ -22,6 +23,31 @@ class ClaudeBridge {
     return loadProviderConfig();
   }
 
+  _selectProviderForCode() {
+    const activeProviderConfig = this._loadProviderConfig();
+    const activeId = activeProviderConfig.provider_id || activeProviderConfig.active;
+    const providerCandidates = getProviderCandidates('code', activeId);
+    const providerConfig = providerCandidates[0] || activeProviderConfig;
+    const providerMode = getProviderMode(providerConfig);
+    const providerModel = resolveProviderModel(providerConfig);
+
+    if (providerConfig.provider_id && providerConfig.provider_id !== activeId) {
+      console.log(`[failover] Selected provider ${providerConfig.provider_id} after ${activeId} was unavailable`);
+    }
+
+    return {
+      providerConfig,
+      providerMode,
+      providerModel,
+      providerFingerprint: [
+        providerConfig.provider_id || providerConfig.active || 'none',
+        providerConfig.cli_command || 'claude',
+        providerMode || 'unknown',
+        providerModel || '',
+      ].join('|'),
+    };
+  }
+
   findClaudeCommand(cliCommand = 'claude') {
     const { execSync } = require('child_process');
 
@@ -76,16 +102,26 @@ class ClaudeBridge {
     if (this.sessions.has(sessionId)) {
       const existing = this.sessions.get(sessionId);
       if (existing.active) {
-        // Idempotent: a duplicate startSession can arrive when the WebSocket
-        // reconnects through a reverse proxy (Traefik) and the frontend
-        // re-sends start_claude before learning the session is still alive.
-        // Returning the existing session instead of throwing prevents a
-        // confusing "Session already exists" toast on the user's terminal
-        // while keeping the original PTY intact.
-        console.log(`[bridge] startSession(${sessionId}) — already active, returning existing session`);
-        return existing;
+        const desiredProvider = this._selectProviderForCode();
+        if (existing.providerFingerprint === desiredProvider.providerFingerprint) {
+          // Idempotent: a duplicate startSession can arrive when the WebSocket
+          // reconnects through a reverse proxy (Traefik) and the frontend
+          // re-sends start_claude before learning the session is still alive.
+          // Returning the existing session instead of throwing prevents a
+          // confusing "Session already exists" toast on the user's terminal
+          // while keeping the original PTY intact.
+          console.log(`[bridge] startSession(${sessionId}) - already active on ${desiredProvider.providerFingerprint}, returning existing session`);
+          return existing;
+        }
+
+        if (existing.providerFingerprint !== desiredProvider.providerFingerprint) {
+          console.log(
+            `[bridge] Provider changed for ${sessionId}: ` +
+            `${existing.providerFingerprint || 'unknown'} -> ${desiredProvider.providerFingerprint}; restarting PTY`
+          );
+        }
       }
-      // Orphaned dead session — clean up and restart
+      // Orphaned dead session or provider change: clean up and restart.
       if (existing.process) {
         try { existing.process.kill('SIGKILL'); } catch (_) {}
       }
@@ -107,15 +143,12 @@ class ClaudeBridge {
       // Reload provider config fresh on every session start
       // so switching provider in the dashboard takes effect immediately.
       // TKR Customization: Use failover provider chain for resilience
-      const activeProviderConfig = this._loadProviderConfig();
-      const providerCandidates = getProviderCandidates('code', activeProviderConfig.provider_id || activeProviderConfig.active);
-      const providerConfig = providerCandidates[0] || activeProviderConfig;
-      const providerMode = getProviderMode(providerConfig);
-      const providerModel = resolveProviderModel(providerConfig);
-
-      if (providerConfig.provider_id && providerConfig.provider_id !== (activeProviderConfig.provider_id || activeProviderConfig.active)) {
-        console.log(`[failover] Selected provider ${providerConfig.provider_id} after ${activeProviderConfig.provider_id || activeProviderConfig.active} was unavailable`);
-      }
+      const {
+        providerConfig,
+        providerMode,
+        providerModel,
+        providerFingerprint,
+      } = this._selectProviderForCode();
 
       // Block session if no provider is active
       if (!providerConfig.active || providerConfig.active === 'none') {
@@ -124,6 +157,11 @@ class ClaudeBridge {
         if (onExit) onExit(1, null);
         return;
       }
+      if (!isProviderReady(providerConfig)) {
+        throw new Error(
+          `Provider "${providerConfig.active}" nao esta configurado. Configure API key/OAuth em Providers antes de abrir o Terminal.`
+        );
+      }
       if (providerConfig.active !== 'anthropic' && providerMode !== 'code') {
         throw new Error(
           `Provider "${providerConfig.active}" com modelo "${providerModel || 'não definido'}" está em modo Chat Completion/Memory Output. Use o Chat para esse modelo. O Terminal aceita apenas modelos Code.`
@@ -234,7 +272,13 @@ class ClaudeBridge {
         workingDir,
         created: new Date(),
         active: true,
-        killTimeout: null
+        killTimeout: null,
+        provider_id: providerConfig.provider_id || providerConfig.active,
+        provider_name: providerConfig.provider_name || providerConfig.active,
+        provider_cli: providerConfig.cli_command,
+        provider_model: providerModel || null,
+        provider_mode: providerMode,
+        providerFingerprint
       };
 
       this.sessions.set(sessionId, session);
@@ -373,6 +417,36 @@ class ClaudeBridge {
     }));
   }
 
+  /**
+   * Invalidate all active sessions — used when the active provider changes.
+   * Kills every PTY process so the next session start uses the new provider's CLI.
+   * Returns the list of session IDs that were invalidated.
+   */
+  async invalidateAllSessions(reason = 'provider_changed') {
+    const invalidated = [];
+    for (const [sessionId, session] of this.sessions.entries()) {
+      if (session.active) {
+        console.log(`[bridge] Invalidating session ${sessionId} (reason: ${reason})`);
+        invalidated.push(sessionId);
+        try {
+          if (session.process) {
+            session.process.kill('SIGTERM');
+            setTimeout(() => {
+              try {
+                if (session.active && session.process) {
+                  session.process.kill('SIGKILL');
+                }
+              } catch {}
+            }, 2000);
+          }
+        } catch (err) {
+          console.warn(`[bridge] Error killing session ${sessionId}:`, err.message);
+        }
+      }
+    }
+    return invalidated;
+  }
+
   async cleanup() {
     const sessionIds = Array.from(this.sessions.keys());
     for (const sessionId of sessionIds) {
diff --git a/dashboard/terminal-server/src/http-routes.js b/dashboard/terminal-server/src/http-routes.js
index 44956d6a..d75db2cd 100644
--- a/dashboard/terminal-server/src/http-routes.js
+++ b/dashboard/terminal-server/src/http-routes.js
@@ -269,6 +269,70 @@ function registerTerminalHttpRoutes(app, server) {
     }
     res.json({ notifications });
   });
+
+  // ── Provider change notification ───────────────────────────
+  // Called by the Flask backend when the user switches the active provider.
+  // Triggers immediate invalidation of all PTY sessions.
+  app.post('/api/provider-changed', async (req, res) => {
+    const { new_provider, old_provider } = req.body || {};
+    console.log(`[http] POST /api/provider-changed: ${old_provider} -> ${new_provider}`);
+
+    try {
+      // Invalidate all active PTY sessions
+      const invalidated = await server.claudeBridge.invalidateAllSessions('provider_changed_api');
+
+      // Mark tracked sessions as inactive
+      for (const [sessionId, session] of server.claudeSessions.entries()) {
+        if (session.active && session.agent === 'claude') {
+          session.active = false;
+          session.agent = null;
+          session.lastActivity = new Date();
+        }
+      }
+
+      await server.saveSessionsToDisk();
+
+      // Broadcast to all WebSocket clients
+      const payload = {
+        type: 'provider_changed',
+        newProvider: new_provider,
+        oldProvider: old_provider,
+        invalidatedSessions: invalidated,
+        message: `Provedor alterado para ${new_provider}. ${invalidated.length} sessao(oes) reiniciada(s).`,
+      };
+      for (const [wsId, wsInfo] of server.webSocketConnections.entries()) {
+        if (wsInfo.ws && wsInfo.ws.readyState === 1) {
+          server.sendToWebSocket(wsInfo.ws, payload);
+        }
+      }
+
+      res.json({
+        success: true,
+        invalidated_sessions: invalidated.length,
+        new_provider,
+      });
+    } catch (err) {
+      console.error('[http] Error handling provider-changed:', err);
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // Current active provider info
+  app.get('/api/provider/active', (req, res) => {
+    try {
+      const { loadProviderConfig, getProviderMode } = require('./provider-config');
+      const config = loadProviderConfig();
+      res.json({
+        active: config.active,
+        provider_id: config.provider_id,
+        cli_command: config.cli_command,
+        mode: getProviderMode(config),
+        provider_name: config.provider_name,
+      });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
 }
 
 module.exports = {
diff --git a/dashboard/terminal-server/src/provider-config.js b/dashboard/terminal-server/src/provider-config.js
index 1445d4c7..7a97c5c6 100644
--- a/dashboard/terminal-server/src/provider-config.js
+++ b/dashboard/terminal-server/src/provider-config.js
@@ -2,8 +2,12 @@ const fs = require('fs');
 const path = require('path');
 
 const WORKSPACE_ROOT = path.resolve(__dirname, '..', '..', '..');
-const PROVIDERS_PATH = path.join(WORKSPACE_ROOT, 'config', 'providers.json');
-const CODEX_AUTH_FILE = path.join(WORKSPACE_ROOT, 'config', 'codex-auth.json');
+const PROVIDERS_PATH = process.env.EVO_NEXUS_PROVIDERS_PATH ||
+  path.join(WORKSPACE_ROOT, 'config', 'providers.json');
+const CODEX_AUTH_FILE = path.join(
+  process.env.CODEX_HOME || path.join(process.env.HOME || '/', '.codex'),
+  'auth.json',
+);
 
 const ALLOWED_CLI = new Set(['claude', 'openclaude']);
 const ALLOWED_ENV_VARS = new Set([
@@ -27,8 +31,8 @@ const ALLOWED_ENV_VARS = new Set([
 
 // ---- TKR Customization: Failover routing support ----
 const DEFAULT_FAILOVER_ORDER = [
-  'anthropic',
   'openrouter',
+  'anthropic',
   'openai',
   'codex_auth',
   'gemini',
@@ -36,6 +40,12 @@ const DEFAULT_FAILOVER_ORDER = [
   'vertex',
 ];
 
+const PROVIDER_DEFAULT_ENV = {
+  openrouter: {
+    OPENAI_BASE_URL: 'https://openrouter.ai/api/v1',
+  },
+};
+
 function _normalizeModel(model) {
   return (model || '').trim().toLowerCase();
 }
@@ -43,17 +53,17 @@ function _normalizeModel(model) {
 function loadProvidersFile() {
   try {
     if (!fs.existsSync(PROVIDERS_PATH)) {
-      return { active_provider: 'anthropic', providers: {} };
+      return { active_provider: 'openrouter', providers: {} };
     }
     return JSON.parse(fs.readFileSync(PROVIDERS_PATH, 'utf8'));
   } catch {
-    return { active_provider: 'anthropic', providers: {} };
+    return { active_provider: 'openrouter', providers: {} };
   }
 }
 
 function getProviderRouting(config, activeProviderId = null) {
   const providers = config?.providers || {};
-  const active = activeProviderId || config?.active_provider || 'anthropic';
+  const active = activeProviderId || config?.active_provider || 'openrouter';
   const routing = config?.routing && typeof config.routing === 'object' ? config.routing : {};
   const seen = new Set();
   const ordered = [];
@@ -80,18 +90,31 @@ function getProviderRouting(config, activeProviderId = null) {
 }
 
 function buildProviderConfig(config, providerId) {
-  const active = providerId || config?.active_provider || 'anthropic';
+  const active = providerId || config?.active_provider || 'openrouter';
   const provider = config?.providers?.[active] || {};
 
   let cliCommand = provider.cli_command || 'claude';
   if (!ALLOWED_CLI.has(cliCommand)) cliCommand = 'claude';
 
+  const rawEnvVars = provider.env_vars || {};
   const envVars = Object.fromEntries(
-    Object.entries(provider.env_vars || {}).filter(
+    Object.entries(rawEnvVars).filter(
       ([k, v]) => v !== '' && ALLOWED_ENV_VARS.has(k)
     )
   );
 
+  const providerDefaults = PROVIDER_DEFAULT_ENV[active] || {};
+  if ('OPENAI_BASE_URL' in rawEnvVars && !envVars.OPENAI_BASE_URL) {
+    const defaultBaseUrl = provider.default_base_url || providerDefaults.OPENAI_BASE_URL;
+    if (defaultBaseUrl) envVars.OPENAI_BASE_URL = defaultBaseUrl;
+  }
+  if ('OPENAI_MODEL' in rawEnvVars && !envVars.OPENAI_MODEL && provider.default_model) {
+    envVars.OPENAI_MODEL = provider.default_model;
+  }
+  if ('GEMINI_MODEL' in rawEnvVars && !envVars.GEMINI_MODEL && provider.default_model) {
+    envVars.GEMINI_MODEL = provider.default_model;
+  }
+
   if (active === 'codex_auth' && 'OPENAI_API_KEY' in envVars) {
     delete envVars.OPENAI_API_KEY;
   }
@@ -111,7 +134,8 @@ function isProviderReady(providerConfig) {
   if (!providerConfig || providerConfig.active === 'none') return false;
   if (providerConfig.active === 'anthropic') return true;
   if (providerConfig.active === 'codex_auth') {
-    return fs.existsSync(CODEX_AUTH_FILE);
+    const explicitAuthPath = providerConfig.env_vars?.CODEX_AUTH_JSON_PATH;
+    return fs.existsSync(explicitAuthPath || CODEX_AUTH_FILE);
   }
 
   const env = providerConfig.env_vars || {};
@@ -128,20 +152,34 @@ function supportsMode(providerConfig, mode) {
   }
   if (mode === 'code') {
     if (providerConfig.active === 'anthropic') return true;
-    return getProviderMode(providerConfig) === 'code';
+    return providerConfig.cli_command === 'openclaude' && getProviderMode(providerConfig) === 'code';
   }
   return true;
 }
 
 function resolveProviderChain(mode = 'chat', preferredProviderId = null) {
   const config = loadProvidersFile();
-  const routing = getProviderRouting(config, preferredProviderId || config.active_provider);
+  const preferred = preferredProviderId || config.active_provider;
+  const routing = getProviderRouting(config, preferred);
   const providers = config.providers || {};
-  return routing.failover_order
+  const chain = routing.failover_order
     .map((providerId) => buildProviderConfig(config, providerId))
     .filter((providerConfig) => providers[providerConfig.provider_id])
     .filter((providerConfig) => supportsMode(providerConfig, mode))
     .filter((providerConfig) => isProviderReady(providerConfig));
+
+  if (mode === 'code' && preferred && preferred !== 'anthropic') {
+    const openClaudeChain = chain.filter(
+      (providerConfig) =>
+        providerConfig.provider_id === preferred ||
+        providerConfig.cli_command === 'openclaude'
+    );
+    return openClaudeChain.length > 0 ? openClaudeChain : chain.filter(
+      (providerConfig) => providerConfig.provider_id === preferred
+    );
+  }
+
+  return chain;
 }
 
 function getProviderCandidates(mode = 'chat', preferredProviderId = null) {
@@ -155,14 +193,21 @@ function isCodeModel(model) {
   if (m === 'codexplan' || m === 'codexspark') return true;
   if (m.includes('memory-output') || m.includes('memory_output')) return false;
   if (m.includes('coder') || m.includes('codex') || m.includes('devstral')) return true;
+  if (m.includes('claude') || m.includes('sonnet') || m.includes('opus') || m.includes('haiku')) return true;
+  if (m.includes('gpt-5') || m.includes('gpt-4') || m.includes('gpt-4o') || m.includes('gpt-4.1')) return true;
+  if (/^o[134]($|[/:._-])/.test(m)) return true;
+  if (m.includes('gemini-2.5') || m.includes('qwen3-coder') || m.includes('deepseek') || m.includes('kimi-k2')) return true;
+  if (m.includes('glm-4.5')) return true;
   return /(^|[/:._-])code([/:._-]|$)/i.test(m);
 }
 
 function isChatCompletionModel(model) {
   const m = _normalizeModel(model);
-  if (!m) return true;
+  if (!m) return false;
   if (m.includes('memory-output') || m.includes('memory_output')) return true;
-  return !isCodeModel(m);
+  return ['embedding', 'moderation', 'whisper', 'tts', 'dall-e', 'image', 'audio', 'rerank'].some(
+    (token) => m.includes(token)
+  );
 }
 
 function resolveProviderModel(providerConfig) {
@@ -182,27 +227,72 @@ function getProviderMode(providerConfig) {
   const active = providerConfig?.active || 'anthropic';
   if (active === 'anthropic') return 'anthropic';
   const model = resolveProviderModel(providerConfig);
+  if (isChatCompletionModel(model)) return 'chat';
   if (isCodeModel(model)) return 'code';
-  return 'chat';
+  return providerConfig?.cli_command === 'openclaude' ? 'code' : 'chat';
 }
 
 function loadProviderConfig(providerId = null) {
   const config = loadProvidersFile();
   try {
-    return buildProviderConfig(config, providerId || config.active_provider || 'anthropic');
+    return buildProviderConfig(config, providerId || config.active_provider || 'openrouter');
   } catch {
     return {
-      provider_id: providerId || 'anthropic',
-      cli_command: 'claude',
+      provider_id: providerId || 'openrouter',
+      cli_command: 'openclaude',
       env_vars: {},
-      active: providerId || 'anthropic',
-      provider_name: providerId || 'anthropic',
-      routing: { enabled: true, failover_order: [providerId || 'anthropic'] },
+      active: providerId || 'openrouter',
+      provider_name: providerId || 'openrouter',
+      routing: { enabled: true, failover_order: [providerId || 'openrouter'] },
       provider: {},
     };
   }
 }
 
+/**
+ * Watch providers.json for active_provider changes.
+ * Calls onChange(newActiveProvider, oldActiveProvider) when the provider switches.
+ * Returns a stop() function to cancel watching.
+ */
+function watchProviderChanges(onChange) {
+  let lastKnownProvider = null;
+  try {
+    const config = loadProvidersFile();
+    lastKnownProvider = config.active_provider || 'openrouter';
+  } catch {
+    lastKnownProvider = 'openrouter';
+  }
+
+  const POLL_INTERVAL_MS = 2000;
+  const interval = setInterval(() => {
+    try {
+      const config = loadProvidersFile();
+      const currentProvider = config.active_provider || 'openrouter';
+      if (currentProvider !== lastKnownProvider) {
+        const oldProvider = lastKnownProvider;
+        lastKnownProvider = currentProvider;
+        console.log(`[provider-watcher] Provider changed: ${oldProvider} -> ${currentProvider}`);
+        if (onChange) onChange(currentProvider, oldProvider);
+      }
+    } catch (err) {
+      // Ignore transient read errors (file being written)
+    }
+  }, POLL_INTERVAL_MS);
+
+  if (typeof interval.unref === 'function') {
+    interval.unref();
+  }
+
+  return {
+    stop() {
+      clearInterval(interval);
+    },
+    getCurrentProvider() {
+      return lastKnownProvider;
+    },
+  };
+}
+
 module.exports = {
   loadProviderConfig,
   loadProvidersFile,
@@ -210,6 +300,8 @@ module.exports = {
   getProviderCandidates,
   resolveProviderModel,
   getProviderMode,
+  isProviderReady,
   isCodeModel,
   isChatCompletionModel,
+  watchProviderChanges,
 };
diff --git a/dashboard/terminal-server/src/terminal-server-runtime.js b/dashboard/terminal-server/src/terminal-server-runtime.js
index 51446a53..bcef4305 100644
--- a/dashboard/terminal-server/src/terminal-server-runtime.js
+++ b/dashboard/terminal-server/src/terminal-server-runtime.js
@@ -13,7 +13,7 @@ const SessionStore = require('./utils/session-store');
 const ChatLogger = require('./utils/chat-logger');
 const TerminalAuditLog = require('./utils/terminal-audit-log');
 const { createPlatformEventBroker } = require('./platform-event-broker');
-const { loadProviderConfig, getProviderMode } = require('./provider-config');
+const { loadProviderConfig, getProviderMode, watchProviderChanges } = require('./provider-config');
 
 class TerminalServer {
   constructor(options = {}) {
@@ -59,10 +59,13 @@ class TerminalServer {
     };
     this.ready = this.loadPersistedSessions();
 
+    this.providerWatcher = null;
+
     this.setupExpress();
     this.setupAutoSave();
     this.setupSessionGc();
     this.setupHeartbeatMonitor();
+    this.setupProviderWatcher();
   }
 
   async loadPersistedSessions() {
@@ -109,6 +112,59 @@ class TerminalServer {
     }, this.wsHeartbeatSweepIntervalMs);
   }
 
+  /**
+   * Watch providers.json for active_provider changes.
+   * When the provider switches, invalidate all PTY sessions and
+   * broadcast a provider_changed event to all connected WebSocket clients.
+   */
+  setupProviderWatcher() {
+    this.providerWatcher = watchProviderChanges(async (newProvider, oldProvider) => {
+      console.log(`[provider-watcher] Active provider changed: ${oldProvider} -> ${newProvider}`);
+
+      // 1. Invalidate all active PTY sessions (terminal mode)
+      const invalidatedPty = await this.claudeBridge.invalidateAllSessions('provider_changed');
+
+      // 2. Mark all tracked sessions as inactive
+      for (const [sessionId, session] of this.claudeSessions.entries()) {
+        if (session.active && session.agent === 'claude') {
+          session.active = false;
+          session.agent = null;
+          session.lastActivity = new Date();
+        }
+      }
+
+      // 3. Save updated session state
+      await this.saveSessionsToDisk();
+
+      // 4. Broadcast provider_changed to ALL connected WebSocket clients
+      const payload = {
+        type: 'provider_changed',
+        newProvider,
+        oldProvider,
+        invalidatedSessions: invalidatedPty,
+        message: `Provedor alterado para ${newProvider}. ${invalidatedPty.length} sessao(oes) reiniciada(s).`,
+      };
+
+      for (const [wsId, wsInfo] of this.webSocketConnections.entries()) {
+        if (wsInfo.ws && wsInfo.ws.readyState === 1) {
+          this.sendToWebSocket(wsInfo.ws, payload);
+        }
+      }
+
+      // 5. Also broadcast as global notification
+      this.broadcastToGlobalSubscribers({
+        type: 'notification',
+        id: `provider_changed-${Date.now()}`,
+        event: 'provider_changed',
+        newProvider,
+        oldProvider,
+        createdAt: Date.now(),
+      });
+
+      console.log(`[provider-watcher] Invalidated ${invalidatedPty.length} PTY sessions, notified ${this.webSocketConnections.size} clients`);
+    });
+  }
+
   async saveSessionsToDisk() {
     if (this._sessionSaveTimer) {
       clearTimeout(this._sessionSaveTimer);
@@ -376,6 +432,7 @@ class TerminalServer {
     if (this.sessionGcInterval) clearInterval(this.sessionGcInterval);
     if (this.wsHeartbeatInterval) clearInterval(this.wsHeartbeatInterval);
     if (this.platformEventBroker) this.platformEventBroker.stop();
+    if (this.providerWatcher) this.providerWatcher.stop();
     this.close();
     process.exit(0);
   }
@@ -1005,6 +1062,7 @@ class TerminalServer {
     if (this.sessionGcInterval) clearInterval(this.sessionGcInterval);
     if (this.wsHeartbeatInterval) clearInterval(this.wsHeartbeatInterval);
     if (this.platformEventBroker) this.platformEventBroker.stop();
+    if (this.providerWatcher) this.providerWatcher.stop();
     if (this.wss) this.wss.close();
     if (this.server) this.server.close();
 
diff --git a/dashboard/terminal-server/test/provider-config.test.js b/dashboard/terminal-server/test/provider-config.test.js
index cbe17213..68460481 100644
--- a/dashboard/terminal-server/test/provider-config.test.js
+++ b/dashboard/terminal-server/test/provider-config.test.js
@@ -1,9 +1,18 @@
 const assert = require('node:assert/strict');
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const test = require('node:test');
 
-const CONFIG_PATH = path.resolve(__dirname, '..', '..', '..', 'config', 'providers.json');
+const CONFIG_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'evo-provider-config-'));
+const CONFIG_PATH = path.join(CONFIG_DIR, 'providers.json');
+process.env.EVO_NEXUS_PROVIDERS_PATH = CONFIG_PATH;
+
+function loadProviderConfigModule() {
+  const modulePath = require.resolve('../src/provider-config');
+  delete require.cache[modulePath];
+  return require(modulePath);
+}
 
 function withProviderConfig(config, fn) {
   const hadOriginal = fs.existsSync(CONFIG_PATH);
@@ -38,9 +47,11 @@ test('provider config resolves routing and ready chat candidates', () => {
       openrouter: {
         name: 'OpenRouter',
         cli_command: 'openclaude',
-        default_model: 'gpt-4.1',
+        default_base_url: 'https://openrouter.ai/api/v1',
+        default_model: 'anthropic/claude-sonnet-4',
         env_vars: {
           CLAUDE_CODE_USE_OPENAI: '1',
+          OPENAI_BASE_URL: '',
           OPENAI_API_KEY: 'sk-test',
           OPENAI_MODEL: '',
         },
@@ -65,7 +76,7 @@ test('provider config resolves routing and ready chat candidates', () => {
       loadProviderConfig,
       resolveProviderChain,
       resolveProviderModel,
-    } = require('../src/provider-config');
+    } = loadProviderConfigModule();
 
     const active = loadProviderConfig();
     assert.equal(active.provider_id, 'anthropic');
@@ -73,13 +84,50 @@ test('provider config resolves routing and ready chat candidates', () => {
     assert.deepEqual(active.routing.failover_order[0], 'anthropic');
 
     const openrouter = loadProviderConfig('openrouter');
-    assert.equal(resolveProviderModel(openrouter), 'gpt-4.1');
-    assert.equal(getProviderMode(openrouter), 'chat');
+    assert.equal(resolveProviderModel(openrouter), 'anthropic/claude-sonnet-4');
+    assert.equal(openrouter.env_vars.OPENAI_BASE_URL, 'https://openrouter.ai/api/v1');
+    assert.equal(openrouter.env_vars.OPENAI_MODEL, 'anthropic/claude-sonnet-4');
+    assert.equal(getProviderMode(openrouter), 'code');
 
     const chain = resolveProviderChain('code', 'openrouter');
-    assert.equal(chain[0].provider_id, 'anthropic');
+    assert.equal(chain[0].provider_id, 'openrouter');
 
     const candidates = getProviderCandidates('chat', 'anthropic');
     assert.deepEqual(candidates.map((candidate) => candidate.provider_id), ['openrouter']);
   });
 });
+
+test('non-anthropic code routing does not silently fall back to native claude', () => {
+  const config = {
+    active_provider: 'openrouter',
+    routing: {
+      enabled: true,
+      failover_order: ['openrouter', 'anthropic'],
+    },
+    providers: {
+      anthropic: {
+        name: 'Anthropic',
+        cli_command: 'claude',
+        env_vars: {},
+      },
+      openrouter: {
+        name: 'OpenRouter',
+        cli_command: 'openclaude',
+        default_base_url: 'https://openrouter.ai/api/v1',
+        default_model: 'anthropic/claude-sonnet-4',
+        env_vars: {
+          CLAUDE_CODE_USE_OPENAI: '1',
+          OPENAI_BASE_URL: '',
+          OPENAI_API_KEY: '',
+          OPENAI_MODEL: '',
+        },
+      },
+    },
+  };
+
+  withProviderConfig(config, () => {
+    const { resolveProviderChain } = loadProviderConfigModule();
+    const chain = resolveProviderChain('code', 'openrouter');
+    assert.deepEqual(chain.map((candidate) => candidate.provider_id), []);
+  });
+});
diff --git a/pyproject.toml b/pyproject.toml
index 17da8867..e140ce8a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -31,6 +31,7 @@ dependencies = [
     "sqlparse>=0.4,<1.0",
     "jsonschema>=4.21",
     "flask-limiter>=3.5",
+    "websocket-client>=1.8",
 ]
 
 [project.scripts]
diff --git a/uv.lock b/uv.lock
index 69360e19..bd921fa6 100644
--- a/uv.lock
+++ b/uv.lock
@@ -560,6 +560,18 @@ nvtx = [
     { name = "nvidia-nvtx", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
 ]
 
+[[package]]
+name = "deprecated"
+version = "1.3.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "wrapt" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/49/85/12f0a49a7c4ffb70572b6c2ef13c90c88fd190debda93b23f026b25f9634/deprecated-1.3.1.tar.gz", hash = "sha256:b1b50e0ff0c1fddaa5708a2c6b0a6588bb09b892825ab2b214ac9ea9d92a5223", size = 2932523, upload-time = "2025-10-30T08:19:02.757Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/84/d0/205d54408c08b13550c733c4b85429e7ead111c7f0014309637425520a9a/deprecated-1.3.1-py2.py3-none-any.whl", hash = "sha256:597bfef186b6f60181535a29fbe44865ce137a5079f295b479886c82729d5f3f", size = 11298, upload-time = "2025-10-30T08:19:00.758Z" },
+]
+
 [[package]]
 name = "distlib"
 version = "0.4.0"
@@ -589,7 +601,7 @@ wheels = [
 
 [[package]]
 name = "evo-nexus"
-version = "0.32.2"
+version = "0.33.0"
 source = { virtual = "." }
 dependencies = [
     { name = "alembic" },
@@ -599,6 +611,7 @@ dependencies = [
     { name = "cryptography" },
     { name = "flask" },
     { name = "flask-cors" },
+    { name = "flask-limiter" },
     { name = "flask-login" },
     { name = "flask-sock" },
     { name = "flask-sqlalchemy" },
@@ -618,6 +631,7 @@ dependencies = [
     { name = "sqlparse" },
     { name = "tiktoken" },
     { name = "watchdog" },
+    { name = "websocket-client" },
 ]
 
 [package.dev-dependencies]
@@ -634,6 +648,7 @@ requires-dist = [
     { name = "cryptography", specifier = ">=42" },
     { name = "flask", specifier = ">=3.0" },
     { name = "flask-cors", specifier = ">=4.0" },
+    { name = "flask-limiter", specifier = ">=3.5" },
     { name = "flask-login", specifier = ">=0.6" },
     { name = "flask-sock", specifier = ">=0.7" },
     { name = "flask-sqlalchemy", specifier = ">=3.1" },
@@ -653,6 +668,7 @@ requires-dist = [
     { name = "sqlparse", specifier = ">=0.4,<1.0" },
     { name = "tiktoken", specifier = ">=0.7" },
     { name = "watchdog", specifier = ">=4.0" },
+    { name = "websocket-client", specifier = ">=1.8" },
 ]
 
 [package.metadata.requires-dev]
@@ -718,6 +734,21 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/4f/af/72ad54402e599152de6d067324c46fe6a4f531c7c65baf7e96c63db55eaf/flask_cors-6.0.2-py3-none-any.whl", hash = "sha256:e57544d415dfd7da89a9564e1e3a9e515042df76e12130641ca6f3f2f03b699a", size = 13257, upload-time = "2025-12-12T20:31:41.3Z" },
 ]
 
+[[package]]
+name = "flask-limiter"
+version = "4.1.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "flask" },
+    { name = "limits" },
+    { name = "ordered-set" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/4e/98/71780be5d1afb941219c4b48d241d4e246e3062b017caa4e79c4dc71314c/flask_limiter-4.1.1.tar.gz", hash = "sha256:ca11608fc7eec43dcea606964ca07c3bd4ec1ae89043a0f67f717899a4f48106", size = 403198, upload-time = "2025-12-06T17:39:00.575Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/75/7c/9fe9ffc83be199011bb0c6deb82cdcbc5a355601e380581de9dbc30490dd/flask_limiter-4.1.1-py3-none-any.whl", hash = "sha256:e1ae13e06e6b3e39a4902e7d240b901586b25932c2add7bd5f5eeb4bdc11111b", size = 30554, upload-time = "2025-12-06T17:38:59.162Z" },
+]
+
 [[package]]
 name = "flask-login"
 version = "0.6.3"
@@ -1155,6 +1186,20 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/41/45/1a4ed80516f02155c51f51e8cedb3c1902296743db0bbc66608a0db2814f/jsonschema_specifications-2025.9.1-py3-none-any.whl", hash = "sha256:98802fee3a11ee76ecaca44429fda8a41bff98b00a0f2838151b113f210cc6fe", size = 18437, upload-time = "2025-09-08T01:34:57.871Z" },
 ]
 
+[[package]]
+name = "limits"
+version = "5.8.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "deprecated" },
+    { name = "packaging" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/71/69/826a5d1f45426c68d8f6539f8d275c0e4fcaa57f0c017ec3100986558a41/limits-5.8.0.tar.gz", hash = "sha256:c9e0d74aed837e8f6f50d1fcebcf5fd8130957287206bc3799adaee5092655da", size = 226104, upload-time = "2026-02-05T07:17:35.859Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b9/98/cb5ca20618d205a09d5bec7591fbc4130369c7e6308d9a676a28ff3ab22c/limits-5.8.0-py3-none-any.whl", hash = "sha256:ae1b008a43eb43073c3c579398bd4eb4c795de60952532dc24720ab45e1ac6b8", size = 60954, upload-time = "2026-02-05T07:17:34.425Z" },
+]
+
 [[package]]
 name = "mako"
 version = "1.3.11"
@@ -1723,6 +1768,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/86/8a/69176a64335aed183529207ba8bc3d329c2999d852b4f3818027203f50e6/opencv_python_headless-4.11.0.86-cp37-abi3-win_amd64.whl", hash = "sha256:6c304df9caa7a6a5710b91709dd4786bf20a74d57672b3c31f7033cc638174ca", size = 39402386, upload-time = "2025-01-16T13:52:56.418Z" },
 ]
 
+[[package]]
+name = "ordered-set"
+version = "4.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/4c/ca/bfac8bc689799bcca4157e0e0ced07e70ce125193fc2e166d2e685b7e2fe/ordered-set-4.1.0.tar.gz", hash = "sha256:694a8e44c87657c59292ede72891eb91d34131f6531463aab3009191c77364a8", size = 12826, upload-time = "2022-01-26T14:38:56.6Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/33/55/af02708f230eb77084a299d7b08175cff006dea4f2721074b92cdb0296c0/ordered_set-4.1.0-py3-none-any.whl", hash = "sha256:046e1132c71fcf3330438a539928932caf51ddbc582496833e23de611de14562", size = 7634, upload-time = "2022-01-26T14:38:48.677Z" },
+]
+
 [[package]]
 name = "packaging"
 version = "26.0"
@@ -3400,6 +3454,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/68/5a/199c59e0a824a3db2b89c5d2dade7ab5f9624dbf6448dc291b46d5ec94d3/wcwidth-0.6.0-py3-none-any.whl", hash = "sha256:1a3a1e510b553315f8e146c54764f4fb6264ffad731b3d78088cdb1478ffbdad", size = 94189, upload-time = "2026-02-06T19:19:39.646Z" },
 ]
 
+[[package]]
+name = "websocket-client"
+version = "1.9.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/2c/41/aa4bf9664e4cda14c3b39865b12251e8e7d239f4cd0e3cc1b6c2ccde25c1/websocket_client-1.9.0.tar.gz", hash = "sha256:9e813624b6eb619999a97dc7958469217c3176312b3a16a4bd1bc7e08a46ec98", size = 70576, upload-time = "2025-10-07T21:16:36.495Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/34/db/b10e48aa8fff7407e67470363eac595018441cf32d5e1001567a7aeba5d2/websocket_client-1.9.0-py3-none-any.whl", hash = "sha256:af248a825037ef591efbf6ed20cc5faa03d3b47b9e5a2230a529eeee1c1fc3ef", size = 82616, upload-time = "2025-10-07T21:16:34.951Z" },
+]
+
 [[package]]
 name = "websockets"
 version = "16.0"
@@ -3480,6 +3543,92 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/93/8c/2e650f2afeb7ee576912636c23ddb621c91ac6a98e66dc8d29c3c69446e1/werkzeug-3.1.8-py3-none-any.whl", hash = "sha256:63a77fb8892bf28ebc3178683445222aa500e48ebad5ec77b0ad80f8726b1f50", size = 226459, upload-time = "2026-04-02T18:49:12.72Z" },
 ]
 
+[[package]]
+name = "wrapt"
+version = "2.1.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/2e/64/925f213fdcbb9baeb1530449ac71a4d57fc361c053d06bf78d0c5c7cd80c/wrapt-2.1.2.tar.gz", hash = "sha256:3996a67eecc2c68fd47b4e3c564405a5777367adfd9b8abb58387b63ee83b21e", size = 81678, upload-time = "2026-03-06T02:53:25.134Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/da/d2/387594fb592d027366645f3d7cc9b4d7ca7be93845fbaba6d835a912ef3c/wrapt-2.1.2-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:4b7a86d99a14f76facb269dc148590c01aaf47584071809a70da30555228158c", size = 60669, upload-time = "2026-03-06T02:52:40.671Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/18/3f373935bc5509e7ac444c8026a56762e50c1183e7061797437ca96c12ce/wrapt-2.1.2-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:a819e39017f95bf7aede768f75915635aa8f671f2993c036991b8d3bfe8dbb6f", size = 61603, upload-time = "2026-03-06T02:54:21.032Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/7a/32758ca2853b07a887a4574b74e28843919103194bb47001a304e24af62f/wrapt-2.1.2-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:5681123e60aed0e64c7d44f72bbf8b4ce45f79d81467e2c4c728629f5baf06eb", size = 113632, upload-time = "2026-03-06T02:53:54.121Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/d5/eeaa38f670d462e97d978b3b0d9ce06d5b91e54bebac6fbed867809216e7/wrapt-2.1.2-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2b8b28e97a44d21836259739ae76284e180b18abbb4dcfdff07a415cf1016c3e", size = 115644, upload-time = "2026-03-06T02:54:53.33Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/09/2a41506cb17affb0bdf9d5e2129c8c19e192b388c4c01d05e1b14db23c00/wrapt-2.1.2-cp310-cp310-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:cef91c95a50596fcdc31397eb6955476f82ae8a3f5a8eabdc13611b60ee380ba", size = 112016, upload-time = "2026-03-06T02:54:43.274Z" },
+    { url = "https://files.pythonhosted.org/packages/64/15/0e6c3f5e87caadc43db279724ee36979246d5194fa32fed489c73643ba59/wrapt-2.1.2-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:dad63212b168de8569b1c512f4eac4b57f2c6934b30df32d6ee9534a79f1493f", size = 114823, upload-time = "2026-03-06T02:54:29.392Z" },
+    { url = "https://files.pythonhosted.org/packages/56/b2/0ad17c8248f4e57bedf44938c26ec3ee194715f812d2dbbd9d7ff4be6c06/wrapt-2.1.2-cp310-cp310-musllinux_1_2_riscv64.whl", hash = "sha256:d307aa6888d5efab2c1cde09843d48c843990be13069003184b67d426d145394", size = 111244, upload-time = "2026-03-06T02:54:02.149Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/04/bcdba98c26f2c6522c7c09a726d5d9229120163493620205b2f76bd13c01/wrapt-2.1.2-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:c87cf3f0c85e27b3ac7d9ad95da166bf8739ca215a8b171e8404a2d739897a45", size = 113307, upload-time = "2026-03-06T02:54:12.428Z" },
+    { url = "https://files.pythonhosted.org/packages/0e/1b/5e2883c6bc14143924e465a6fc5a92d09eeabe35310842a481fb0581f832/wrapt-2.1.2-cp310-cp310-win32.whl", hash = "sha256:d1c5fea4f9fe3762e2b905fdd67df51e4be7a73b7674957af2d2ade71a5c075d", size = 57986, upload-time = "2026-03-06T02:54:26.823Z" },
+    { url = "https://files.pythonhosted.org/packages/42/5a/4efc997bccadd3af5749c250b49412793bc41e13a83a486b2b54a33e240c/wrapt-2.1.2-cp310-cp310-win_amd64.whl", hash = "sha256:d8f7740e1af13dff2684e4d56fe604a7e04d6c94e737a60568d8d4238b9a0c71", size = 60336, upload-time = "2026-03-06T02:54:18Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/f5/a2bb833e20181b937e87c242645ed5d5aa9c373006b0467bfe1a35c727d0/wrapt-2.1.2-cp310-cp310-win_arm64.whl", hash = "sha256:1c6cc827c00dc839350155f316f1f8b4b0c370f52b6a19e782e2bda89600c7dc", size = 58757, upload-time = "2026-03-06T02:53:51.545Z" },
+    { url = "https://files.pythonhosted.org/packages/c7/81/60c4471fce95afa5922ca09b88a25f03c93343f759aae0f31fb4412a85c7/wrapt-2.1.2-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:96159a0ee2b0277d44201c3b5be479a9979cf154e8c82fa5df49586a8e7679bb", size = 60666, upload-time = "2026-03-06T02:52:58.934Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/be/80e80e39e7cb90b006a0eaf11c73ac3a62bbfb3068469aec15cc0bc795de/wrapt-2.1.2-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:98ba61833a77b747901e9012072f038795de7fc77849f1faa965464f3f87ff2d", size = 61601, upload-time = "2026-03-06T02:53:00.487Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/be/d7c88cd9293c859fc74b232abdc65a229bb953997995d6912fc85af18323/wrapt-2.1.2-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:767c0dbbe76cae2a60dd2b235ac0c87c9cccf4898aef8062e57bead46b5f6894", size = 114057, upload-time = "2026-03-06T02:52:44.08Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/25/36c04602831a4d685d45a93b3abea61eca7fe35dab6c842d6f5d570ef94a/wrapt-2.1.2-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9c691a6bc752c0cc4711cc0c00896fcd0f116abc253609ef64ef930032821842", size = 116099, upload-time = "2026-03-06T02:54:56.74Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/4e/98a6eb417ef551dc277bec1253d5246b25003cf36fdf3913b65cb7657a56/wrapt-2.1.2-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:f3b7d73012ea75aee5844de58c88f44cf62d0d62711e39da5a82824a7c4626a8", size = 112457, upload-time = "2026-03-06T02:53:52.842Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/a6/a6f7186a5297cad8ec53fd7578533b28f795fdf5372368c74bd7e6e9841c/wrapt-2.1.2-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:577dff354e7acd9d411eaf4bfe76b724c89c89c8fc9b7e127ee28c5f7bcb25b6", size = 115351, upload-time = "2026-03-06T02:53:32.684Z" },
+    { url = "https://files.pythonhosted.org/packages/97/6f/06e66189e721dbebd5cf20e138acc4d1150288ce118462f2fcbff92d38db/wrapt-2.1.2-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:3d7b6fd105f8b24e5bd23ccf41cb1d1099796524bcc6f7fbb8fe576c44befbc9", size = 111748, upload-time = "2026-03-06T02:53:08.455Z" },
+    { url = "https://files.pythonhosted.org/packages/ef/43/4808b86f499a51370fbdbdfa6cb91e9b9169e762716456471b619fca7a70/wrapt-2.1.2-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:866abdbf4612e0b34764922ef8b1c5668867610a718d3053d59e24a5e5fcfc15", size = 113783, upload-time = "2026-03-06T02:53:02.02Z" },
+    { url = "https://files.pythonhosted.org/packages/91/2c/a3f28b8fa7ac2cefa01cfcaca3471f9b0460608d012b693998cd61ef43df/wrapt-2.1.2-cp311-cp311-win32.whl", hash = "sha256:5a0a0a3a882393095573344075189eb2d566e0fd205a2b6414e9997b1b800a8b", size = 57977, upload-time = "2026-03-06T02:53:27.844Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/c3/2b1c7bd07a27b1db885a2fab469b707bdd35bddf30a113b4917a7e2139d2/wrapt-2.1.2-cp311-cp311-win_amd64.whl", hash = "sha256:64a07a71d2730ba56f11d1a4b91f7817dc79bc134c11516b75d1921a7c6fcda1", size = 60336, upload-time = "2026-03-06T02:54:28.104Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/5c/76ece7b401b088daa6503d6264dd80f9a727df3e6042802de9a223084ea2/wrapt-2.1.2-cp311-cp311-win_arm64.whl", hash = "sha256:b89f095fe98bc12107f82a9f7d570dc83a0870291aeb6b1d7a7d35575f55d98a", size = 58756, upload-time = "2026-03-06T02:53:16.319Z" },
+    { url = "https://files.pythonhosted.org/packages/4c/b6/1db817582c49c7fcbb7df6809d0f515af29d7c2fbf57eb44c36e98fb1492/wrapt-2.1.2-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:ff2aad9c4cda28a8f0653fc2d487596458c2a3f475e56ba02909e950a9efa6a9", size = 61255, upload-time = "2026-03-06T02:52:45.663Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/16/9b02a6b99c09227c93cd4b73acc3678114154ec38da53043c0ddc1fba0dc/wrapt-2.1.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:6433ea84e1cfacf32021d2a4ee909554ade7fd392caa6f7c13f1f4bf7b8e8748", size = 61848, upload-time = "2026-03-06T02:53:48.728Z" },
+    { url = "https://files.pythonhosted.org/packages/af/aa/ead46a88f9ec3a432a4832dfedb84092fc35af2d0ba40cd04aea3889f247/wrapt-2.1.2-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:c20b757c268d30d6215916a5fa8461048d023865d888e437fab451139cad6c8e", size = 121433, upload-time = "2026-03-06T02:54:40.328Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/9f/742c7c7cdf58b59085a1ee4b6c37b013f66ac33673a7ef4aaed5e992bc33/wrapt-2.1.2-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:79847b83eb38e70d93dc392c7c5b587efe65b3e7afcc167aa8abd5d60e8761c8", size = 123013, upload-time = "2026-03-06T02:53:26.58Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/44/2c3dd45d53236b7ed7c646fcf212251dc19e48e599debd3926b52310fafb/wrapt-2.1.2-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:f8fba1bae256186a83d1875b2b1f4e2d1242e8fac0f58ec0d7e41b26967b965c", size = 117326, upload-time = "2026-03-06T02:53:11.547Z" },
+    { url = "https://files.pythonhosted.org/packages/74/e2/b17d66abc26bd96f89dec0ecd0ef03da4a1286e6ff793839ec431b9fae57/wrapt-2.1.2-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:e3d3b35eedcf5f7d022291ecd7533321c4775f7b9cd0050a31a68499ba45757c", size = 121444, upload-time = "2026-03-06T02:54:09.5Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/62/e2977843fdf9f03daf1586a0ff49060b1b2fc7ff85a7ea82b6217c1ae36e/wrapt-2.1.2-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:6f2c5390460de57fa9582bc8a1b7a6c86e1a41dfad74c5225fc07044c15cc8d1", size = 116237, upload-time = "2026-03-06T02:54:03.884Z" },
+    { url = "https://files.pythonhosted.org/packages/88/dd/27fc67914e68d740bce512f11734aec08696e6b17641fef8867c00c949fc/wrapt-2.1.2-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:7dfa9f2cf65d027b951d05c662cc99ee3bd01f6e4691ed39848a7a5fffc902b2", size = 120563, upload-time = "2026-03-06T02:53:20.412Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/9f/b750b3692ed2ef4705cb305bd68858e73010492b80e43d2a4faa5573cbe7/wrapt-2.1.2-cp312-cp312-win32.whl", hash = "sha256:eba8155747eb2cae4a0b913d9ebd12a1db4d860fc4c829d7578c7b989bd3f2f0", size = 58198, upload-time = "2026-03-06T02:53:37.732Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/b2/feecfe29f28483d888d76a48f03c4c4d8afea944dbee2b0cd3380f9df032/wrapt-2.1.2-cp312-cp312-win_amd64.whl", hash = "sha256:1c51c738d7d9faa0b3601708e7e2eda9bf779e1b601dce6c77411f2a1b324a63", size = 60441, upload-time = "2026-03-06T02:52:47.138Z" },
+    { url = "https://files.pythonhosted.org/packages/44/e1/e328f605d6e208547ea9fd120804fcdec68536ac748987a68c47c606eea8/wrapt-2.1.2-cp312-cp312-win_arm64.whl", hash = "sha256:c8e46ae8e4032792eb2f677dbd0d557170a8e5524d22acc55199f43efedd39bf", size = 58836, upload-time = "2026-03-06T02:53:22.053Z" },
+    { url = "https://files.pythonhosted.org/packages/4c/7a/d936840735c828b38d26a854e85d5338894cda544cb7a85a9d5b8b9c4df7/wrapt-2.1.2-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:787fd6f4d67befa6fe2abdffcbd3de2d82dfc6fb8a6d850407c53332709d030b", size = 61259, upload-time = "2026-03-06T02:53:41.922Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/88/9a9b9a90ac8ca11c2fdb6a286cb3a1fc7dd774c00ed70929a6434f6bc634/wrapt-2.1.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:4bdf26e03e6d0da3f0e9422fd36bcebf7bc0eeb55fdf9c727a09abc6b9fe472e", size = 61851, upload-time = "2026-03-06T02:52:48.672Z" },
+    { url = "https://files.pythonhosted.org/packages/03/a9/5b7d6a16fd6533fed2756900fc8fc923f678179aea62ada6d65c92718c00/wrapt-2.1.2-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:bbac24d879aa22998e87f6b3f481a5216311e7d53c7db87f189a7a0266dafffb", size = 121446, upload-time = "2026-03-06T02:54:14.013Z" },
+    { url = "https://files.pythonhosted.org/packages/45/bb/34c443690c847835cfe9f892be78c533d4f32366ad2888972c094a897e39/wrapt-2.1.2-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:16997dfb9d67addc2e3f41b62a104341e80cac52f91110dece393923c0ebd5ca", size = 123056, upload-time = "2026-03-06T02:54:10.829Z" },
+    { url = "https://files.pythonhosted.org/packages/93/b9/ff205f391cb708f67f41ea148545f2b53ff543a7ac293b30d178af4d2271/wrapt-2.1.2-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:162e4e2ba7542da9027821cb6e7c5e068d64f9a10b5f15512ea28e954893a267", size = 117359, upload-time = "2026-03-06T02:53:03.623Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/3d/1ea04d7747825119c3c9a5e0874a40b33594ada92e5649347c457d982805/wrapt-2.1.2-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:f29c827a8d9936ac320746747a016c4bc66ef639f5cd0d32df24f5eacbf9c69f", size = 121479, upload-time = "2026-03-06T02:53:45.844Z" },
+    { url = "https://files.pythonhosted.org/packages/78/cc/ee3a011920c7a023b25e8df26f306b2484a531ab84ca5c96260a73de76c0/wrapt-2.1.2-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:a9dd9813825f7ecb018c17fd147a01845eb330254dff86d3b5816f20f4d6aaf8", size = 116271, upload-time = "2026-03-06T02:54:46.356Z" },
+    { url = "https://files.pythonhosted.org/packages/98/fd/e5ff7ded41b76d802cf1191288473e850d24ba2e39a6ec540f21ae3b57cb/wrapt-2.1.2-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:6f8dbdd3719e534860d6a78526aafc220e0241f981367018c2875178cf83a413", size = 120573, upload-time = "2026-03-06T02:52:50.163Z" },
+    { url = "https://files.pythonhosted.org/packages/47/c5/242cae3b5b080cd09bacef0591691ba1879739050cc7c801ff35c8886b66/wrapt-2.1.2-cp313-cp313-win32.whl", hash = "sha256:5c35b5d82b16a3bc6e0a04349b606a0582bc29f573786aebe98e0c159bc48db6", size = 58205, upload-time = "2026-03-06T02:53:47.494Z" },
+    { url = "https://files.pythonhosted.org/packages/12/69/c358c61e7a50f290958809b3c61ebe8b3838ea3e070d7aac9814f95a0528/wrapt-2.1.2-cp313-cp313-win_amd64.whl", hash = "sha256:f8bc1c264d8d1cf5b3560a87bbdd31131573eb25f9f9447bb6252b8d4c44a3a1", size = 60452, upload-time = "2026-03-06T02:53:30.038Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/66/c8a6fcfe321295fd8c0ab1bd685b5a01462a9b3aa2f597254462fc2bc975/wrapt-2.1.2-cp313-cp313-win_arm64.whl", hash = "sha256:3beb22f674550d5634642c645aba4c72a2c66fb185ae1aebe1e955fae5a13baf", size = 58842, upload-time = "2026-03-06T02:52:52.114Z" },
+    { url = "https://files.pythonhosted.org/packages/da/55/9c7052c349106e0b3f17ae8db4b23a691a963c334de7f9dbd60f8f74a831/wrapt-2.1.2-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:0fc04bc8664a8bc4c8e00b37b5355cffca2535209fba1abb09ae2b7c76ddf82b", size = 63075, upload-time = "2026-03-06T02:53:19.108Z" },
+    { url = "https://files.pythonhosted.org/packages/09/a8/ce7b4006f7218248dd71b7b2b732d0710845a0e49213b18faef64811ffef/wrapt-2.1.2-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:a9b9d50c9af998875a1482a038eb05755dfd6fe303a313f6a940bb53a83c3f18", size = 63719, upload-time = "2026-03-06T02:54:33.452Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/e5/2ca472e80b9e2b7a17f106bb8f9df1db11e62101652ce210f66935c6af67/wrapt-2.1.2-cp313-cp313t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:2d3ff4f0024dd224290c0eabf0240f1bfc1f26363431505fb1b0283d3b08f11d", size = 152643, upload-time = "2026-03-06T02:52:42.721Z" },
+    { url = "https://files.pythonhosted.org/packages/36/42/30f0f2cefca9d9cbf6835f544d825064570203c3e70aa873d8ae12e23791/wrapt-2.1.2-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3278c471f4468ad544a691b31bb856374fbdefb7fee1a152153e64019379f015", size = 158805, upload-time = "2026-03-06T02:54:25.441Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/67/d08672f801f604889dcf58f1a0b424fe3808860ede9e03affc1876b295af/wrapt-2.1.2-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:a8914c754d3134a3032601c6984db1c576e6abaf3fc68094bb8ab1379d75ff92", size = 145990, upload-time = "2026-03-06T02:53:57.456Z" },
+    { url = "https://files.pythonhosted.org/packages/68/a7/fd371b02e73babec1de6ade596e8cd9691051058cfdadbfd62a5898f3295/wrapt-2.1.2-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:ff95d4264e55839be37bafe1536db2ab2de19da6b65f9244f01f332b5286cfbf", size = 155670, upload-time = "2026-03-06T02:54:55.309Z" },
+    { url = "https://files.pythonhosted.org/packages/86/2d/9fe0095dfdb621009f40117dcebf41d7396c2c22dca6eac779f4c007b86c/wrapt-2.1.2-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:76405518ca4e1b76fbb1b9f686cff93aebae03920cc55ceeec48ff9f719c5f67", size = 144357, upload-time = "2026-03-06T02:54:24.092Z" },
+    { url = "https://files.pythonhosted.org/packages/0e/b6/ec7b4a254abbe4cde9fa15c5d2cca4518f6b07d0f1b77d4ee9655e30280e/wrapt-2.1.2-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:c0be8b5a74c5824e9359b53e7e58bef71a729bacc82e16587db1c4ebc91f7c5a", size = 150269, upload-time = "2026-03-06T02:53:31.268Z" },
+    { url = "https://files.pythonhosted.org/packages/6e/6b/2fabe8ebf148f4ee3c782aae86a795cc68ffe7d432ef550f234025ce0cfa/wrapt-2.1.2-cp313-cp313t-win32.whl", hash = "sha256:f01277d9a5fc1862f26f7626da9cf443bebc0abd2f303f41c5e995b15887dabd", size = 59894, upload-time = "2026-03-06T02:54:15.391Z" },
+    { url = "https://files.pythonhosted.org/packages/ca/fb/9ba66fc2dedc936de5f8073c0217b5d4484e966d87723415cc8262c5d9c2/wrapt-2.1.2-cp313-cp313t-win_amd64.whl", hash = "sha256:84ce8f1c2104d2f6daa912b1b5b039f331febfeee74f8042ad4e04992bd95c8f", size = 63197, upload-time = "2026-03-06T02:54:41.943Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/1c/012d7423c95d0e337117723eb8ecf73c622ce15a97847e84cf3f8f26cd7e/wrapt-2.1.2-cp313-cp313t-win_arm64.whl", hash = "sha256:a93cd767e37faeddbe07d8fc4212d5cba660af59bdb0f6372c93faaa13e6e679", size = 60363, upload-time = "2026-03-06T02:54:48.093Z" },
+    { url = "https://files.pythonhosted.org/packages/39/25/e7ea0b417db02bb796182a5316398a75792cd9a22528783d868755e1f669/wrapt-2.1.2-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:1370e516598854e5b4366e09ce81e08bfe94d42b0fd569b88ec46cc56d9164a9", size = 61418, upload-time = "2026-03-06T02:53:55.706Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/0f/fa539e2f6a770249907757eaeb9a5ff4deb41c026f8466c1c6d799088a9b/wrapt-2.1.2-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:6de1a3851c27e0bd6a04ca993ea6f80fc53e6c742ee1601f486c08e9f9b900a9", size = 61914, upload-time = "2026-03-06T02:52:53.37Z" },
+    { url = "https://files.pythonhosted.org/packages/53/37/02af1867f5b1441aaeda9c82deed061b7cd1372572ddcd717f6df90b5e93/wrapt-2.1.2-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:de9f1a2bbc5ac7f6012ec24525bdd444765a2ff64b5985ac6e0692144838542e", size = 120417, upload-time = "2026-03-06T02:54:30.74Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/b7/0138a6238c8ba7476c77cf786a807f871672b37f37a422970342308276e7/wrapt-2.1.2-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:970d57ed83fa040d8b20c52fe74a6ae7e3775ae8cff5efd6a81e06b19078484c", size = 122797, upload-time = "2026-03-06T02:54:51.539Z" },
+    { url = "https://files.pythonhosted.org/packages/e1/ad/819ae558036d6a15b7ed290d5b14e209ca795dd4da9c58e50c067d5927b0/wrapt-2.1.2-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:3969c56e4563c375861c8df14fa55146e81ac11c8db49ea6fb7f2ba58bc1ff9a", size = 117350, upload-time = "2026-03-06T02:54:37.651Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/2d/afc18dc57a4600a6e594f77a9ae09db54f55ba455440a54886694a84c71b/wrapt-2.1.2-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:57d7c0c980abdc5f1d98b11a2aa3bb159790add80258c717fa49a99921456d90", size = 121223, upload-time = "2026-03-06T02:54:35.221Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/5b/5ec189b22205697bc56eb3b62aed87a1e0423e9c8285d0781c7a83170d15/wrapt-2.1.2-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:776867878e83130c7a04237010463372e877c1c994d449ca6aaafeab6aab2586", size = 116287, upload-time = "2026-03-06T02:54:19.654Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/2d/f84939a7c9b5e6cdd8a8d0f6a26cabf36a0f7e468b967720e8b0cd2bdf69/wrapt-2.1.2-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:fab036efe5464ec3291411fabb80a7a39e2dd80bae9bcbeeca5087fdfa891e19", size = 119593, upload-time = "2026-03-06T02:54:16.697Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/fe/ccd22a1263159c4ac811ab9374c061bcb4a702773f6e06e38de5f81a1bdc/wrapt-2.1.2-cp314-cp314-win32.whl", hash = "sha256:e6ed62c82ddf58d001096ae84ce7f833db97ae2263bff31c9b336ba8cfe3f508", size = 58631, upload-time = "2026-03-06T02:53:06.498Z" },
+    { url = "https://files.pythonhosted.org/packages/65/0a/6bd83be7bff2e7efaac7b4ac9748da9d75a34634bbbbc8ad077d527146df/wrapt-2.1.2-cp314-cp314-win_amd64.whl", hash = "sha256:467e7c76315390331c67073073d00662015bb730c566820c9ca9b54e4d67fd04", size = 60875, upload-time = "2026-03-06T02:53:50.252Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/c0/0b3056397fe02ff80e5a5d72d627c11eb885d1ca78e71b1a5c1e8c7d45de/wrapt-2.1.2-cp314-cp314-win_arm64.whl", hash = "sha256:da1f00a557c66225d53b095a97eace0fc5349e3bfda28fa34ffae238978ee575", size = 59164, upload-time = "2026-03-06T02:53:59.128Z" },
+    { url = "https://files.pythonhosted.org/packages/71/ed/5d89c798741993b2371396eb9d4634f009ff1ad8a6c78d366fe2883ea7a6/wrapt-2.1.2-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:62503ffbc2d3a69891cf29beeaccdb4d5e0a126e2b6a851688d4777e01428dbb", size = 63163, upload-time = "2026-03-06T02:52:54.873Z" },
+    { url = "https://files.pythonhosted.org/packages/c6/8c/05d277d182bf36b0a13d6bd393ed1dec3468a25b59d01fba2dd70fe4d6ae/wrapt-2.1.2-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:c7e6cd120ef837d5b6f860a6ea3745f8763805c418bb2f12eeb1fa6e25f22d22", size = 63723, upload-time = "2026-03-06T02:52:56.374Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/27/6c51ec1eff4413c57e72d6106bb8dec6f0c7cdba6503d78f0fa98767bcc9/wrapt-2.1.2-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:3769a77df8e756d65fbc050333f423c01ae012b4f6731aaf70cf2bef61b34596", size = 152652, upload-time = "2026-03-06T02:53:23.79Z" },
+    { url = "https://files.pythonhosted.org/packages/db/4c/d7dd662d6963fc7335bfe29d512b02b71cdfa23eeca7ab3ac74a67505deb/wrapt-2.1.2-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a76d61a2e851996150ba0f80582dd92a870643fa481f3b3846f229de88caf044", size = 158807, upload-time = "2026-03-06T02:53:35.742Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/4d/1e5eea1a78d539d346765727422976676615814029522c76b87a95f6bcdd/wrapt-2.1.2-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:6f97edc9842cf215312b75fe737ee7c8adda75a89979f8e11558dfff6343cc4b", size = 146061, upload-time = "2026-03-06T02:52:57.574Z" },
+    { url = "https://files.pythonhosted.org/packages/89/bc/62cabea7695cd12a288023251eeefdcb8465056ddaab6227cb78a2de005b/wrapt-2.1.2-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:4006c351de6d5007aa33a551f600404ba44228a89e833d2fadc5caa5de8edfbf", size = 155667, upload-time = "2026-03-06T02:53:39.422Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/99/6f2888cd68588f24df3a76572c69c2de28287acb9e1972bf0c83ce97dbc1/wrapt-2.1.2-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:a9372fc3639a878c8e7d87e1556fa209091b0a66e912c611e3f833e2c4202be2", size = 144392, upload-time = "2026-03-06T02:54:22.41Z" },
+    { url = "https://files.pythonhosted.org/packages/40/51/1dfc783a6c57971614c48e361a82ca3b6da9055879952587bc99fe1a7171/wrapt-2.1.2-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:3144b027ff30cbd2fca07c0a87e67011adb717eb5f5bd8496325c17e454257a3", size = 150296, upload-time = "2026-03-06T02:54:07.848Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/38/cbb8b933a0201076c1f64fc42883b0023002bdc14a4964219154e6ff3350/wrapt-2.1.2-cp314-cp314t-win32.whl", hash = "sha256:3b8d15e52e195813efe5db8cec156eebe339aaf84222f4f4f051a6c01f237ed7", size = 60539, upload-time = "2026-03-06T02:54:00.594Z" },
+    { url = "https://files.pythonhosted.org/packages/82/dd/e5176e4b241c9f528402cebb238a36785a628179d7d8b71091154b3e4c9e/wrapt-2.1.2-cp314-cp314t-win_amd64.whl", hash = "sha256:08ffa54146a7559f5b8df4b289b46d963a8e74ed16ba3687f99896101a3990c5", size = 63969, upload-time = "2026-03-06T02:54:39Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/99/79f17046cf67e4a95b9987ea129632ba8bcec0bc81f3fb3d19bdb0bd60cd/wrapt-2.1.2-cp314-cp314t-win_arm64.whl", hash = "sha256:72aaa9d0d8e4ed0e2e98019cea47a21f823c9dd4b43c7b77bba6679ffcca6a00", size = 60554, upload-time = "2026-03-06T02:53:14.132Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/c7/8528ac2dfa2c1e6708f647df7ae144ead13f0a31146f43c7264b4942bf12/wrapt-2.1.2-py3-none-any.whl", hash = "sha256:b8fd6fa2b2c4e7621808f8c62e8317f4aae56e59721ad933bac5239d913cf0e8", size = 43993, upload-time = "2026-03-06T02:53:12.905Z" },
+]
+
 [[package]]
 name = "wsproto"
 version = "1.3.2"

From a90b129a872732c7d4aa8cdf8d6f0375e5a59906 Mon Sep 17 00:00:00 2001
From: jbmendonca <jbmendonca@users.noreply.github.com>
Date: Thu, 30 Apr 2026 10:35:34 -0400
Subject: [PATCH 11/12] fix(dashboard): fix terminal websocket proxy routing on
 Werkzeug 3.1+

---
 dashboard/backend/app.py | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/dashboard/backend/app.py b/dashboard/backend/app.py
index ed3aa6aa..e070c93c 100644
--- a/dashboard/backend/app.py
+++ b/dashboard/backend/app.py
@@ -61,6 +61,28 @@ def _cors_allowed_origins():
     return "*" if not _is_production() else []
 
 app = Flask(__name__, static_folder=None)
+
+class ProxyFixWSGI:
+    def __init__(self, wsgi_app):
+        self.wsgi_app = wsgi_app
+
+    def __call__(self, environ, start_response):
+        if environ.get('HTTP_UPGRADE', '').lower() == 'websocket':
+            environ['wsgi.websocket'] = True
+        return self.wsgi_app(environ, start_response)
+
+app.wsgi_app = ProxyFixWSGI(app.wsgi_app)
+
+class ProxyFixWSGI:
+    def __init__(self, wsgi_app):
+        self.wsgi_app = wsgi_app
+    def __call__(self, environ, start_response):
+        print('PROXY_FIX:', environ.get('HTTP_UPGRADE', ''), flush=True)
+        if environ.get('HTTP_UPGRADE', '').lower() == 'websocket':
+            environ['wsgi.websocket'] = True
+        return self.wsgi_app(environ, start_response)
+
+app.wsgi_app = ProxyFixWSGI(app.wsgi_app)
 # Persist secret key so sessions survive restarts
 _secret_key = os.environ.get("EVONEXUS_SECRET_KEY")
 if not _secret_key:
@@ -960,6 +982,11 @@ def attach_security_headers(response):
 app.register_blueprint(triggers_bp)
 app.register_blueprint(terminal_proxy_bp)
 
+@app.route('/terminal/ws')
+def proxy_ws_test():
+    print("HIT PROXY_WS_TEST!!!", flush=True)
+    return "test"
+
 # Mount the terminal-server WebSocket proxy on the same Sock instance the
 # rest of the app uses. Done after the blueprint is registered so route
 # names are unique. Without this, browsers connecting from a host other

From ffe1a7aab74aaeb28b9abe9f72d799cd922d332f Mon Sep 17 00:00:00 2001
From: jbmendonca <jbmendonca@users.noreply.github.com>
Date: Thu, 30 Apr 2026 10:45:56 -0400
Subject: [PATCH 12/12] docs: add WEBSOCKET_PROXY_FIX.md explaining terminal
 stability patch

---
 docs/WEBSOCKET_PROXY_FIX.md | 43 +++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 docs/WEBSOCKET_PROXY_FIX.md

diff --git a/docs/WEBSOCKET_PROXY_FIX.md b/docs/WEBSOCKET_PROXY_FIX.md
new file mode 100644
index 00000000..c925a526
--- /dev/null
+++ b/docs/WEBSOCKET_PROXY_FIX.md
@@ -0,0 +1,43 @@
+# WebSocket Proxy Fix (Werkzeug 3.1+)
+
+## O Problema
+
+Durante a atualização do EvoNexus para a versão `v0.33.0` (ou qualquer ambiente usando Flask 3.0+ e Werkzeug 3.1+), os terminais começaram a sofrer fechamentos repentinos com o erro "WebSocket error" no frontend.
+
+A investigação revelou que o problema ocorria devido a uma mudança arquitetural no **Werkzeug**. A partir da versão 2.1, o Werkzeug removeu o suporte nativo a *WebSocket Hijacking* no seu servidor WSGI de desenvolvimento.
+
+A extensão `flask-sock` e o pacote subjacente `simple-websocket` utilizam *monkey-patching* para restaurar esse suporte, exigindo que as regras de rota WebSocket tenham o sinalizador `websocket=True` habilitado internamente. 
+No entanto, quando a aplicação roda atrás de um proxy reverso (como o **Traefik** no ambiente de produção da VPS), os cabeçalhos de *Upgrade* são repassados como `HTTP_UPGRADE: websocket`. Como o ambiente WSGI gerado não contém a variável interna `wsgi.websocket = True`, o sistema de roteamento do Werkzeug considera que a requisição **não é** um WebSocket.
+
+**A Cascata de Falhas:**
+1. O navegador conecta-se a `wss://<dominio>/terminal/ws`.
+2. O Traefik encaminha para o Flask com `HTTP_UPGRADE: websocket`.
+3. O Werkzeug avalia a rota `/terminal/ws` do `flask-sock` (que exige `wsgi.websocket = True`), avalia como **falsa** (não correspondente) e **pula** essa rota.
+4. A requisição "cai" na rota coringa de proxy HTTP (`/terminal/<path:subpath>`).
+5. A rota HTTP converte a requisição WebSocket num `GET` normal e envia para o servidor Node.js interno do terminal (`:32352/ws`).
+6. O servidor Node.js não encontra uma página HTTP em `/ws` e retorna **404 Not Found**.
+7. O Flask retorna o `404` embutido num status `200 OK`, destruindo a negociação do WebSocket e derrubando a conexão.
+
+## A Solução
+
+Foi implementado um **WSGI Middleware** (`ProxyFixWSGI`) no arquivo `dashboard/backend/app.py`.
+
+```python
+class ProxyFixWSGI:
+    def __init__(self, wsgi_app):
+        self.wsgi_app = wsgi_app
+
+    def __call__(self, environ, start_response):
+        # Fix for modern Werkzeug (3.0+) not matching websocket=True rules
+        # when running behind proxies that don't set wsgi.websocket.
+        if environ.get("HTTP_UPGRADE", "").lower() == "websocket":
+            environ["wsgi.websocket"] = True
+        return self.wsgi_app(environ, start_response)
+```
+
+**Como funciona?**
+Este middleware intercepta as requisições *antes* delas entrarem na esteira de roteamento do Flask/Werkzeug. Ele examina os cabeçalhos em busca de uma solicitação de `Upgrade: websocket`. Caso encontre, ele injeta artificialmente a chave `environ["wsgi.websocket"] = True` no ambiente WSGI.
+
+Ao fazer isso, quando a requisição atinge o sistema de roteamento (o `MapAdapter`), o Werkzeug avalia a rota do `flask-sock` como perfeitamente válida para WebSockets, permitindo que o tráfego seja roteado corretamente para a função `proxy_ws` em `terminal_proxy.py`, mantendo a persistência, resiliência e validação correta do túnel WebSocket no terminal do usuário.
+
+Adicionalmente, no arquivo `terminal_proxy.py`, a rota foi estabilizada e configurada com prioridade de escopo para sempre anteceder a rota de coringa HTTP, blindando o sistema contra eventuais falhas do sistema de peso do URL Map do Flask.