From 9345c67854f6ef1ef4f68ac4b9c3ae266ecceccf Mon Sep 17 00:00:00 2001
From: emozilla <emozilla@nousresearch.com>
Date: Fri, 18 Sep 2026 14:37:08 -0400
Subject: [PATCH 001/190] fix(webhook): per-route toolsets bind to the
 authenticated route, not a split of chat_id (GHSA-2fmg-cjqm-hhrj)

toolsets_for_source recovered the route for the per-route toolsets grant by
splitting the session chat_id "webhook:{route}:{delivery_id}" on ":", while
authentication used the exact URL segment. A route named "build:external"
therefore resolved to route "build" and inherited its toolsets: a caller
holding the weak route's HMAC secret got the privileged sibling's terminal/
file tools. Reproduced on main through the real aiohttp handler with a
signed request.

Key the lookup on source.user_id instead, which _dispatch_agent_run already
stamps as exactly "webhook:{route_name}" from the authenticated segment.
No split at all: delivery_id is caller-supplied (X-GitHub-Delivery, svix-id,
X-Request-ID), so any parse of chat_id, including rsplit, stays attacker-
influenced. Routes without ":" resolve identically before and after; a ":"
route with no colliding sibling now gets the toolsets it configured, where
the old code silently fell back to the platform default.

Tests go through the HTTP handler, HMAC, and the gateway resolver: the ":"
route gets its own toolsets (red on base), and a crafted delivery id on the
privileged route cannot name another route (pins against a future rsplit).

Reported-by: pinarsadioglu (GHSA-2fmg-cjqm-hhrj)
---
 gateway/platforms/webhook.py                 | 10 ++--
 tests/gateway/test_webhook_route_toolsets.py | 61 ++++++++++++++++++++
 2 files changed, 67 insertions(+), 4 deletions(-)

diff --git a/gateway/platforms/webhook.py b/gateway/platforms/webhook.py
index c8005a0df3..a9c6fa514d 100644
--- a/gateway/platforms/webhook.py
+++ b/gateway/platforms/webhook.py
@@ -323,11 +323,13 @@ class WebhookAdapter(BasePlatformAdapter):
     def toolsets_for_source(self, source) -> Optional[List[str]]:
         """Per-route ``toolsets`` override (config.yaml or a manual key in webhook_subscriptions.json —
         deliberately NOT settable via `hermes webhook subscribe`, so an agent-created subscription
-        cannot self-grant tools)."""
-        parts = str(getattr(source, "chat_id", "") or "").split(":", 2)
-        if len(parts) < 2 or parts[0] != "webhook":
+        cannot self-grant tools). Keyed on ``user_id`` (exactly ``webhook:{route}`` as authenticated), not
+        ``chat_id``, whose caller-supplied delivery id and ``:``-bearing route names make any split ambiguous
+        (GHSA-2fmg-cjqm-hhrj)."""
+        user_id = str(getattr(source, "user_id", "") or "")
+        if not user_id.startswith("webhook:"):
             return None
-        route_config = self._routes.get(parts[1])
+        route_config = self._routes.get(user_id[len("webhook:"):])
         toolsets = route_config.get("toolsets") if isinstance(route_config, dict) else None
         if not isinstance(toolsets, list):
             return None
diff --git a/tests/gateway/test_webhook_route_toolsets.py b/tests/gateway/test_webhook_route_toolsets.py
index d1a19f07f3..a830444f47 100644
--- a/tests/gateway/test_webhook_route_toolsets.py
+++ b/tests/gateway/test_webhook_route_toolsets.py
@@ -5,8 +5,22 @@ platform-level ``platform_toolsets.webhook`` resolution for runs triggered by
 that route only. The gateway validates the override through the same
 ``_get_platform_tools`` path as platform config, so restricted/unknown names
 behave identically to a manually configured platform toolset list.
+
+The grant must bind to the route whose secret authenticated the request
+(GHSA-2fmg-cjqm-hhrj): route names may contain ``:`` and the delivery id in the
+session key is caller-supplied, so nothing may be recovered by splitting ``chat_id``.
 """
 
+import asyncio
+import hashlib
+import hmac
+import json
+
+import pytest
+from aiohttp import web
+from aiohttp.test_utils import TestClient, TestServer
+
+from gateway.config import PlatformConfig
 from gateway.platforms.base import BasePlatformAdapter
 from gateway.platforms.webhook import WebhookAdapter
 from gateway.run import GatewayRunner
@@ -16,6 +30,8 @@ from hermes_cli.tools_config import _get_platform_tools
 class _Src:
     def __init__(self, chat_id):
         self.chat_id = chat_id
+        # What _dispatch_agent_run stamps: exactly the authenticated route, no delivery id.
+        self.user_id = chat_id.rsplit(":", 1)[0] if chat_id.startswith("webhook:") else None
 
 
 def _make_adapter(routes):
@@ -135,3 +151,48 @@ class TestGatewayResolveEnabledToolsetsForSource:
             gr, cfg, _Src("webhook:mon:d"), "webhook"
         )
         assert cfg["platform_toolsets"]["webhook"] == ["web"]
+
+
+class TestToolsetsBindToAuthenticatedRoute:
+    """Regression for GHSA-2fmg-cjqm-hhrj, end to end through the real HTTP handler."""
+
+    ROUTES = {
+        "build": {"secret": "strong-secret", "toolsets": ["terminal", "file"]},
+        "build:external": {"secret": "weak-secret", "toolsets": ["web"], "prompt": "{text}"},
+    }
+
+    async def _dispatch(self, path, secret, delivery_id):
+        adapter = WebhookAdapter(PlatformConfig(
+            enabled=True, extra={"host": "127.0.0.1", "port": 0, "routes": self.ROUTES}))
+        captured = []
+
+        async def _capture(event):
+            captured.append(event.source)
+
+        adapter.handle_message = _capture
+        app = web.Application()
+        app.router.add_post("/webhooks/{route_name}", adapter._handle_webhook)
+        body = json.dumps({"text": "hi"}).encode()
+        sig = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
+        async with TestClient(TestServer(app)) as cli:
+            resp = await cli.post(path, data=body, headers={
+                "X-Hub-Signature-256": sig, "Content-Type": "application/json",
+                "X-GitHub-Delivery": delivery_id})
+            assert resp.status == 202
+            await asyncio.sleep(0.05)
+        assert len(captured) == 1
+        gr = _make_runner(adapter)
+        return GatewayRunner._resolve_enabled_toolsets_for_source(gr, BASE_CONFIG, captured[0], "webhook")
+
+    @pytest.mark.asyncio
+    async def test_colon_route_gets_its_own_toolsets_not_its_prefix_routes(self):
+        res = await self._dispatch("/webhooks/build:external", "weak-secret", "d1")
+        assert "web" in res
+        assert "terminal" not in res and "file" not in res
+
+    @pytest.mark.asyncio
+    async def test_caller_supplied_delivery_id_cannot_name_another_route(self):
+        # Delivery id is attacker-controlled; a right-split would read "build:external" here.
+        res = await self._dispatch("/webhooks/build", "strong-secret", "external:d1")
+        assert "terminal" in res and "file" in res
+        assert "web" not in res

From a2ed82c88d946529264af49059b171f8d4107ce8 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 01:55:50 -0700
Subject: [PATCH 002/190] fix(desktop): keep the message reaction picker open
 while the pointer moves toward it (#114130)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Clicking the reaction button on an assistant message opened the picker,
but the very next pointer movement over the transcript closed it, so no
emoji could ever be chosen. The group-hover / PopoverAnchor mechanism in
the report is not the cause: the anchor is already kept live while open
(styles.css `[data-state='open']`) and Radix does not close on a hidden
anchor. The picker died to the floating composer's focus-follow: Radix
autofocuses the popover content when it opens, `trackPointer` pulled
that focus back into the pane composer on `pointermove`, and the
popover's `onFocusOutside` dismissed it.

Guard `focusSelectedComposer()` — the chokepoint every focus-follow
branch funnels through — against focus that sits inside an open floating
layer (popover, menu, listbox, dialog, popper wrapper). The selector is
the one `composer-focus-keys` already uses for its overlay gate, hoisted
to the leaf `combo.ts` as `OVERLAY_SURFACE` so both consumers share it.

Tests: focus-follow leaves focus inside a floating layer (with the
plain-control control case), and the assistant reaction picker survives
a pointermove over its message with a registered floating composer. Both
red on origin/main.
---
 .../floating-target-floating-layer.test.ts    | 66 +++++++++++++++++++
 .../src/app/chat/composer/floating-target.ts  | 14 +++-
 .../reaction-picker-focus-follow.test.tsx     | 65 ++++++++++++++++++
 apps/desktop/src/lib/keybinds/combo.ts        |  7 ++
 .../src/lib/keybinds/composer-focus-keys.ts   |  5 +-
 5 files changed, 151 insertions(+), 6 deletions(-)
 create mode 100644 apps/desktop/src/app/chat/composer/floating-target-floating-layer.test.ts
 create mode 100644 apps/desktop/src/components/assistant-ui/thread/reaction-picker-focus-follow.test.tsx

diff --git a/apps/desktop/src/app/chat/composer/floating-target-floating-layer.test.ts b/apps/desktop/src/app/chat/composer/floating-target-floating-layer.test.ts
new file mode 100644
index 0000000000..e2433bebcc
--- /dev/null
+++ b/apps/desktop/src/app/chat/composer/floating-target-floating-layer.test.ts
@@ -0,0 +1,66 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { registerFloatingComposer } from './floating-target'
+
+/** The owner's composer host, a chat surface with a plain control, and a
+ * body-portaled Radix popper layer holding a control — the shapes the
+ * window-level focus-follow has to tell apart. */
+function mount() {
+  const host = document.createElement('div')
+  host.dataset.composerOwner = 'surface-1'
+  const editor = document.createElement('div')
+  editor.dataset.slot = 'composer-rich-input'
+  editor.tabIndex = -1
+  host.appendChild(editor)
+  document.body.appendChild(host)
+
+  const surface = document.createElement('div')
+  surface.dataset.chatSurface = ''
+  surface.dataset.composerSurfaceId = 'surface-1'
+  const plainButton = document.createElement('button')
+  surface.appendChild(plainButton)
+  document.body.appendChild(surface)
+
+  const layer = document.createElement('div')
+  layer.setAttribute('data-radix-popper-content-wrapper', '')
+  const layerButton = document.createElement('button')
+  layer.appendChild(layerButton)
+  document.body.appendChild(layer)
+
+  return { editor, layerButton, plainButton, surface }
+}
+
+/** Button-up movement over the chat surface — every hover of the transcript. */
+function movePointerOver(target: Element, x: number) {
+  target.dispatchEvent(new PointerEvent('pointermove', { bubbles: true, buttons: 0, clientX: x, clientY: 40 }))
+}
+
+/** Radix moves focus into a popover/menu when it opens and dismisses it as soon
+ * as focus leaves. The focus-follow used to pull that focus back into the pane
+ * composer on the next pointermove, so the message reaction picker closed
+ * before the pointer could reach it. */
+describe('floating composer focus-follow vs an open floating layer', () => {
+  let unregister: (() => void) | undefined
+
+  afterEach(() => {
+    unregister?.()
+    unregister = undefined
+    document.body.innerHTML = ''
+  })
+
+  it('leaves focus inside a floating layer, but still follows the pointer otherwise', () => {
+    const { editor, layerButton, plainButton, surface } = mount()
+    unregister = registerFloatingComposer('surface-1', { groupId: 'g1', target: 'main' })
+
+    layerButton.focus()
+    movePointerOver(surface, 10)
+    expect(document.activeElement).toBe(layerButton)
+
+    // Control: focus on an ordinary control in the surface is not "owned" —
+    // hovering the transcript hands the caret to the composer as before.
+    plainButton.focus()
+    movePointerOver(surface, 20)
+    expect(document.activeElement).toBe(editor)
+  })
+})
diff --git a/apps/desktop/src/app/chat/composer/floating-target.ts b/apps/desktop/src/app/chat/composer/floating-target.ts
index 6bf5f2451a..4fe29bf1d9 100644
--- a/apps/desktop/src/app/chat/composer/floating-target.ts
+++ b/apps/desktop/src/app/chat/composer/floating-target.ts
@@ -1,7 +1,7 @@
 import { flushSync } from 'react-dom'
 
 import { $activeTreeGroup, $hoveredTreeGroup, noteActiveTreeGroup } from '@/components/pane-shell/tree/store'
-import { isEditableTarget } from '@/lib/keybinds/combo'
+import { isEditableTarget, OVERLAY_SURFACE } from '@/lib/keybinds/combo'
 import { $composerPopout } from '@/store/composer-popout'
 
 import { $floatingComposerOwner, type FloatingComposerOwner } from './floating-state'
@@ -32,6 +32,13 @@ const inInlineEdit = (el: Element | null) => Boolean(el?.closest(EDIT_COMPOSER_R
 const keepsOwnFocus = (el: Element | null) =>
   inInlineEdit(el) || (isEditableTarget(el) && !el?.closest('[data-slot="composer-rich-input"]'))
 
+/** Focus inside an open floating layer — a popover, menu, listbox or dialog
+ * portaled over the transcript — is the user's own as well. Radix moves focus
+ * into such a layer when it opens and dismisses it the moment focus leaves, so
+ * pulling the caret back to the pane composer on the very next pointermove
+ * closed the message reaction picker before the pointer could reach it. */
+const inFloatingLayer = (el: Element | null) => Boolean(el?.closest(OVERLAY_SURFACE))
+
 function rememberCaret(editor: EventTarget | null) {
   const selection = window.getSelection()
 
@@ -66,11 +73,12 @@ function selectionOutsideComposer(): boolean {
 }
 
 /** Every focus-follow branch (pointermove and focusin) funnels here, so the
- * selection guard lives at this chokepoint rather than at one call site. */
+ * selection and floating-layer guards live at this chokepoint rather than at
+ * one call site. */
 function focusSelectedComposer() {
   const owner = $floatingComposerOwner.get()
 
-  if (!owner || selectionOutsideComposer()) {
+  if (!owner || selectionOutsideComposer() || inFloatingLayer(document.activeElement)) {
     return
   }
 
diff --git a/apps/desktop/src/components/assistant-ui/thread/reaction-picker-focus-follow.test.tsx b/apps/desktop/src/components/assistant-ui/thread/reaction-picker-focus-follow.test.tsx
new file mode 100644
index 0000000000..dc3f1c804c
--- /dev/null
+++ b/apps/desktop/src/components/assistant-ui/thread/reaction-picker-focus-follow.test.tsx
@@ -0,0 +1,65 @@
+import { AssistantRuntimeProvider, type ThreadMessage, useExternalStoreRuntime } from '@assistant-ui/react'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { registerFloatingComposer } from '@/app/chat/composer/floating-target'
+import { $reactionsEnabled } from '@/store/reactions-enabled'
+
+import { assistantMessage, stubThreadEnvironment } from '../test-utils'
+
+import { Thread } from '.'
+
+stubThreadEnvironment()
+
+/** The transcript inside a chat surface that owns a floating composer — the
+ * shape of every chat pane, and the one the window-level focus-follow acts on. */
+function Harness() {
+  const runtime = useExternalStoreRuntime<ThreadMessage>({
+    messages: [assistantMessage()],
+    isRunning: false,
+    onNew: async () => {}
+  })
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <div data-chat-surface="" data-composer-surface-id="surface-1">
+        <Thread />
+        <div data-composer-owner="surface-1">
+          <div contentEditable data-slot="composer-rich-input" suppressContentEditableWarning tabIndex={-1} />
+        </div>
+      </div>
+    </AssistantRuntimeProvider>
+  )
+}
+
+let unregister: (() => void) | undefined
+
+beforeEach(() => {
+  $reactionsEnabled.set(true)
+  unregister = registerFloatingComposer('surface-1', { groupId: 'g1', target: 'main' })
+})
+
+afterEach(() => {
+  unregister?.()
+  unregister = undefined
+  cleanup()
+  $reactionsEnabled.set(false)
+})
+
+describe('assistant reaction picker', () => {
+  it('stays open while the pointer moves over the message toward it', async () => {
+    render(<Harness />)
+
+    const message = (await screen.findByText('done')).closest<HTMLElement>('[data-slot="aui_assistant-message-root"]')
+    const trigger = message?.querySelector<HTMLButtonElement>('[data-slot="aui_msg-reactions"]')
+
+    expect(trigger).toBeTruthy()
+    fireEvent.click(trigger!)
+    expect(await screen.findByRole('button', { name: '👍' })).toBeTruthy()
+
+    fireEvent.pointerMove(message!, { buttons: 0, clientX: 40, clientY: 40 })
+
+    expect(screen.queryByRole('button', { name: '👍' })).not.toBeNull()
+    expect(trigger?.getAttribute('data-state')).toBe('open')
+  })
+})
diff --git a/apps/desktop/src/lib/keybinds/combo.ts b/apps/desktop/src/lib/keybinds/combo.ts
index d5cedeeb90..4222816e42 100644
--- a/apps/desktop/src/lib/keybinds/combo.ts
+++ b/apps/desktop/src/lib/keybinds/combo.ts
@@ -235,6 +235,13 @@ export function isFocusWithin(selector: string): boolean {
   return document.activeElement?.closest(selector) != null
 }
 
+// Overlays that cover the whole window (portaled to the body, or the overlay
+// shell itself): dialogs, menus, listboxes, every Radix popper layer. One
+// anywhere means the composer is behind it — its keys, and any focus the
+// user has inside it, are the overlay's own.
+export const OVERLAY_SURFACE =
+  '[role="dialog"],[role="alertdialog"],[role="menu"],[role="listbox"],[data-radix-popper-content-wrapper],[data-overlay-surface]'
+
 // True when focus is in a text-entry surface, so bare-key shortcuts don't fire
 // while the user is typing.
 export function isEditableTarget(target: EventTarget | null): boolean {
diff --git a/apps/desktop/src/lib/keybinds/composer-focus-keys.ts b/apps/desktop/src/lib/keybinds/composer-focus-keys.ts
index 8cc7d7bdcd..b56ad899fd 100644
--- a/apps/desktop/src/lib/keybinds/composer-focus-keys.ts
+++ b/apps/desktop/src/lib/keybinds/composer-focus-keys.ts
@@ -11,7 +11,7 @@ import { queryAllVisible } from '@/components/pane-shell/pane-visibility'
 import { $activeTreeGroup, $hoveredTreeGroup } from '@/components/pane-shell/tree/store'
 import { switcherActive } from '@/store/session-switcher'
 
-import { isEditableTarget, isFocusWithin } from './combo'
+import { isEditableTarget, isFocusWithin, OVERLAY_SURFACE } from './combo'
 
 /** `composer.focus` defaults that need the surface/target gate. */
 export const isComposerFocusSoftCombo = (combo: string) => combo === '/' || combo === 'enter'
@@ -41,8 +41,7 @@ const ENTER_ACTIVATES = [
 
 // Overlays that cover the whole window (portaled to the body, or the overlay
 // shell itself) — one anywhere means the composer is behind it.
-const BLOCKING_OVERLAY =
-  '[role="dialog"],[role="alertdialog"],[role="menu"],[role="listbox"],[data-radix-popper-content-wrapper],[data-overlay-surface]'
+const BLOCKING_OVERLAY = OVERLAY_SURFACE
 
 // Blockers that live INSIDE a chat surface. Inactive tabs stay mounted, so this
 // one has to be visible-scoped: a clarify card waiting in a background thread

From 9d5a076c4c81763f9259cf26d735054c5a6ef9ac Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 04:50:36 -0700
Subject: [PATCH 003/190] refactor(desktop): read OVERLAY_SURFACE directly in
 composer-focus-keys

The hoist into combo.ts left a BLOCKING_OVERLAY alias behind for its single
use site; drop the alias.
---
 apps/desktop/src/lib/keybinds/composer-focus-keys.ts | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/apps/desktop/src/lib/keybinds/composer-focus-keys.ts b/apps/desktop/src/lib/keybinds/composer-focus-keys.ts
index b56ad899fd..1c01f3ec4c 100644
--- a/apps/desktop/src/lib/keybinds/composer-focus-keys.ts
+++ b/apps/desktop/src/lib/keybinds/composer-focus-keys.ts
@@ -39,10 +39,6 @@ const ENTER_ACTIVATES = [
   '[role="treeitem"]'
 ].join(',')
 
-// Overlays that cover the whole window (portaled to the body, or the overlay
-// shell itself) — one anywhere means the composer is behind it.
-const BLOCKING_OVERLAY = OVERLAY_SURFACE
-
 // Blockers that live INSIDE a chat surface. Inactive tabs stay mounted, so this
 // one has to be visible-scoped: a clarify card waiting in a background thread
 // must not take the foreground composer's letter keys.
@@ -155,7 +151,7 @@ export function composerFocusBlockedBySurface(): boolean {
     switcherActive() ||
     $workspaceIsPage.get() ||
     isFocusWithin('[data-terminal]') ||
-    Boolean(document.querySelector(BLOCKING_OVERLAY))
+    Boolean(document.querySelector(OVERLAY_SURFACE))
   )
 }
 

From e1374093aa07ec794e10297773031b59da33b4af Mon Sep 17 00:00:00 2001
From: John Paul Soliva <soliva.johnpaul@icloud.com>
Date: Thu, 17 Sep 2026 14:02:07 +0900
Subject: [PATCH 004/190] fix(desktop): never register a turn lease that
 nothing can release
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A routed prompt holds one lease per (route, runtime session) until the turn settles, and for a
streaming turn only a Secondary's own terminal-event listener ends it: releaseTerminalTurnLease
invokes `g.turnLeases.get(key)?.()`, so a lease that is not the mapped one is never called at all.
Two ways a hold ends up in that state, both closed here.

The function already skips the primary profile, and its comment says why: a no-op lease leaves a
phantom key that suppresses the real hold if the route is later re-homed as a secondary. But the
primary profile is not the only route served by the primary socket. retainGatewayForAgent returns a
no-op for a shared-remote collapse and for a build with no registry dialing, and gatewayForProfile
returns one for a shared-primary route; none of them creates a Secondary. A lease registered on any
of those is stored and can never be released — and because the map is keyed per session, it silently
suppresses every later hold on that session, including after the route becomes a real pooled
secondary. The shared-remote probe explicitly expects that transition: it prefers the primary "until
a later probe can prove isolation". The next turn then runs with no hold at all, so the socket is
free to be reaped mid-turn and the gateway interrupts the turn as client_gone, which is the failure
this mechanism exists to prevent.

The duplicate-lease guard is also a check-then-act: it runs before the retain awaits and the map is
written after it, so two submits for one (route, session) can both pass. The loser's hold is then
orphaned — its release is never the mapped one, so activeRequests stays above zero and the pooled
socket can never be reclaimed.

Both are decided by outcome rather than by re-probing: no pooled entry for the scope means nothing
can release the key, and a key already present means someone else owns the turn. Either way the
route is released and the caller gets a no-op.

These are the function's first tests. One takes a lease while the route rides the primary, leaves it
unreleased as a streaming turn would, then makes registry dialing available and asserts the next
turn really holds a socket. The other races two submits across the dial, fires the terminal event
the gateway's own listener would, and asserts the socket is then reclaimable. Each fails without its
own guard.
---
 .../gateway-connection-lifecycle.test.ts      | 73 ++++++++++++++++++-
 apps/desktop/src/store/gateway.ts             | 25 +++++++
 2 files changed, 97 insertions(+), 1 deletion(-)

diff --git a/apps/desktop/src/store/gateway-connection-lifecycle.test.ts b/apps/desktop/src/store/gateway-connection-lifecycle.test.ts
index 7bab024916..b712b897a9 100644
--- a/apps/desktop/src/store/gateway-connection-lifecycle.test.ts
+++ b/apps/desktop/src/store/gateway-connection-lifecycle.test.ts
@@ -17,6 +17,7 @@ const gatewayMocks = vi.hoisted(() => {
 
   return {
     connect: vi.fn(async (_wsUrl: string): Promise<void> => undefined),
+    eventHandlers: [] as ((event: unknown) => void)[],
     instances
   }
 })
@@ -37,7 +38,11 @@ vi.mock('@/hermes', () => ({
       await gatewayMocks.connect(wsUrl)
       this.connectionState = 'open'
     }
-    onEvent = vi.fn(() => () => {})
+    onEvent = vi.fn((handler: (event: unknown) => void) => {
+      gatewayMocks.eventHandlers.push(handler)
+
+      return () => {}
+    })
     onState = vi.fn(() => () => {})
     constructor() {
       gatewayMocks.instances.push(this as never)
@@ -67,6 +72,7 @@ const {
   pruneSecondaryGateways,
   reconnectSecondaryGateways,
   retainGatewayForAgent,
+  retainGatewayForSessionTurn,
   retireLocalProfileGateways,
   setPrimaryGateway
 } = await import('./gateway')
@@ -94,11 +100,76 @@ beforeEach(() => {
 afterEach(() => {
   closeSecondaryGateways()
   gatewayMocks.instances.length = 0
+  gatewayMocks.eventHandlers.length = 0
   vi.clearAllMocks()
   vi.useRealTimers()
   delete (window as unknown as { hermesDesktop?: unknown }).hermesDesktop
 })
 
+describe('retainGatewayForSessionTurn', () => {
+  it('lets the next turn take a real hold after a turn that rode the primary socket', async () => {
+    // A routed prompt holds one lease per (route, runtime session) until the turn settles, and for a
+    // streaming turn only a Secondary's terminal-event listener ends it. When the route is served by
+    // the primary socket there is no Secondary, so a lease registered then can never be released —
+    // and the map is keyed per session, so it silently suppresses every later hold on that session,
+    // including after the route is dialed as a real secondary. The socket is then free to be reaped
+    // mid-turn, which is the interruption this whole mechanism exists to prevent.
+    installDesktop({ getConnection: vi.fn() }) // no getConnectionFor: nothing to hold, no Secondary
+
+    // The streaming turn deliberately does NOT release: its release would arrive as a terminal event.
+    await retainGatewayForSessionTurn('homelab', 'writer', 'session-1')
+
+    installDesktop({
+      getConnection: vi.fn(),
+      getConnectionFor: vi.fn(async ({ connectionId, profile }: { connectionId: string; profile: string }) =>
+        descriptorFor(connectionId, profile)
+      )
+    })
+    const dialedBefore = gatewayMocks.instances.length
+
+    await retainGatewayForSessionTurn('homelab', 'writer', 'session-1')
+
+    expect(gatewayMocks.instances.length).toBeGreaterThan(dialedBefore)
+  })
+
+  it('does not orphan a hold when two submits for one session race the dial', async () => {
+    // The duplicate-lease guard runs BEFORE the retain awaits, and the map is written after it, so
+    // two submits for the same (route, session) can both pass. Only the mapped release is ever
+    // invoked — releaseTerminalTurnLease does `g.turnLeases.get(key)?.()` — so the loser's hold is
+    // never released and the socket can never be reclaimed.
+    let openDial = () => {}
+
+    const dialed = new Promise<void>(resolve => {
+      openDial = resolve
+    })
+
+    gatewayMocks.connect.mockImplementationOnce(async () => dialed)
+    installDesktop({
+      getConnectionFor: vi.fn(async ({ connectionId, profile }: { connectionId: string; profile: string }) =>
+        descriptorFor(connectionId, profile)
+      )
+    })
+
+    const both = Promise.all([
+      retainGatewayForSessionTurn('homelab', 'writer', 'session-2'),
+      retainGatewayForSessionTurn('homelab', 'writer', 'session-2')
+    ])
+
+    openDial()
+    await both
+
+    // The terminal event releases the one lease the map holds, exactly as the gateway's own
+    // listener does; a leaked second hold would keep activeRequests above zero.
+    for (const handler of gatewayMocks.eventHandlers) {
+      handler({ session_id: 'session-2', type: 'session.reclaimed' })
+    }
+
+    pruneSecondaryGateways(new Set())
+
+    expect(gatewayMocks.instances[0].close).toHaveBeenCalled()
+  })
+})
+
 describe('a redial of the active route', () => {
   it('is not cancelled by a prune that runs while it is dialing', async () => {
     // Editing the connection you are viewing defers the redial until its lease drops, then
diff --git a/apps/desktop/src/store/gateway.ts b/apps/desktop/src/store/gateway.ts
index 27a134f455..81c49a688c 100644
--- a/apps/desktop/src/store/gateway.ts
+++ b/apps/desktop/src/store/gateway.ts
@@ -1500,6 +1500,31 @@ export async function retainGatewayForSessionTurn(
   }
 
   const releaseRoute = await retainGatewayForAgent(connectionId, profile)
+
+  // Only a Secondary's own terminal-event listener releases this lease, so a route with no
+  // Secondary can never release one: retainGatewayForAgent and gatewayForProfile both hand back a
+  // no-op exactly when the route rides the primary socket (shared-remote collapse, shared-primary
+  // route, or a build without registry dialing), and none of those creates an entry. Storing the
+  // key there leaves the same phantom the primary-profile guard above avoids, and it would suppress
+  // the real hold once that route IS dialed as a secondary — which the shared-remote probe
+  // explicitly expects ("prefer the primary until a later probe can prove isolation"). Decide by
+  // outcome rather than re-probing every no-op case.
+  if (!g.secondaries.has(scope)) {
+    releaseRoute()
+
+    return () => undefined
+  }
+
+  // Re-check after the await: the guard above the retain ran before it, so a second submit for the
+  // same (route, session) can arrive while this one suspends and both pass it. Only the release
+  // stored in the map is ever invoked — releaseTerminalTurnLease does `g.turnLeases.get(key)?.()` —
+  // so the loser's hold would never be released and the socket could never be reclaimed.
+  if (g.turnLeases.has(key)) {
+    releaseRoute()
+
+    return () => undefined
+  }
+
   let released = false
 
   const release = () => {

From 8bbc02a02a4cecaae5a9b0cff4c6f6c30d5cf325 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 01:57:27 -0700
Subject: [PATCH 005/190] test(desktop): move the turn-lease tests to the end
 of the lifecycle file

Keeps the block off the shared anchor after afterEach that the sibling
prune-redial fix also extends, so the two PRs merge independently.
---
 .../gateway-connection-lifecycle.test.ts      | 128 +++++++++---------
 1 file changed, 64 insertions(+), 64 deletions(-)

diff --git a/apps/desktop/src/store/gateway-connection-lifecycle.test.ts b/apps/desktop/src/store/gateway-connection-lifecycle.test.ts
index b712b897a9..6b2c7fa382 100644
--- a/apps/desktop/src/store/gateway-connection-lifecycle.test.ts
+++ b/apps/desktop/src/store/gateway-connection-lifecycle.test.ts
@@ -106,70 +106,6 @@ afterEach(() => {
   delete (window as unknown as { hermesDesktop?: unknown }).hermesDesktop
 })
 
-describe('retainGatewayForSessionTurn', () => {
-  it('lets the next turn take a real hold after a turn that rode the primary socket', async () => {
-    // A routed prompt holds one lease per (route, runtime session) until the turn settles, and for a
-    // streaming turn only a Secondary's terminal-event listener ends it. When the route is served by
-    // the primary socket there is no Secondary, so a lease registered then can never be released —
-    // and the map is keyed per session, so it silently suppresses every later hold on that session,
-    // including after the route is dialed as a real secondary. The socket is then free to be reaped
-    // mid-turn, which is the interruption this whole mechanism exists to prevent.
-    installDesktop({ getConnection: vi.fn() }) // no getConnectionFor: nothing to hold, no Secondary
-
-    // The streaming turn deliberately does NOT release: its release would arrive as a terminal event.
-    await retainGatewayForSessionTurn('homelab', 'writer', 'session-1')
-
-    installDesktop({
-      getConnection: vi.fn(),
-      getConnectionFor: vi.fn(async ({ connectionId, profile }: { connectionId: string; profile: string }) =>
-        descriptorFor(connectionId, profile)
-      )
-    })
-    const dialedBefore = gatewayMocks.instances.length
-
-    await retainGatewayForSessionTurn('homelab', 'writer', 'session-1')
-
-    expect(gatewayMocks.instances.length).toBeGreaterThan(dialedBefore)
-  })
-
-  it('does not orphan a hold when two submits for one session race the dial', async () => {
-    // The duplicate-lease guard runs BEFORE the retain awaits, and the map is written after it, so
-    // two submits for the same (route, session) can both pass. Only the mapped release is ever
-    // invoked — releaseTerminalTurnLease does `g.turnLeases.get(key)?.()` — so the loser's hold is
-    // never released and the socket can never be reclaimed.
-    let openDial = () => {}
-
-    const dialed = new Promise<void>(resolve => {
-      openDial = resolve
-    })
-
-    gatewayMocks.connect.mockImplementationOnce(async () => dialed)
-    installDesktop({
-      getConnectionFor: vi.fn(async ({ connectionId, profile }: { connectionId: string; profile: string }) =>
-        descriptorFor(connectionId, profile)
-      )
-    })
-
-    const both = Promise.all([
-      retainGatewayForSessionTurn('homelab', 'writer', 'session-2'),
-      retainGatewayForSessionTurn('homelab', 'writer', 'session-2')
-    ])
-
-    openDial()
-    await both
-
-    // The terminal event releases the one lease the map holds, exactly as the gateway's own
-    // listener does; a leaked second hold would keep activeRequests above zero.
-    for (const handler of gatewayMocks.eventHandlers) {
-      handler({ session_id: 'session-2', type: 'session.reclaimed' })
-    }
-
-    pruneSecondaryGateways(new Set())
-
-    expect(gatewayMocks.instances[0].close).toHaveBeenCalled()
-  })
-})
-
 describe('a redial of the active route', () => {
   it('is not cancelled by a prune that runs while it is dialing', async () => {
     // Editing the connection you are viewing defers the redial until its lease drops, then
@@ -1029,3 +965,67 @@ it('does not let a removed connection repopulate the auth rejection', async () =
   await expect(requestGatewayForAgent('cloud', 'default', 'session.list')).rejects.toThrow()
   expect(getGatewayWsUrlFor).toHaveBeenCalledTimes(2)
 })
+
+describe('retainGatewayForSessionTurn', () => {
+  it('lets the next turn take a real hold after a turn that rode the primary socket', async () => {
+    // A routed prompt holds one lease per (route, runtime session) until the turn settles, and for a
+    // streaming turn only a Secondary's terminal-event listener ends it. When the route is served by
+    // the primary socket there is no Secondary, so a lease registered then can never be released —
+    // and the map is keyed per session, so it silently suppresses every later hold on that session,
+    // including after the route is dialed as a real secondary. The socket is then free to be reaped
+    // mid-turn, which is the interruption this whole mechanism exists to prevent.
+    installDesktop({ getConnection: vi.fn() }) // no getConnectionFor: nothing to hold, no Secondary
+
+    // The streaming turn deliberately does NOT release: its release would arrive as a terminal event.
+    await retainGatewayForSessionTurn('homelab', 'writer', 'session-1')
+
+    installDesktop({
+      getConnection: vi.fn(),
+      getConnectionFor: vi.fn(async ({ connectionId, profile }: { connectionId: string; profile: string }) =>
+        descriptorFor(connectionId, profile)
+      )
+    })
+    const dialedBefore = gatewayMocks.instances.length
+
+    await retainGatewayForSessionTurn('homelab', 'writer', 'session-1')
+
+    expect(gatewayMocks.instances.length).toBeGreaterThan(dialedBefore)
+  })
+
+  it('does not orphan a hold when two submits for one session race the dial', async () => {
+    // The duplicate-lease guard runs BEFORE the retain awaits, and the map is written after it, so
+    // two submits for the same (route, session) can both pass. Only the mapped release is ever
+    // invoked — releaseTerminalTurnLease does `g.turnLeases.get(key)?.()` — so the loser's hold is
+    // never released and the socket can never be reclaimed.
+    let openDial = () => {}
+
+    const dialed = new Promise<void>(resolve => {
+      openDial = resolve
+    })
+
+    gatewayMocks.connect.mockImplementationOnce(async () => dialed)
+    installDesktop({
+      getConnectionFor: vi.fn(async ({ connectionId, profile }: { connectionId: string; profile: string }) =>
+        descriptorFor(connectionId, profile)
+      )
+    })
+
+    const both = Promise.all([
+      retainGatewayForSessionTurn('homelab', 'writer', 'session-2'),
+      retainGatewayForSessionTurn('homelab', 'writer', 'session-2')
+    ])
+
+    openDial()
+    await both
+
+    // The terminal event releases the one lease the map holds, exactly as the gateway's own
+    // listener does; a leaked second hold would keep activeRequests above zero.
+    for (const handler of gatewayMocks.eventHandlers) {
+      handler({ session_id: 'session-2', type: 'session.reclaimed' })
+    }
+
+    pruneSecondaryGateways(new Set())
+
+    expect(gatewayMocks.instances[0].close).toHaveBeenCalled()
+  })
+})

From 3aa76b2ce51a484d7e09b0aadab38b32190ed16d Mon Sep 17 00:00:00 2001
From: KoNit-K <konit.block@protonmail.com>
Date: Thu, 17 Sep 2026 08:12:48 +0800
Subject: [PATCH 006/190] fix(kanban): report failed auto-heartbeats

---
 tests/tools/test_delegate_kanban_isolation.py | 26 +++++++++++++++++++
 tools/kanban_tools.py                         | 10 ++++---
 2 files changed, 32 insertions(+), 4 deletions(-)

diff --git a/tests/tools/test_delegate_kanban_isolation.py b/tests/tools/test_delegate_kanban_isolation.py
index 9d053d0570..960ae29864 100644
--- a/tests/tools/test_delegate_kanban_isolation.py
+++ b/tests/tools/test_delegate_kanban_isolation.py
@@ -174,6 +174,32 @@ def test_delegate_child_execute_code_env_bridges_contextvar_and_scrubs_kanban(
     assert env["HERMES_KANBAN_WORKSPACE"] == str(tmp_path / "parent-workspace")
 
 
+def test_auto_heartbeat_reports_failure_without_mutating_fenced_child_board(
+    monkeypatch,
+    tmp_path,
+):
+    """An inherited child marker fences both bridge writes instead of faking success."""
+    kb, tid, _workspace, _attachments_root = _make_running_kanban_task(monkeypatch, tmp_path)
+    from hermes_cli import kanban_db_connect as kbc
+    from tools import kanban_tools
+
+    conn = kbc.connect()
+    try:
+        task_before = kb.get_task(conn, tid)
+        events_before = kb.list_events(conn, tid)
+        monkeypatch.setenv("HERMES_DELEGATED_CHILD_CONTEXT", str(tmp_path / ".hermes"))
+        monkeypatch.setattr(kanban_tools, "_auto_heartbeat_last_attempt", 0.0)
+
+        assert kanban_tools.heartbeat_current_worker_from_env() is False
+
+        task_after = kb.get_task(conn, tid)
+        assert task_after.claim_expires == task_before.claim_expires
+        assert task_after.last_heartbeat_at == task_before.last_heartbeat_at
+        assert kb.list_events(conn, tid) == events_before
+    finally:
+        conn.close()
+
+
 def test_delegate_child_kanban_cli_cannot_delete_parent_board(
     monkeypatch,
     tmp_path,
diff --git a/tools/kanban_tools.py b/tools/kanban_tools.py
index 6390577f96..3fd9a58ced 100644
--- a/tools/kanban_tools.py
+++ b/tools/kanban_tools.py
@@ -450,8 +450,8 @@ _auto_heartbeat_last_attempt: float = 0.0
 
 
 def heartbeat_current_worker_from_env() -> bool:
-    """Claim extension + board heartbeat for the current worker; True iff a write was
-    attempted. ``HERMES_KANBAN_RUN_ID`` pins the run row so a reclaimed stale run is not
+    """Claim extension + board heartbeat for the current worker; True iff both writes
+    succeed. ``HERMES_KANBAN_RUN_ID`` pins the run row so a reclaimed stale run is not
     heartbeated; ``HERMES_KANBAN_CLAIM_LOCK`` absent -> default claimer (local workers)."""
     global _auto_heartbeat_last_attempt
     tid = os.environ.get("HERMES_KANBAN_TASK")
@@ -464,13 +464,15 @@ def heartbeat_current_worker_from_env() -> bool:
         with _board(None, quiet_close=True) as (kb, conn):
             ops = ((kb.heartbeat_claim, {"claimer": os.environ.get("HERMES_KANBAN_CLAIM_LOCK")}),
                    (kbd.heartbeat_worker, {"note": None, "expected_run_id": _worker_run_id(tid)}))
+            succeeded = True
             for fn, kwargs in ops:
                 op = fn.__name__
                 try:
-                    fn(conn, tid, **kwargs)
+                    succeeded = bool(fn(conn, tid, **kwargs)) and succeeded
                 except Exception:
                     logger.debug("auto-heartbeat: %s failed", op, exc_info=True)
-        return True
+                    succeeded = False
+        return succeeded
     except Exception:
         logger.debug("auto-heartbeat: bridge failed", exc_info=True)
         return False

From 63fb1a7d36d3593ea636bc8abb0d928cae33f1f0 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 00:44:46 -0700
Subject: [PATCH 007/190] fix(kanban): warn once when an inherited delegation
 fence rejects the worker's auto-heartbeat

A worker process that carries HERMES_DELEGATED_CHILD_CONTEXT next to its
HERMES_KANBAN_TASK is fenced by kanban_path_is_fenced's env-marker branch: both
auto-heartbeat writes raised PermissionError at DEBUG only, so the board showed a
worker that never beats while the process was alive (the salvaged commit already
made the return value honest, but _touch_activity ignores it). Log the refusal once
per process at WARNING with the cause, and skip the bridge for an in-process
delegate child BEFORE stamping the rate-limit window so a chatty child cannot starve
the worker's own heartbeat.

No self-write grant is added: the marker + TASK combination means "descendant, not
worker" by design (b578261584e, 8a8c3634e8d), and the only in-tree grant path,
kanban_db_dispatch._default_spawn, already pops the marker. The real-spawn grant
test now proves that from a dispatcher that itself carries the marker: the worker's
auto-heartbeat lands and its handoff completes.

Docs: worker guide notes the automatic claim extension and what the refusal warning
means.
---
 tests/cron/test_cron_kanban_env_isolation.py  | 12 ++++++++---
 tests/tools/test_delegate_kanban_isolation.py | 21 +++++++++++++++++--
 tools/kanban_tools.py                         | 21 ++++++++++++++++++-
 website/docs/user-guide/features/kanban.md    |  2 ++
 4 files changed, 50 insertions(+), 6 deletions(-)

diff --git a/tests/cron/test_cron_kanban_env_isolation.py b/tests/cron/test_cron_kanban_env_isolation.py
index 9e8badc95f..a177de9805 100644
--- a/tests/cron/test_cron_kanban_env_isolation.py
+++ b/tests/cron/test_cron_kanban_env_isolation.py
@@ -400,17 +400,23 @@ def test_dispatcher_grants_only_the_assigned_worker_scope(tmp_path, monkeypatch)
     root = str(Path(__file__).resolve().parents[2])
     worker.write_text(
         f"#!{sys.executable}\nimport sys, os, json;sys.path.insert(0, {root!r})\n"
-        "from tools.kanban_tools import _handle_complete\n"
-        f"result=_handle_complete({{'summary':'assigned worker'}});open({str(output)!r}, 'w').write(result)\n"
+        "from tools.kanban_tools import _handle_complete, heartbeat_current_worker_from_env\n"
+        "beat=heartbeat_current_worker_from_env()\n"
+        f"result=json.loads(_handle_complete({{'summary':'assigned worker'}}));result['beat']=beat\n"
+        f"open({str(output)!r}, 'w').write(json.dumps(result))\n"
     )
     worker.chmod(0o700)
     monkeypatch.setenv("HERMES_BIN", str(worker))
     # Building a new worker under an existing task must replace, not inherit, its scope.
     monkeypatch.setenv("HERMES_KANBAN_TASK", "prior-task")
+    # A dispatcher launched from an agent's shell carries the descendant fence itself; the worker it
+    # grants a task to must not (an inherited marker fences the worker's own heartbeat + handoff).
+    monkeypatch.setenv("HERMES_DELEGATED_CHILD_CONTEXT", str(tmp_path))
     pid = _default_spawn(task, str(tmp_path), board="default")
     assert pid is not None
     os.waitpid(pid, 0)  # windows-footgun: ok — Linux-only real dispatcher spawn
-    assert json.loads(output.read_text())["ok"]
+    result = json.loads(output.read_text())
+    assert result["ok"] and result["beat"] is True, result
     assert kb.get_task(conn, tid).status == "done"
     assert os.environ["HERMES_KANBAN_TASK"] == "prior-task"
     conn.close()
diff --git a/tests/tools/test_delegate_kanban_isolation.py b/tests/tools/test_delegate_kanban_isolation.py
index 960ae29864..28658cdfb1 100644
--- a/tests/tools/test_delegate_kanban_isolation.py
+++ b/tests/tools/test_delegate_kanban_isolation.py
@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import json
+import logging
 import os
 import shlex
 import sys
@@ -177,9 +178,13 @@ def test_delegate_child_execute_code_env_bridges_contextvar_and_scrubs_kanban(
 def test_auto_heartbeat_reports_failure_without_mutating_fenced_child_board(
     monkeypatch,
     tmp_path,
+    caplog,
 ):
-    """An inherited child marker fences both bridge writes instead of faking success."""
+    """An inherited child marker fences both bridge writes instead of faking success, and says
+    so once at WARNING (the DEBUG-only refusal hid a starving claim for a day). An in-process
+    delegate child stays fenced too, quietly, without consuming the worker's heartbeat window."""
     kb, tid, _workspace, _attachments_root = _make_running_kanban_task(monkeypatch, tmp_path)
+    from agent.delegation_context import delegated_child_context
     from hermes_cli import kanban_db_connect as kbc
     from tools import kanban_tools
 
@@ -189,8 +194,20 @@ def test_auto_heartbeat_reports_failure_without_mutating_fenced_child_board(
         events_before = kb.list_events(conn, tid)
         monkeypatch.setenv("HERMES_DELEGATED_CHILD_CONTEXT", str(tmp_path / ".hermes"))
         monkeypatch.setattr(kanban_tools, "_auto_heartbeat_last_attempt", 0.0)
+        monkeypatch.setattr(kanban_tools, "_auto_heartbeat_fence_warned", False)
 
-        assert kanban_tools.heartbeat_current_worker_from_env() is False
+        with caplog.at_level(logging.WARNING, logger="tools.kanban_tools"):
+            assert kanban_tools.heartbeat_current_worker_from_env() is False
+            monkeypatch.setattr(kanban_tools, "_auto_heartbeat_last_attempt", 0.0)
+            assert kanban_tools.heartbeat_current_worker_from_env() is False
+        fence_warnings = [r for r in caplog.records if "HERMES_DELEGATED_CHILD_CONTEXT" in r.getMessage()]
+        assert len(fence_warnings) == 1 and tid in fence_warnings[0].getMessage()
+
+        monkeypatch.delenv("HERMES_DELEGATED_CHILD_CONTEXT")
+        monkeypatch.setattr(kanban_tools, "_auto_heartbeat_last_attempt", 0.0)
+        with delegated_child_context("child-1"):
+            assert kanban_tools.heartbeat_current_worker_from_env() is False
+        assert kanban_tools._auto_heartbeat_last_attempt == 0.0
 
         task_after = kb.get_task(conn, tid)
         assert task_after.claim_expires == task_before.claim_expires
diff --git a/tools/kanban_tools.py b/tools/kanban_tools.py
index 3fd9a58ced..3292eadd38 100644
--- a/tools/kanban_tools.py
+++ b/tools/kanban_tools.py
@@ -447,17 +447,22 @@ def _goal_gate(tool_name: str, task, tid: str, evidence: str) -> None:
 # for the explicit tool which carries a model-supplied note.
 _AUTO_HEARTBEAT_MIN_INTERVAL_SECONDS = 60.0
 _auto_heartbeat_last_attempt: float = 0.0
+_auto_heartbeat_fence_warned = False
 
 
 def heartbeat_current_worker_from_env() -> bool:
     """Claim extension + board heartbeat for the current worker; True iff both writes
     succeed. ``HERMES_KANBAN_RUN_ID`` pins the run row so a reclaimed stale run is not
     heartbeated; ``HERMES_KANBAN_CLAIM_LOCK`` absent -> default claimer (local workers)."""
-    global _auto_heartbeat_last_attempt
+    global _auto_heartbeat_last_attempt, _auto_heartbeat_fence_warned
     tid = os.environ.get("HERMES_KANBAN_TASK")
     now = time.monotonic()
     if not tid or (now - _auto_heartbeat_last_attempt) < _AUTO_HEARTBEAT_MIN_INTERVAL_SECONDS:
         return False
+    if _is_delegated_child_context():
+        # An in-process delegate child's activity is not the worker's liveness; checked before
+        # stamping the window so a chatty child cannot starve the worker's own heartbeat.
+        return False
     _auto_heartbeat_last_attempt = now
     try:
         from hermes_cli import kanban_db_dispatch as kbd
@@ -469,6 +474,20 @@ def heartbeat_current_worker_from_env() -> bool:
                 op = fn.__name__
                 try:
                     succeeded = bool(fn(conn, tid, **kwargs)) and succeeded
+                except PermissionError as exc:
+                    # The board fence rejected the worker's own liveness write: this process
+                    # inherited HERMES_DELEGATED_CHILD_CONTEXT next to HERMES_KANBAN_TASK, so it is
+                    # a delegate descendant, not the dispatcher's worker (kanban_complete refuses
+                    # too). Loud once: at DEBUG the board just showed a worker that never beats.
+                    succeeded = False
+                    if not _auto_heartbeat_fence_warned:
+                        _auto_heartbeat_fence_warned = True
+                        logger.warning(
+                            "kanban auto-heartbeat for task %s refused (%s): this process carries "
+                            "HERMES_DELEGATED_CHILD_CONTEXT together with HERMES_KANBAN_TASK, so the board "
+                            "treats it as a delegate_task descendant and its claim will not be extended by "
+                            "activity. Only the dispatcher's own spawn grants worker scope; do not copy a "
+                            "worker's environment into a hand-launched process.", tid, exc)
                 except Exception:
                     logger.debug("auto-heartbeat: %s failed", op, exc_info=True)
                     succeeded = False
diff --git a/website/docs/user-guide/features/kanban.md b/website/docs/user-guide/features/kanban.md
index 96e36a702f..837799590e 100644
--- a/website/docs/user-guide/features/kanban.md
+++ b/website/docs/user-guide/features/kanban.md
@@ -553,6 +553,8 @@ Every profile that works kanban tasks automatically gets the worker lifecycle 
 3. Call `kanban_heartbeat(note="...")` every few minutes during long operations. **If your work may run longer than 1 hour, call `kanban_heartbeat` at least once an hour** — the dispatcher reclaims tasks that have been running past `kanban.dispatch_stale_timeout_seconds` (default 4 h) with no heartbeat in the last hour, on the assumption the worker crashed without cleanup. A reclaim is benign (the task goes back to `ready` for re-dispatch without a failure-counter tick) but you lose your current run's progress.
 4. Complete with `kanban_complete(summary="...", metadata={...})`, hand a code change off for same-card review with `kanban_request_review(summary="...")`, or `kanban_block(reason="...")` if stuck.
 
+Normal tool activity also extends the claim automatically (the worker mirrors its in-process liveness onto the board about once a minute). That bridge only works for a process the dispatcher spawned itself: a process that carries `HERMES_DELEGATED_CHILD_CONTEXT` next to `HERMES_KANBAN_TASK` (a `delegate_task` descendant, or a hand-launched copy of a worker's environment) is fenced from the board — its auto-heartbeat logs one `kanban auto-heartbeat for task … refused` warning and `kanban_complete` / `kanban_request_review` refuse. Fix the launch (let the dispatcher spawn the worker) rather than exporting the marker away.
+
 That final terminal board call (`kanban_complete` / `kanban_request_review` /
 `kanban_block`; reviewers end with `kanban_complete` or `kanban_request_changes`)
 is part of the worker

From e3e086689973a8cc78591cf9b7c053e910733bcf Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 04:02:58 -0700
Subject: [PATCH 008/190] fix(kanban): fence-warned flag reset must not mask
 the heartbeat assertion

`monkeypatch.setattr(kanban_tools, "_auto_heartbeat_fence_warned", False)` raised
AttributeError against a module without the flag, so a regression that dropped the
warn-once flag failed on the attribute probe instead of the user-visible symptom
(`heartbeat_current_worker_from_env()` returning True). `raising=False` lets the
symptom assertion bite (main's kanban_tools.py: AssertionError `assert True is False`).
---
 tests/tools/test_delegate_kanban_isolation.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/tests/tools/test_delegate_kanban_isolation.py b/tests/tools/test_delegate_kanban_isolation.py
index 28658cdfb1..71bc8a10da 100644
--- a/tests/tools/test_delegate_kanban_isolation.py
+++ b/tests/tools/test_delegate_kanban_isolation.py
@@ -194,7 +194,9 @@ def test_auto_heartbeat_reports_failure_without_mutating_fenced_child_board(
         events_before = kb.list_events(conn, tid)
         monkeypatch.setenv("HERMES_DELEGATED_CHILD_CONTEXT", str(tmp_path / ".hermes"))
         monkeypatch.setattr(kanban_tools, "_auto_heartbeat_last_attempt", 0.0)
-        monkeypatch.setattr(kanban_tools, "_auto_heartbeat_fence_warned", False)
+        # raising=False: a regression that drops the module flag must fail on the
+        # symptom assertions below, not on this attribute probe.
+        monkeypatch.setattr(kanban_tools, "_auto_heartbeat_fence_warned", False, raising=False)
 
         with caplog.at_level(logging.WARNING, logger="tools.kanban_tools"):
             assert kanban_tools.heartbeat_current_worker_from_env() is False

From 8f6f9e5b36da7435e26b79e7b35a4f235eb175ce Mon Sep 17 00:00:00 2001
From: funky-xamarin <30426178+Wenfengcheng@users.noreply.github.com>
Date: Wed, 16 Sep 2026 15:18:50 +0800
Subject: [PATCH 009/190] fix(cron): order status next run by actual instant

---
 hermes_cli/cron.py                            | 14 +++++-
 tests/hermes_cli/test_cron_status_next_run.py | 47 +++++++++++++++++++
 2 files changed, 59 insertions(+), 2 deletions(-)
 create mode 100644 tests/hermes_cli/test_cron_status_next_run.py

diff --git a/hermes_cli/cron.py b/hermes_cli/cron.py
index 02c7a94a18..4de42aa0dd 100644
--- a/hermes_cli/cron.py
+++ b/hermes_cli/cron.py
@@ -466,10 +466,20 @@ def _print_active_jobs_summary(jobs) -> None:
     if not jobs:
         print("  No active jobs")
         return
-    next_runs = [j.get("next_run_at") for j in jobs if j.get("next_run_at")]
+    from datetime import timezone
+    from cron.jobs import _parse_aware
+
+    next_runs = []
+    for job in jobs:
+        raw = job.get("next_run_at")
+        parsed = _parse_aware(raw)
+        if parsed is not None:
+            # A shared ZoneInfo compares wall times across a DST fold; use UTC
+            # for ordering, but keep the stored timestamp for display.
+            next_runs.append((parsed.astimezone(timezone.utc), raw))
     print(f"  {len(jobs)} active job(s)")
     if next_runs:
-        print(f"  Next run: {min(next_runs)}")
+        print(f"  Next run: {min(next_runs, key=lambda run: run[0])[1]}")
     # Post-downtime late fires show at status level, not just per-job in `cron list`.
     late = [j for j in jobs if isinstance(j.get("last_dispatch"), dict)
             and j["last_dispatch"].get("kind") in ("late", "catch_up")]
diff --git a/tests/hermes_cli/test_cron_status_next_run.py b/tests/hermes_cli/test_cron_status_next_run.py
new file mode 100644
index 0000000000..b73370499a
--- /dev/null
+++ b/tests/hermes_cli/test_cron_status_next_run.py
@@ -0,0 +1,47 @@
+"""Cron status orders persisted next runs by instant, including a DST fold."""
+
+from datetime import datetime
+from zoneinfo import ZoneInfo
+
+import pytest
+
+from cron import jobs as job_store
+from hermes_cli.cron import _print_active_jobs_summary
+
+
+@pytest.mark.parametrize("later,earlier", [
+    ("2026-11-01T01:15:00-05:00", "2026-11-01T01:45:00-04:00"),
+    ("2026-11-02T09:00:00-05:00", "2026-11-02T08:00:00-05:00"),
+    ("2026-11-02T08:00:00-05:00", "2026-11-02T12:30:00+00:00"),
+])
+def test_status_earliest_persisted_instant(later, earlier, monkeypatch, capsys):
+    # Only freeze the clock: creation, persistence, normalization and listing are real.
+    now = datetime(2026, 10, 31, tzinfo=ZoneInfo("America/New_York"))
+    monkeypatch.setattr(job_store, "_hermes_now", lambda: now)
+    late_job = job_store.create_job(prompt="later", schedule=later)
+    early_job = job_store.create_job(prompt="earlier", schedule=earlier)
+    jobs = job_store.list_jobs()
+    assert {job["id"] for job in jobs} == {late_job["id"], early_job["id"]}
+    expected = next(job["next_run_at"] for job in jobs if job["id"] == early_job["id"])
+
+    _print_active_jobs_summary(jobs)
+
+    out = capsys.readouterr().out
+    assert "2 active job(s)" in out
+    assert f"Next run: {expected}\n" in out
+    assert job_store.list_jobs() == jobs  # Rendering never reschedules a job.
+
+
+@pytest.mark.parametrize("jobs,expected", [
+    ([], "  No active jobs\n"),
+    ([{}, {"next_run_at": None}, {"next_run_at": ""}], "  3 active job(s)\n"),
+    ([{"next_run_at": "bad"}, {"next_run_at": 123}], "  2 active job(s)\n"),
+    ([{"next_run_at": "bad"}, {"next_run_at": "2026-11-01T06:15:00Z"}],
+     "  2 active job(s)\n  Next run: 2026-11-01T06:15:00Z\n"),
+    ([{"next_run_at": "2026-11-01T06:15:00Z"},
+      {"next_run_at": "2026-11-01T01:15:00-05:00"}],
+     "  2 active job(s)\n  Next run: 2026-11-01T06:15:00Z\n"),
+])
+def test_status_missing_invalid_and_equivalent_instants(jobs, expected, capsys):
+    _print_active_jobs_summary(jobs)
+    assert capsys.readouterr().out == expected

From a20a71a3e3f1a507b40b94ce48784faeccc4a97f Mon Sep 17 00:00:00 2001
From: liuhao1024 <sunsky.lau@gmail.com>
Date: Fri, 18 Sep 2026 02:14:35 +0800
Subject: [PATCH 010/190] fix(cli): flag overdue next_run_at and stale ticker
 in cron status

When the scheduler host dies, a job's next_run_at is stranded in the
past and `hermes cron status` still printed it as an upcoming
"Next run", hiding the outage (#114309): the report's only signal was
the gateway line, while the schedule line kept presenting a 7h-old
timestamp as future.

- _print_active_jobs_summary: when the earliest next_run_at already
  passed, print a loud OVERDUE line (age + scheduler question) instead
  of a bare "Next run: <past ts>"; future timestamps render unchanged.
- cron_status gateway-down branch: when ticker_heartbeat is stale,
  print when the scheduler last ticked so the frozen state is
  first-class visible.

Fixes #114309
---
 hermes_cli/cron.py            | 36 ++++++++++++++++++++++++++-
 tests/hermes_cli/test_cron.py | 46 +++++++++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+), 1 deletion(-)

diff --git a/hermes_cli/cron.py b/hermes_cli/cron.py
index 4de42aa0dd..fc15702fc5 100644
--- a/hermes_cli/cron.py
+++ b/hermes_cli/cron.py
@@ -4,6 +4,7 @@ import contextlib
 import json
 import re
 import sys
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, Iterable, List, Optional
 
@@ -96,6 +97,21 @@ def _dispatch_kind_label(kind) -> Optional[str]:
     return {"catch_up": "catch-up after missed fire", "late": "late"}.get(kind)
 
 
+def _next_run_overdue_seconds(next_run_at: str) -> Optional[float]:
+    """Seconds the timestamp has already been in the past; None if malformed.
+
+    next_run_at is written as timezone-aware ISO strings; a naive value only ever comes
+    from a hand-edited jobs.json and is read as UTC.
+    """
+    try:
+        dt = datetime.fromisoformat(str(next_run_at).replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return (datetime.now(timezone.utc) - dt).total_seconds()
+
+
 def _dispatch_display(dispatch: dict) -> Optional[str]:
     """One-line scheduled-vs-actual dispatch summary; None when the stamp is malformed.
 
@@ -442,6 +458,15 @@ def cron_status():
         else:
             print(color("✗ Gateway is not running — cron jobs will NOT fire", Colors.RED))
             active = get_active_profile_name()
+            # When scheduling last worked before the host went away: without this, a
+            # 7h-overdue job still reads as a normal upcoming "Next run" (#114309).
+            with contextlib.suppress(Exception):
+                from cron.jobs import TICKER_INTERVAL_SECONDS, get_ticker_heartbeat_age
+                hb_age = get_ticker_heartbeat_age()
+                if hb_age is not None and hb_age > TICKER_INTERVAL_SECONDS * 3 + 20:
+                    print(color("  Scheduler last ticked "
+                                f"{_format_lateness(hb_age)} ago — jobs that came due "
+                                "since then have not fired.", Colors.YELLOW))
             print("\n  To enable automatic execution for this profile:\n"
                   "    hermes gateway install    # Install as a user service\n"
                   "    sudo hermes gateway install --system  # Linux servers: boot-time system service\n"
@@ -479,7 +504,16 @@ def _print_active_jobs_summary(jobs) -> None:
             next_runs.append((parsed.astimezone(timezone.utc), raw))
     print(f"  {len(jobs)} active job(s)")
     if next_runs:
-        print(f"  Next run: {min(next_runs, key=lambda run: run[0])[1]}")
+        earliest = min(next_runs, key=lambda run: run[0])[1]
+        overdue_by = _next_run_overdue_seconds(earliest)
+        if overdue_by is not None and overdue_by > 0:
+            # #114309: a dead scheduler leaves next_run_at stranded in the past; presenting it
+            # as an upcoming "Next run" hides the outage.
+            print(color(f"  ⚠ Next run {earliest} is OVERDUE — passed "
+                        f"{_format_lateness(overdue_by)} ago but the job has not fired "
+                        "(is the scheduler running?)", Colors.YELLOW))
+        else:
+            print(f"  Next run: {earliest}")
     # Post-downtime late fires show at status level, not just per-job in `cron list`.
     late = [j for j in jobs if isinstance(j.get("last_dispatch"), dict)
             and j["last_dispatch"].get("kind") in ("late", "catch_up")]
diff --git a/tests/hermes_cli/test_cron.py b/tests/hermes_cli/test_cron.py
index 96d4e63dd9..8680689340 100644
--- a/tests/hermes_cli/test_cron.py
+++ b/tests/hermes_cli/test_cron.py
@@ -1,7 +1,9 @@
 """Tests for hermes_cli.cron command handling."""
 
 import argparse
+import time
 from argparse import Namespace
+from datetime import datetime, timedelta, timezone
 from types import SimpleNamespace
 
 import pytest
@@ -590,6 +592,50 @@ class TestSlashCronListLastStatus:
         assert "(ok)" in out
 
 
+class TestStatusSurfacesDeadScheduler:
+    """#114309 — with the ticker dead and a job's next_run_at stranded in the past, `cron
+    status` must not present the stale timestamp as an upcoming "Next run": flag it as
+    OVERDUE and say when the scheduler last ticked."""
+
+    def _dead_gateway(self, monkeypatch):
+        monkeypatch.setattr("hermes_cli.gateway.find_gateway_pids", lambda: [])
+        monkeypatch.setattr(
+            "hermes_cli.gateway.named_profile_served_by_running_multiplexer", lambda: None
+        )
+        monkeypatch.setattr("gateway.status.is_gateway_runtime_lock_active", lambda: False)
+
+    def test_overdue_next_run_and_stale_heartbeat_are_loud(
+        self, tmp_cron_dir, capsys, monkeypatch
+    ):
+        job = create_job(prompt="Hourly", schedule="every 60m")
+        self._dead_gateway(monkeypatch)
+        overdue = datetime.now(timezone.utc) - timedelta(hours=7)
+        jobs = load_jobs()
+        jobs[[j["id"] for j in jobs].index(job["id"])]["next_run_at"] = overdue.isoformat()
+        save_jobs(jobs)
+        (tmp_cron_dir / "cron" / "ticker_heartbeat").write_text(str(time.time() - 25 * 3600))
+
+        cron_command(Namespace(cron_command="status"))
+
+        out = capsys.readouterr().out
+        assert "Gateway is not running" in out
+        assert "Scheduler last ticked" in out
+        assert "OVERDUE" in out
+        # The stale timestamp must no longer read as an upcoming run.
+        assert "Next run:" not in out
+
+    def test_future_next_run_stays_plain(self, tmp_cron_dir, capsys, monkeypatch):
+        create_job(prompt="Hourly", schedule="every 60m")
+        self._dead_gateway(monkeypatch)
+
+        cron_command(Namespace(cron_command="status"))
+
+        out = capsys.readouterr().out
+        assert "Next run:" in out
+        assert "OVERDUE" not in out
+        assert "Scheduler last ticked" not in out
+
+
 class TestSlashCronRunSkipped:
     """``/cron run`` on a job whose claim is refused (paused here; a live claim held by another
     run is the same shape) must print the refusal, never ``Triggered … next scheduler tick``."""

From f9683271448162920e12c6e9a4a07130a3113409 Mon Sep 17 00:00:00 2001
From: liuhao1024 <sunsky.lau@gmail.com>
Date: Fri, 18 Sep 2026 04:25:26 +0800
Subject: [PATCH 011/190] fix(cli): share the doctor's overdue grace in cron
 status

Address review feedback: `cron doctor` tolerates a 15-minute grace
window (_OVERDUE_GRACE_SECONDS) before calling a next_run_at overdue,
but the new status OVERDUE line fired on any `scheduled < now`, so a
job a few minutes behind the ticker's own cadence could flash OVERDUE
while doctor still called the same job healthy.

- Gate the status OVERDUE line on the same _OVERDUE_GRACE_SECONDS so
  status, list, and doctor tell one consistent story.
- Reuse _next_run_overdue_seconds inside _next_run_overdue_issue,
  dropping the duplicated timestamp parsing.
- Add a regression test: a next_run_at 5 minutes in the past stays a
  plain 'Next run' line.
---
 hermes_cli/cron.py            | 17 ++++++++---------
 tests/hermes_cli/test_cron.py | 17 +++++++++++++++++
 2 files changed, 25 insertions(+), 9 deletions(-)

diff --git a/hermes_cli/cron.py b/hermes_cli/cron.py
index fc15702fc5..bb1cc84e1b 100644
--- a/hermes_cli/cron.py
+++ b/hermes_cli/cron.py
@@ -506,9 +506,11 @@ def _print_active_jobs_summary(jobs) -> None:
     if next_runs:
         earliest = min(next_runs, key=lambda run: run[0])[1]
         overdue_by = _next_run_overdue_seconds(earliest)
-        if overdue_by is not None and overdue_by > 0:
+        if overdue_by is not None and overdue_by > _OVERDUE_GRACE_SECONDS:
             # #114309: a dead scheduler leaves next_run_at stranded in the past; presenting it
-            # as an upcoming "Next run" hides the outage.
+            # as an upcoming "Next run" hides the outage. Same 15m grace as `cron doctor`
+            # (_OVERDUE_GRACE_SECONDS) so a job a few minutes behind the ticker's own
+            # cadence doesn't flash OVERDUE here while doctor still calls it healthy.
             print(color(f"  ⚠ Next run {earliest} is OVERDUE — passed "
                         f"{_format_lateness(overdue_by)} ago but the job has not fired "
                         "(is the scheduler running?)", Colors.YELLOW))
@@ -552,19 +554,16 @@ def _script_health_issue(script: str) -> Optional[str]:
 
 # A busy tick can push dispatch a few minutes late; only a next_run_at parked well in the past
 # means the job is silently not firing (ticker dead, gateway down, wedged fire-claim).
+# `cron status`'s OVERDUE line shares this grace so status, list, and doctor tell one
+# consistent story about when a job counts as overdue.
 _OVERDUE_GRACE_SECONDS = 15 * 60
 
 
 def _next_run_overdue_issue(next_run: str) -> Optional[str]:
     """Issue string when ``next_run_at`` is parked in the past."""
-    from datetime import datetime, timezone
-    try:
-        dt = datetime.fromisoformat(next_run.replace("Z", "+00:00"))
-    except ValueError:
+    overdue_s = _next_run_overdue_seconds(next_run)
+    if overdue_s is None:
         return f"next_run_at is not a valid timestamp: {next_run!r}"
-    if dt.tzinfo is None:
-        dt = dt.replace(tzinfo=timezone.utc)
-    overdue_s = (datetime.now(timezone.utc) - dt).total_seconds()
     if overdue_s <= _OVERDUE_GRACE_SECONDS:
         return None
     amount = f"{overdue_s / 3600:.1f}h" if overdue_s >= 3600 else f"{overdue_s / 60:.0f}m"
diff --git a/tests/hermes_cli/test_cron.py b/tests/hermes_cli/test_cron.py
index 8680689340..0df0fe05c9 100644
--- a/tests/hermes_cli/test_cron.py
+++ b/tests/hermes_cli/test_cron.py
@@ -635,6 +635,23 @@ class TestStatusSurfacesDeadScheduler:
         assert "OVERDUE" not in out
         assert "Scheduler last ticked" not in out
 
+    def test_overdue_within_doctor_grace_stays_plain(self, tmp_cron_dir, capsys, monkeypatch):
+        # status shares `cron doctor`'s 15-minute grace (_OVERDUE_GRACE_SECONDS): a job only
+        # a few minutes behind the ticker's own cadence is not an outage yet, and status must
+        # not flash OVERDUE while doctor calls the same job healthy.
+        job = create_job(prompt="Hourly", schedule="every 60m")
+        self._dead_gateway(monkeypatch)
+        within_grace = datetime.now(timezone.utc) - timedelta(minutes=5)
+        jobs = load_jobs()
+        jobs[[j["id"] for j in jobs].index(job["id"])]["next_run_at"] = within_grace.isoformat()
+        save_jobs(jobs)
+
+        cron_command(Namespace(cron_command="status"))
+
+        out = capsys.readouterr().out
+        assert "Next run:" in out
+        assert "OVERDUE" not in out
+
 
 class TestSlashCronRunSkipped:
     """``/cron run`` on a job whose claim is refused (paused here; a live claim held by another

From eddf7283e4b178ddca0dea37b1a5744f9ee8e992 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 00:52:39 -0700
Subject: [PATCH 012/190] fix(cron): label overdue next runs in cron list,
 dashboard and Desktop; one parser for the instant
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`hermes cron list`, the web dashboard Cron page and the Desktop cron panel/sidebar all
rendered a `next_run_at` parked hours in the past as an ordinary upcoming "Next run" —
the only user-visible trace of a scheduler that stopped ticking (#114309). Every
surface now labels a slot past `cron doctor`'s 15-minute grace as overdue (CLI
`Overdue:` row with the lateness, web `Overdue since`, Desktop `Overdue since` label
on the detail panel and sidebar meta) while paused/disabled/completed jobs keep the
plain label because they are not expected to fire.

The CLI's overdue check now parses through `cron.jobs._parse_aware` and `hermes_time.now`
so status/list/doctor and the ticker agree on the instant (mixed offsets, DST folds,
legacy naive stamps read as system-local like the scheduler does), and both the
ordering and the subtraction normalise to UTC: Python compares same-tzinfo datetimes by
wall clock, which is wrong across a DST fold. Status still orders the soonest run by
instant (#113874) and prints the stored stamp.

Tests: the salvaged status tests are trimmed to two invariants (overdue + stale
heartbeat is loud on status AND list; within-grace stays plain on both), the DST-fold
ordering tests freeze the CLI clock as well so their 2026-11 fixtures never start
reading as overdue, and one vitest each pins the web and Desktop helpers.

Co-authored-by: funky-xamarin <30426178+Wenfengcheng@users.noreply.github.com>
Co-authored-by: joaomarcos <joaomarcosdias444@gmail.com>
---
 .../app/chat/sidebar/cron-jobs-section.tsx    | 10 +++-
 .../src/app/cron/cron-job-model.test.ts       | 19 +++++++
 apps/desktop/src/app/cron/index.tsx           |  7 ++-
 apps/desktop/src/app/cron/job-state.ts        | 25 +++++++++
 apps/desktop/src/i18n/en.ts                   |  2 +
 apps/desktop/src/i18n/types.ts                |  1 +
 hermes_cli/cron.py                            | 55 ++++++++++++-------
 tests/hermes_cli/test_cron.py                 | 54 ++++++++----------
 tests/hermes_cli/test_cron_status_next_run.py | 15 +++--
 web/src/i18n/en.ts                            |  2 +
 web/src/i18n/types.ts                         |  1 +
 web/src/lib/cron-job.test.ts                  | 20 +++++++
 web/src/lib/cron-job.ts                       | 20 +++++++
 web/src/pages/CronPage.tsx                    | 16 +++++-
 website/docs/user-guide/features/cron.md      |  2 +
 15 files changed, 187 insertions(+), 62 deletions(-)

diff --git a/apps/desktop/src/app/chat/sidebar/cron-jobs-section.tsx b/apps/desktop/src/app/chat/sidebar/cron-jobs-section.tsx
index b8feea2416..2e6575f43c 100644
--- a/apps/desktop/src/app/chat/sidebar/cron-jobs-section.tsx
+++ b/apps/desktop/src/app/chat/sidebar/cron-jobs-section.tsx
@@ -20,7 +20,7 @@ import { notify, notifyError } from '@/store/notifications'
 import { $selectedStoredSessionId } from '@/store/session'
 import type { CronJob } from '@/types/hermes'
 
-import { jobState, jobTitle, STATE_DOT } from '../../cron/job-state'
+import { jobState, jobTitle, nextRunOverdueMs, STATE_DOT } from '../../cron/job-state'
 import { SidebarPanelLabel } from '../../shell/sidebar-label'
 
 import { SidebarRowBody, SidebarRowLabel, SidebarRowLead, SidebarRowShell } from './chrome'
@@ -244,7 +244,13 @@ function CronJobSidebarRow({
   const label = jobTitle(job)
   const isPaused = state === 'paused'
 
-  const meta = INACTIVE_STATES.has(state) ? (c.states[state] ?? state) : next !== null ? relativeTime(next, nowMs) : '—'
+  const overdue = nextRunOverdueMs(job, nowMs) !== null
+
+  const meta = INACTIVE_STATES.has(state)
+    ? (c.states[state] ?? state)
+    : next !== null
+      ? `${overdue ? `${c.overdueSince.replace(/:$/, '')} ` : ''}${relativeTime(next, nowMs)}`
+      : '—'
 
   // Pause/resume and delete aren't threaded through the sidebar's prop chain, so
   // drive them against the shared $cronJobs atom directly (same path the cron
diff --git a/apps/desktop/src/app/cron/cron-job-model.test.ts b/apps/desktop/src/app/cron/cron-job-model.test.ts
index c76df80abf..97af7ac7b9 100644
--- a/apps/desktop/src/app/cron/cron-job-model.test.ts
+++ b/apps/desktop/src/app/cron/cron-job-model.test.ts
@@ -8,6 +8,7 @@ import {
   toggleCronDeliveryTarget,
   validateCronEditor
 } from './cron-job-model'
+import { nextRunOverdueMs } from './job-state'
 
 describe('jobIsScriptOnly', () => {
   it('is true when no_agent is set and a script is present', () => {
@@ -143,3 +144,21 @@ describe('cronEditorUpdates', () => {
     expect('provider' in updates).toBe(false)
   })
 })
+
+describe('nextRunOverdueMs', () => {
+  const now = Date.parse('2026-09-17T20:35:00+04:00')
+
+  it('flags an active job whose stored slot sits past the scheduler grace (#114309)', () => {
+    const job = { enabled: true, next_run_at: '2026-09-17T13:34:18+04:00', state: 'scheduled' }
+
+    expect(nextRunOverdueMs(job, now)).toBe(now - Date.parse(job.next_run_at))
+  })
+
+  it('keeps upcoming, within-grace, paused and unparseable slots as plain next runs', () => {
+    expect(nextRunOverdueMs({ enabled: true, next_run_at: '2026-09-17T21:00:00+04:00' }, now)).toBeNull()
+    expect(nextRunOverdueMs({ enabled: true, next_run_at: '2026-09-17T20:30:00+04:00' }, now)).toBeNull()
+    expect(nextRunOverdueMs({ enabled: true, next_run_at: '2026-09-17T13:34:18+04:00', state: 'paused' }, now)).toBeNull()
+    expect(nextRunOverdueMs({ enabled: false, next_run_at: '2026-09-17T13:34:18+04:00' }, now)).toBeNull()
+    expect(nextRunOverdueMs({ enabled: true, next_run_at: 'not-a-date' }, now)).toBeNull()
+  })
+})
diff --git a/apps/desktop/src/app/cron/index.tsx b/apps/desktop/src/app/cron/index.tsx
index 9bbf2e44ff..cfd9f9138c 100644
--- a/apps/desktop/src/app/cron/index.tsx
+++ b/apps/desktop/src/app/cron/index.tsx
@@ -83,7 +83,7 @@ import {
   toggleCronDeliveryTarget,
   validateCronEditor
 } from './cron-job-model'
-import { jobState, jobTitle, STATE_DOT } from './job-state'
+import { jobState, jobTitle, nextRunOverdueMs, STATE_DOT } from './job-state'
 
 const DEFAULT_DELIVER = 'local'
 
@@ -818,7 +818,10 @@ function CronJobDetail({ busy, c, job, onEdit, onOpenSession, onPauseResume, onT
           rows={[
             { label: c.frequencyLabel, value: jobScheduleDisplay(job) },
             { label: c.last.replace(/:$/, ''), value: formatTime(job.last_run_at) },
-            { label: c.next.replace(/:$/, ''), value: formatTime(job.next_run_at) },
+            {
+              label: (nextRunOverdueMs(job) === null ? c.next : c.overdueSince).replace(/:$/, ''),
+              value: formatTime(job.next_run_at)
+            },
             { label: c.deliverLabel, value: c.deliveryLabels[deliver] ?? deliver },
             ...(modelOverride ? [{ label: c.modelLabel, value: modelOverride }] : [])
           ]}
diff --git a/apps/desktop/src/app/cron/job-state.ts b/apps/desktop/src/app/cron/job-state.ts
index b7dd139cc4..bf7348f67d 100644
--- a/apps/desktop/src/app/cron/job-state.ts
+++ b/apps/desktop/src/app/cron/job-state.ts
@@ -27,3 +27,28 @@ export function jobTitle(job: CronJob): string {
 
   return pick(job.name) || clip(pick(job.prompt)) || clip(pick(job.script)) || job.id || 'Cron job'
 }
+
+// Mirrors hermes_cli/cron.py `_OVERDUE_GRACE_SECONDS`: a busy tick can dispatch a few minutes late.
+export const NEXT_RUN_OVERDUE_GRACE_MS = 15 * 60 * 1000
+
+// Milliseconds a job's stored next_run_at has sat in the past beyond that grace, or null when
+// the slot is upcoming, within grace, unparseable, or the job is not expected to fire. A slot
+// parked in the past is the only user-visible trace of a dead scheduler (#114309), so no
+// surface may present it as an upcoming "Next".
+export function nextRunOverdueMs(job: Pick<CronJob, 'enabled' | 'next_run_at' | 'state'>, nowMs = Date.now()): null | number {
+  const state = jobState(job as CronJob)
+
+  if (state === 'paused' || state === 'completed' || state === 'disabled' || !job.next_run_at) {
+    return null
+  }
+
+  const at = Date.parse(job.next_run_at)
+
+  if (Number.isNaN(at)) {
+    return null
+  }
+
+  const overdue = nowMs - at
+
+  return overdue > NEXT_RUN_OVERDUE_GRACE_MS ? overdue : null
+}
diff --git a/apps/desktop/src/i18n/en.ts b/apps/desktop/src/i18n/en.ts
index fcd287befc..f54b272c54 100644
--- a/apps/desktop/src/i18n/en.ts
+++ b/apps/desktop/src/i18n/en.ts
@@ -2632,6 +2632,8 @@ export const en: Translations = {
     emptyTitleSearch: 'No matches',
     last: 'Last:',
     next: 'Next:',
+    // Replaces `next` when the stored next_run_at is already past the scheduler grace (#114309).
+    overdueSince: 'Overdue since:',
     noRuns: 'No runs yet',
     manage: 'Manage',
     showRuns: 'Show runs',
diff --git a/apps/desktop/src/i18n/types.ts b/apps/desktop/src/i18n/types.ts
index 7429e74e96..30c2474084 100644
--- a/apps/desktop/src/i18n/types.ts
+++ b/apps/desktop/src/i18n/types.ts
@@ -2254,6 +2254,7 @@ export interface Translations {
     emptyTitleSearch: string
     last: string
     next: string
+    overdueSince: string
     noRuns: string
     manage: string
     showRuns: string
diff --git a/hermes_cli/cron.py b/hermes_cli/cron.py
index bb1cc84e1b..fa459339d2 100644
--- a/hermes_cli/cron.py
+++ b/hermes_cli/cron.py
@@ -4,7 +4,7 @@ import contextlib
 import json
 import re
 import sys
-from datetime import datetime, timezone
+from datetime import timezone
 from pathlib import Path
 from typing import Any, Dict, Iterable, List, Optional
 
@@ -97,19 +97,35 @@ def _dispatch_kind_label(kind) -> Optional[str]:
     return {"catch_up": "catch-up after missed fire", "late": "late"}.get(kind)
 
 
-def _next_run_overdue_seconds(next_run_at: str) -> Optional[float]:
-    """Seconds the timestamp has already been in the past; None if malformed.
+def _next_run_overdue_seconds(next_run_at: Any) -> Optional[float]:
+    """Seconds the stored ``next_run_at`` is already in the past (negative while still
+    upcoming); None when it is not a parseable ISO timestamp.
 
-    next_run_at is written as timezone-aware ISO strings; a naive value only ever comes
-    from a hand-edited jobs.json and is read as UTC.
+    Parses through the scheduler's own ``_parse_aware`` so the CLI and the ticker agree on
+    the instant (mixed UTC offsets, DST folds, legacy naive stamps read as system-local).
     """
-    try:
-        dt = datetime.fromisoformat(str(next_run_at).replace("Z", "+00:00"))
-    except ValueError:
+    from cron.jobs import _parse_aware
+    from hermes_time import now
+    dt = _parse_aware(next_run_at)
+    if dt is None:
         return None
-    if dt.tzinfo is None:
-        dt = dt.replace(tzinfo=timezone.utc)
-    return (datetime.now(timezone.utc) - dt).total_seconds()
+    # Same-tzinfo subtraction is wall-clock arithmetic in Python; compare instants.
+    return (now().astimezone(timezone.utc) - dt.astimezone(timezone.utc)).total_seconds()
+
+
+def _next_run_row(job: Dict[str, Any]) -> tuple[str, str]:
+    """``("Next run" | "Overdue", value)`` for one job.
+
+    A stamp parked past `cron doctor`'s grace on a job that is supposed to fire is the only
+    user-visible trace of a dead scheduler; never present it as an upcoming run (#114309).
+    """
+    stamp = job.get("next_run_at", "?")
+    overdue_s = _next_run_overdue_seconds(stamp)
+    if (overdue_s is None or overdue_s <= _OVERDUE_GRACE_SECONDS
+            or not job.get("enabled", True) or job.get("state") in {"paused", "completed"}):
+        return ("Next run", stamp)
+    return ("Overdue", color(f"{stamp}  ({_format_lateness(overdue_s)} ago — the job has not fired; "
+                                   "is the scheduler running?)", Colors.YELLOW))
 
 
 def _dispatch_display(dispatch: dict) -> Optional[str]:
@@ -223,7 +239,7 @@ def _job_rows(job: Dict[str, Any]) -> List[tuple[str, str]]:
         ("Name", job.get("name", "(unnamed)")),
         ("Schedule", job.get("schedule_display", job.get("schedule", {}).get("value", "?"))),
         ("Repeat", f"{repeat_info.get('completed', 0)}/{repeat_times}" if repeat_times else "∞"),
-        ("Next run", job.get("next_run_at", "?")),
+        _next_run_row(job),
         ("Deliver", deliver if isinstance(deliver, str) else ", ".join(deliver)),
     ] + [(label, value) for label, value in optional if value]
 
@@ -491,17 +507,14 @@ def _print_active_jobs_summary(jobs) -> None:
     if not jobs:
         print("  No active jobs")
         return
-    from datetime import timezone
     from cron.jobs import _parse_aware
 
-    next_runs = []
-    for job in jobs:
-        raw = job.get("next_run_at")
-        parsed = _parse_aware(raw)
-        if parsed is not None:
-            # A shared ZoneInfo compares wall times across a DST fold; use UTC
-            # for ordering, but keep the stored timestamp for display.
-            next_runs.append((parsed.astimezone(timezone.utc), raw))
+    # Stored stamps carry mixed UTC offsets (an interval job keeps last_run_at's offset, a cron
+    # job its configured zone), so order by instant, never by ISO text; display the stored stamp.
+    # `_parse_aware` hands back one shared ZoneInfo, and Python compares same-tzinfo datetimes
+    # by wall clock (wrong across a DST fold) — normalise to UTC before ordering.
+    next_runs = [(parsed.astimezone(timezone.utc), j["next_run_at"]) for j in jobs
+                 if (parsed := _parse_aware(j.get("next_run_at"))) is not None]
     print(f"  {len(jobs)} active job(s)")
     if next_runs:
         earliest = min(next_runs, key=lambda run: run[0])[1]
diff --git a/tests/hermes_cli/test_cron.py b/tests/hermes_cli/test_cron.py
index 0df0fe05c9..15c1104df9 100644
--- a/tests/hermes_cli/test_cron.py
+++ b/tests/hermes_cli/test_cron.py
@@ -594,8 +594,8 @@ class TestSlashCronListLastStatus:
 
 class TestStatusSurfacesDeadScheduler:
     """#114309 — with the ticker dead and a job's next_run_at stranded in the past, `cron
-    status` must not present the stale timestamp as an upcoming "Next run": flag it as
-    OVERDUE and say when the scheduler last ticked."""
+    status` / `cron list` must not present the stale timestamp as an upcoming "Next run":
+    flag it as overdue and say when the scheduler last ticked."""
 
     def _dead_gateway(self, monkeypatch):
         monkeypatch.setattr("hermes_cli.gateway.find_gateway_pids", lambda: [])
@@ -604,36 +604,30 @@ class TestStatusSurfacesDeadScheduler:
         )
         monkeypatch.setattr("gateway.status.is_gateway_runtime_lock_active", lambda: False)
 
+    def _park_next_run(self, job_id, when):
+        jobs = load_jobs()
+        jobs[[j["id"] for j in jobs].index(job_id)]["next_run_at"] = when.isoformat()
+        save_jobs(jobs)
+
     def test_overdue_next_run_and_stale_heartbeat_are_loud(
         self, tmp_cron_dir, capsys, monkeypatch
     ):
         job = create_job(prompt="Hourly", schedule="every 60m")
         self._dead_gateway(monkeypatch)
-        overdue = datetime.now(timezone.utc) - timedelta(hours=7)
-        jobs = load_jobs()
-        jobs[[j["id"] for j in jobs].index(job["id"])]["next_run_at"] = overdue.isoformat()
-        save_jobs(jobs)
+        self._park_next_run(job["id"], datetime.now(timezone.utc) - timedelta(hours=7))
         (tmp_cron_dir / "cron" / "ticker_heartbeat").write_text(str(time.time() - 25 * 3600))
 
         cron_command(Namespace(cron_command="status"))
+        status_out = capsys.readouterr().out
+        cron_command(Namespace(cron_command="list", all=False, json=False))
+        list_out = capsys.readouterr().out
 
-        out = capsys.readouterr().out
-        assert "Gateway is not running" in out
-        assert "Scheduler last ticked" in out
-        assert "OVERDUE" in out
-        # The stale timestamp must no longer read as an upcoming run.
-        assert "Next run:" not in out
-
-    def test_future_next_run_stays_plain(self, tmp_cron_dir, capsys, monkeypatch):
-        create_job(prompt="Hourly", schedule="every 60m")
-        self._dead_gateway(monkeypatch)
-
-        cron_command(Namespace(cron_command="status"))
-
-        out = capsys.readouterr().out
-        assert "Next run:" in out
-        assert "OVERDUE" not in out
-        assert "Scheduler last ticked" not in out
+        assert "Gateway is not running" in status_out
+        assert "Scheduler last ticked" in status_out
+        assert "OVERDUE" in status_out and "7h ago" in status_out
+        # The stale timestamp must no longer read as an upcoming run on either surface.
+        assert "Next run:" not in status_out
+        assert "Overdue:" in list_out and "Next run:" not in list_out
 
     def test_overdue_within_doctor_grace_stays_plain(self, tmp_cron_dir, capsys, monkeypatch):
         # status shares `cron doctor`'s 15-minute grace (_OVERDUE_GRACE_SECONDS): a job only
@@ -641,16 +635,16 @@ class TestStatusSurfacesDeadScheduler:
         # not flash OVERDUE while doctor calls the same job healthy.
         job = create_job(prompt="Hourly", schedule="every 60m")
         self._dead_gateway(monkeypatch)
-        within_grace = datetime.now(timezone.utc) - timedelta(minutes=5)
-        jobs = load_jobs()
-        jobs[[j["id"] for j in jobs].index(job["id"])]["next_run_at"] = within_grace.isoformat()
-        save_jobs(jobs)
+        self._park_next_run(job["id"], datetime.now(timezone.utc) - timedelta(minutes=5))
 
         cron_command(Namespace(cron_command="status"))
+        status_out = capsys.readouterr().out
+        cron_command(Namespace(cron_command="list", all=False, json=False))
+        list_out = capsys.readouterr().out
 
-        out = capsys.readouterr().out
-        assert "Next run:" in out
-        assert "OVERDUE" not in out
+        assert "Next run:" in status_out and "OVERDUE" not in status_out
+        assert "Scheduler last ticked" not in status_out  # no heartbeat file → nothing to date
+        assert "Next run:" in list_out and "Overdue:" not in list_out
 
 
 class TestSlashCronRunSkipped:
diff --git a/tests/hermes_cli/test_cron_status_next_run.py b/tests/hermes_cli/test_cron_status_next_run.py
index b73370499a..4f3e2f7639 100644
--- a/tests/hermes_cli/test_cron_status_next_run.py
+++ b/tests/hermes_cli/test_cron_status_next_run.py
@@ -9,15 +9,22 @@ from cron import jobs as job_store
 from hermes_cli.cron import _print_active_jobs_summary
 
 
+@pytest.fixture(autouse=True)
+def _frozen_clock(monkeypatch):
+    # Freeze both the scheduler's clock (normalisation) and the CLI's (overdue check): the
+    # fixtures below are 2026-11 instants and must never start reading as overdue.
+    now = datetime(2026, 10, 31, tzinfo=ZoneInfo("America/New_York"))
+    monkeypatch.setattr(job_store, "_hermes_now", lambda: now)
+    monkeypatch.setattr("hermes_time.now", lambda: now)
+
+
 @pytest.mark.parametrize("later,earlier", [
     ("2026-11-01T01:15:00-05:00", "2026-11-01T01:45:00-04:00"),
     ("2026-11-02T09:00:00-05:00", "2026-11-02T08:00:00-05:00"),
     ("2026-11-02T08:00:00-05:00", "2026-11-02T12:30:00+00:00"),
 ])
-def test_status_earliest_persisted_instant(later, earlier, monkeypatch, capsys):
-    # Only freeze the clock: creation, persistence, normalization and listing are real.
-    now = datetime(2026, 10, 31, tzinfo=ZoneInfo("America/New_York"))
-    monkeypatch.setattr(job_store, "_hermes_now", lambda: now)
+def test_status_earliest_persisted_instant(later, earlier, capsys):
+    # Only the clock is frozen: creation, persistence, normalization and listing are real.
     late_job = job_store.create_job(prompt="later", schedule=later)
     early_job = job_store.create_job(prompt="earlier", schedule=earlier)
     jobs = job_store.list_jobs()
diff --git a/web/src/i18n/en.ts b/web/src/i18n/en.ts
index 159b8f2080..d5e4daeffb 100644
--- a/web/src/i18n/en.ts
+++ b/web/src/i18n/en.ts
@@ -308,6 +308,8 @@ export const en: Translations = {
     noJobs: "No cron jobs configured. Create one above.",
     last: "Last",
     next: "Next",
+    /** Replaces `next` when the stored next_run_at is already past the scheduler grace. */
+    overdueSince: "Overdue since",
     pause: "Pause",
     resume: "Resume",
     triggerNow: "Trigger now",
diff --git a/web/src/i18n/types.ts b/web/src/i18n/types.ts
index 0346d7a885..a97b79a21e 100644
--- a/web/src/i18n/types.ts
+++ b/web/src/i18n/types.ts
@@ -322,6 +322,7 @@ export interface Translations {
     noJobs: string;
     last: string;
     next: string;
+    overdueSince?: string;
     pause: string;
     resume: string;
     triggerNow: string;
diff --git a/web/src/lib/cron-job.test.ts b/web/src/lib/cron-job.test.ts
index 25420d0a3a..f0d7424714 100644
--- a/web/src/lib/cron-job.test.ts
+++ b/web/src/lib/cron-job.test.ts
@@ -5,6 +5,7 @@ import {
   cronJobHasExecutionContent,
   cronJobFormFromJob,
   cronLastResult,
+  cronNextRunOverdueMs,
   splitCronList,
   type CronJobFormState,
 } from "./cron-job";
@@ -200,3 +201,22 @@ describe("cronLastResult", () => {
     ).toEqual({ status: "blocked_config", tone: "warning", detail: "missing API key" });
   });
 });
+
+describe("cronNextRunOverdueMs", () => {
+  const now = Date.parse("2026-09-17T20:35:00+04:00");
+
+  it("flags an active job whose stored slot sits past the scheduler grace (#114309)", () => {
+    const job = { next_run_at: "2026-09-17T13:34:18+04:00", enabled: true, state: "scheduled" };
+    expect(cronNextRunOverdueMs(job, now)).toBe(now - Date.parse(job.next_run_at));
+  });
+
+  it("keeps upcoming, within-grace, paused and unparseable slots as plain next runs", () => {
+    expect(cronNextRunOverdueMs({ next_run_at: "2026-09-17T21:00:00+04:00", enabled: true }, now)).toBeNull();
+    expect(cronNextRunOverdueMs({ next_run_at: "2026-09-17T20:30:00+04:00", enabled: true }, now)).toBeNull();
+    expect(
+      cronNextRunOverdueMs({ next_run_at: "2026-09-17T13:34:18+04:00", enabled: true, state: "paused" }, now),
+    ).toBeNull();
+    expect(cronNextRunOverdueMs({ next_run_at: "2026-09-17T13:34:18+04:00", enabled: false }, now)).toBeNull();
+    expect(cronNextRunOverdueMs({ next_run_at: "not-a-date", enabled: true }, now)).toBeNull();
+  });
+});
diff --git a/web/src/lib/cron-job.ts b/web/src/lib/cron-job.ts
index abcbcd3351..2e9b103f7b 100644
--- a/web/src/lib/cron-job.ts
+++ b/web/src/lib/cron-job.ts
@@ -148,3 +148,23 @@ export function cronLastResult(
       : asString(job.last_error).trim() || asString(job.last_delivery_error).trim();
   return { status, tone, detail: detail || null };
 }
+
+/** Mirrors hermes_cli/cron.py `_OVERDUE_GRACE_SECONDS`: a busy tick can run a few minutes late. */
+export const CRON_NEXT_RUN_OVERDUE_GRACE_MS = 15 * 60 * 1000;
+
+/**
+ * Milliseconds a job's stored `next_run_at` has sat in the past beyond the doctor grace, or
+ * null when the job is upcoming, within grace, not expected to fire, or has no parseable stamp.
+ * A stamp parked in the past is the only user-visible trace of a dead scheduler (#114309), so
+ * the dashboard must never present it as an upcoming "Next".
+ */
+export function cronNextRunOverdueMs(
+  job: Pick<CronJob, "next_run_at" | "enabled" | "state">,
+  nowMs: number = Date.now(),
+): number | null {
+  if (job.enabled === false || job.state === "paused" || job.state === "completed") return null;
+  const at = Date.parse(asString(job.next_run_at));
+  if (Number.isNaN(at)) return null;
+  const overdue = nowMs - at;
+  return overdue > CRON_NEXT_RUN_OVERDUE_GRACE_MS ? overdue : null;
+}
diff --git a/web/src/pages/CronPage.tsx b/web/src/pages/CronPage.tsx
index 38f64f4661..6869775bf1 100644
--- a/web/src/pages/CronPage.tsx
+++ b/web/src/pages/CronPage.tsx
@@ -21,6 +21,7 @@ import type {
 import {
   buildCronJobPayload,
   cronJobHasExecutionContent,
+  cronNextRunOverdueMs,
   cronJobFormFromJob,
   cronLastResult,
   focusCronField,
@@ -1181,9 +1182,18 @@ export default function CronPage() {
                     <span>
                       {t.cron.last}: {formatTime(job.last_run_at)}
                     </span>
-                    <span>
-                      {t.cron.next}: {formatTime(job.next_run_at)}
-                    </span>
+                    {cronNextRunOverdueMs(job) === null ? (
+                      <span>
+                        {t.cron.next}: {formatTime(job.next_run_at)}
+                      </span>
+                    ) : (
+                      <span
+                        className="text-warning font-medium"
+                        data-testid="cron-next-run-overdue"
+                      >
+                        {t.cron.overdueSince ?? en.cron.overdueSince!}: {formatTime(job.next_run_at)}
+                      </span>
+                    )}
                   </div>
                   {job.last_delivery_error && (
                     <p className="text-xs text-destructive mt-1">
diff --git a/website/docs/user-guide/features/cron.md b/website/docs/user-guide/features/cron.md
index f4f4aafdd4..b260492397 100644
--- a/website/docs/user-guide/features/cron.md
+++ b/website/docs/user-guide/features/cron.md
@@ -347,6 +347,8 @@ hermes cron list
 hermes cron status
 ```
 
+`hermes cron status` reports whether the scheduler is alive (gateway process, ticker heartbeat, last successful tick) and the soonest scheduled run across your active jobs, ordered by actual instant even when jobs store different UTC offsets. A `next_run_at` that is already more than 15 minutes in the past is never shown as an upcoming "Next run": `cron status` prints `⚠ Next run <time> is OVERDUE — passed 7h ago but the job has not fired`, `cron list` labels the row `Overdue:`, the dashboard shows `Overdue since`, and when the gateway is down `status` also says when the scheduler last ticked. That is the signature of a scheduler that stopped ticking — restart the gateway (`hermes gateway restart`) so the next tick picks the overdue job up, or run it right away with `hermes cron run <id>`.
+
 For a named profile served by the default-profile multiplexer, `hermes cron status` names that scheduler host and reports the named profile's own heartbeat health. Missing or stale heartbeats point to `hermes --profile default gateway restart`. `cron list` and `cron create` also warn when that heartbeat is missing or stale; `cron status` additionally checks the last successful tick and reports tick errors.
 
 ### Gateway scheduler behavior

From 00b7997f4705488017283b126571d690237ebe4f Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 01:45:46 -0700
Subject: [PATCH 013/190] fix(desktop): label an overdue next run on the Bot
 Mode routine card
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The hermes-bots plugin's Routines card (and its inspector's `Next run` row)
still read `Next: 7 hr. ago` for a `next_run_at` parked past the scheduler
grace — the one Desktop surface the overdue labelling left out (#114309).
The card now switches to `t.cron.overdueSince` and the inspector row to
`Overdue since`, using the same `nextRunOverdueMs` decision as the core cron
panel and sidebar, so paused/completed/disabled jobs keep the plain label.

`nextRunOverdueMs` is exported through `@hermes/plugin-sdk` (the plugin only
imports from the SDK) and its parameter is widened to the optional-field shape
the plugin's `RoutineJob` carries; no plugin i18n key is needed because the
card already renders from core `t.cron`, which every locale resolves.

Test: one card test renders an overdue vs an upcoming job and checks both the
card label and the inspector rows; the fixture's fixed 2026-08-23 next_run_at
is made clock-relative so it never ages into "overdue" on its own.
---
 apps/desktop/src/app/cron/job-state.ts        |  5 +++-
 .../plugins/hermes-bots/cron-detail.test.tsx  | 27 ++++++++++++++++++-
 apps/desktop/src/plugins/hermes-bots/cron.tsx |  7 +++--
 apps/desktop/src/sdk/index.ts                 |  5 ++++
 website/docs/user-guide/features/cron.md      |  2 +-
 5 files changed, 41 insertions(+), 5 deletions(-)

diff --git a/apps/desktop/src/app/cron/job-state.ts b/apps/desktop/src/app/cron/job-state.ts
index bf7348f67d..f8b08c32cd 100644
--- a/apps/desktop/src/app/cron/job-state.ts
+++ b/apps/desktop/src/app/cron/job-state.ts
@@ -35,7 +35,10 @@ export const NEXT_RUN_OVERDUE_GRACE_MS = 15 * 60 * 1000
 // the slot is upcoming, within grace, unparseable, or the job is not expected to fire. A slot
 // parked in the past is the only user-visible trace of a dead scheduler (#114309), so no
 // surface may present it as an upcoming "Next".
-export function nextRunOverdueMs(job: Pick<CronJob, 'enabled' | 'next_run_at' | 'state'>, nowMs = Date.now()): null | number {
+export function nextRunOverdueMs(
+  job: { enabled?: boolean; next_run_at?: null | string; state?: null | string },
+  nowMs = Date.now()
+): null | number {
   const state = jobState(job as CronJob)
 
   if (state === 'paused' || state === 'completed' || state === 'disabled' || !job.next_run_at) {
diff --git a/apps/desktop/src/plugins/hermes-bots/cron-detail.test.tsx b/apps/desktop/src/plugins/hermes-bots/cron-detail.test.tsx
index 57ebdf91a5..43af45964a 100644
--- a/apps/desktop/src/plugins/hermes-bots/cron-detail.test.tsx
+++ b/apps/desktop/src/plugins/hermes-bots/cron-detail.test.tsx
@@ -38,7 +38,9 @@ const activeJob: RoutineJob = {
   last_run_at: '2026-08-23T09:00:00Z',
   last_status: 'success',
   name: '[bot:notetaker] Morning digest',
-  next_run_at: '2026-08-23T10:00:00Z',
+  // Relative to the clock: a fixed stamp ages into the past and the "next run"
+  // it promises would start rendering as overdue (see the overdue case below).
+  next_run_at: new Date(Date.now() + 60 * 60 * 1000).toISOString(),
   prompt_preview: 'Summarize yesterday and post it.',
   repeat: 'forever',
   schedule: 'every 1440m'
@@ -161,6 +163,29 @@ describe('the row is reachable', () => {
     expect(screen.getByRole('switch')).toHaveProperty('disabled', true)
     expect(screen.getByText(/Paused for security/)).toBeTruthy()
   })
+
+  it('labels a next run parked past the scheduler grace as overdue, never as "Next" (#114309)', () => {
+    const hour = 60 * 60 * 1000
+    const overdue: RoutineJob = { ...activeJob, next_run_at: new Date(Date.now() - 7 * hour).toISOString() }
+    const upcoming: RoutineJob = { ...activeJob, next_run_at: new Date(Date.now() + 7 * hour).toISOString() }
+
+    render(<RoutineRow job={overdue} onOpen={() => undefined} owner={{ name: 'notetaker' }} />)
+
+    // The card and the inspector make the same call: the stored slot sitting
+    // hours in the past is the only visible trace of a scheduler that stopped
+    // ticking, so it must not be promised as an upcoming run.
+    expect(screen.getByText(/^Overdue since:.*ago$/)).toBeTruthy()
+    expect(screen.queryByText(/^Next:/)).toBeNull()
+    expect(valueOf(routineDetailRows(overdue), 'Overdue since')).toBeTruthy()
+    expect(valueOf(routineDetailRows(overdue), 'Next run')).toBeUndefined()
+
+    cleanup()
+    render(<RoutineRow job={upcoming} onOpen={() => undefined} owner={{ name: 'notetaker' }} />)
+
+    expect(screen.getByText(/^Next: in /)).toBeTruthy()
+    expect(valueOf(routineDetailRows(upcoming), 'Next run')).toBeTruthy()
+    expect(valueOf(routineDetailRows({ ...overdue, enabled: false, state: 'paused' }), 'Overdue since')).toBeUndefined()
+  })
 })
 
 describe('the inspector', () => {
diff --git a/apps/desktop/src/plugins/hermes-bots/cron.tsx b/apps/desktop/src/plugins/hermes-bots/cron.tsx
index 99f9ebee78..9f94621387 100644
--- a/apps/desktop/src/plugins/hermes-bots/cron.tsx
+++ b/apps/desktop/src/plugins/hermes-bots/cron.tsx
@@ -19,6 +19,7 @@ import {
   GlyphSpinner,
   host,
   Input,
+  nextRunOverdueMs,
   PanelEmpty,
   queryClient,
   relativeTime,
@@ -381,7 +382,9 @@ export function routineDetailRows(job: RoutineJob | null | undefined): Array<{ l
       // raw string when it says something the label dropped.
       ['Schedule (raw)', raw && raw !== label ? raw : null],
       ['Repeat', job?.repeat],
-      ['Next run', paused ? null : routineTimestamp(job?.next_run_at)],
+      // A slot parked past the scheduler grace is labelled overdue, never
+      // promised as a next run (#114309); the card below makes the same call.
+      [job && nextRunOverdueMs(job) !== null ? 'Overdue since' : 'Next run', paused ? null : routineTimestamp(job?.next_run_at)],
       ['Last run', routineTimestamp(job?.last_run_at)],
       ['Last result', routineLastResult(job?.last_status)],
       ['Delivers to', job?.deliver],
@@ -584,7 +587,7 @@ export function RoutineRow({ job, onOpen, owner }: RoutineRowProps) {
         </span>
         <span className="ml-auto shrink-0 whitespace-nowrap text-[0.65rem] text-(--ui-text-quaternary)">
           {active && job.next_run_at
-            ? `${c.next} ${relativeTime(new Date(job.next_run_at).getTime())}`
+            ? `${nextRunOverdueMs(job) === null ? c.next : c.overdueSince} ${relativeTime(new Date(job.next_run_at).getTime())}`
             : c.states.paused}
         </span>
       </div>
diff --git a/apps/desktop/src/sdk/index.ts b/apps/desktop/src/sdk/index.ts
index 35b6694390..229a219ea8 100644
--- a/apps/desktop/src/sdk/index.ts
+++ b/apps/desktop/src/sdk/index.ts
@@ -1570,6 +1570,11 @@ export { SidebarRowLead } from '@/app/chat/sidebar/chrome'
 export { ConnectionGlyph } from '@/app/chat/sidebar/connection-glyph'
 export { SIDEBAR_ROW_LEAD, SIDEBAR_TRUNCATED_LEADING } from '@/app/chat/sidebar/row-geometry'
 export { PALETTE_AREA, type PaletteContribution } from '@/app/command-palette/contrib'
+/** THE overdue test for a cron job's `next_run_at`: non-null once the stored slot
+ *  sits past the scheduler grace and the job is expected to fire. Every surface
+ *  that prints a next run switches its label on this (`t.cron.next` →
+ *  `t.cron.overdueSince`) so a dead scheduler never reads as "Next: 7 hr ago". */
+export { nextRunOverdueMs } from '@/app/cron/job-state'
 /** THE master-detail toolkit core uses for list+inspector surfaces (Scheduled
  *  jobs, Kanban, …): a dense left `PanelList` of `PanelListRow`s beside a
  *  scrolling `PanelDetail` of `PanelSectionLabel` / `PanelMeta` / `PanelBlock`.
diff --git a/website/docs/user-guide/features/cron.md b/website/docs/user-guide/features/cron.md
index b260492397..7256397c68 100644
--- a/website/docs/user-guide/features/cron.md
+++ b/website/docs/user-guide/features/cron.md
@@ -347,7 +347,7 @@ hermes cron list
 hermes cron status
 ```
 
-`hermes cron status` reports whether the scheduler is alive (gateway process, ticker heartbeat, last successful tick) and the soonest scheduled run across your active jobs, ordered by actual instant even when jobs store different UTC offsets. A `next_run_at` that is already more than 15 minutes in the past is never shown as an upcoming "Next run": `cron status` prints `⚠ Next run <time> is OVERDUE — passed 7h ago but the job has not fired`, `cron list` labels the row `Overdue:`, the dashboard shows `Overdue since`, and when the gateway is down `status` also says when the scheduler last ticked. That is the signature of a scheduler that stopped ticking — restart the gateway (`hermes gateway restart`) so the next tick picks the overdue job up, or run it right away with `hermes cron run <id>`.
+`hermes cron status` reports whether the scheduler is alive (gateway process, ticker heartbeat, last successful tick) and the soonest scheduled run across your active jobs, ordered by actual instant even when jobs store different UTC offsets. A `next_run_at` that is already more than 15 minutes in the past is never shown as an upcoming "Next run": `cron status` prints `⚠ Next run <time> is OVERDUE — passed 7h ago but the job has not fired`, `cron list` labels the row `Overdue:`, the dashboard and the Desktop cron panel (including a Bot's Routines card) show `Overdue since`, and when the gateway is down `status` also says when the scheduler last ticked. That is the signature of a scheduler that stopped ticking — restart the gateway (`hermes gateway restart`) so the next tick picks the overdue job up, or run it right away with `hermes cron run <id>`.
 
 For a named profile served by the default-profile multiplexer, `hermes cron status` names that scheduler host and reports the named profile's own heartbeat health. Missing or stale heartbeats point to `hermes --profile default gateway restart`. `cron list` and `cron create` also warn when that heartbeat is missing or stale; `cron status` additionally checks the last successful tick and reports tick errors.
 

From 610fc83f500a53143542c6862816c30dd02f3b16 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 03:39:02 -0700
Subject: [PATCH 014/190] fix(cli): label an overdue next run in the in-chat
 /cron and /cron list
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The slash handler behind the classic CLI's and the TUI's `/cron` overview and
`/cron list` still printed the stored `next_run_at` verbatim as `Next:` /
`Next run:`, so a stamp parked seven hours in the past read as an upcoming run —
the exact symptom of #114309 on the one CLI surface the branch had left out.
Both rows now go through `hermes_cli.cron._next_run_row`, the same decision
`hermes cron list` makes: past the doctor grace on an enabled, non-paused job the
row becomes `Overdue: <stamp> (7h ago — the job has not fired; is the scheduler
running?)`, while paused/disabled/completed jobs keep the plain label because they
are not expected to fire.

Test: one slash-handler test parks two jobs 7h in the past, pauses one, and checks
that `/cron` and `/cron list --all` flag exactly the enabled one.
---
 hermes_cli/cli_commands_mixin.py              |  8 +++--
 tests/hermes_cli/test_cron.py                 | 29 +++++++++++++++++++
 .../test_web_server_cron_profiles.py          | 18 ++++++++++++
 3 files changed, 53 insertions(+), 2 deletions(-)

diff --git a/hermes_cli/cli_commands_mixin.py b/hermes_cli/cli_commands_mixin.py
index 2f88a542cd..4f4806243c 100644
--- a/hermes_cli/cli_commands_mixin.py
+++ b/hermes_cli/cli_commands_mixin.py
@@ -1675,6 +1675,7 @@ class CLICommandsMixin:
         result = _cron_api(action="list")
         jobs = result.get("jobs", []) if result.get("success") else []
         if jobs:
+            from hermes_cli.cron import _next_run_row
             _pr("  Current Jobs:", "  " + "-" * 63)
             for job in jobs:
                 print(f"    {job['job_id'][:12]:<12} | {job['schedule']:<15} | {job.get('repeat', '?'):<8}")
@@ -1682,7 +1683,9 @@ class CLICommandsMixin:
                     print(f"      Skills: {', '.join(job['skills'])}")
                 print(f"      {job.get('prompt_preview', '')}")
                 if job.get("next_run_at"):
-                    print(f"      Next: {job['next_run_at']}")
+                    # A stamp parked past the scheduler grace must not read as upcoming (#114309).
+                    label, value = _next_run_row(job)
+                    print(f"      {'Next' if label == 'Next run' else label}: {value}")
                 print()
         else:
             print("  No scheduled jobs. Use '/cron add' to create one.")
@@ -1693,13 +1696,14 @@ class CLICommandsMixin:
         jobs = result.get("jobs", []) if result.get("success") else []
         if not jobs:
             return print("(._.) No scheduled jobs.")
+        from hermes_cli.cron import _next_run_row
         print()
         _pr("Scheduled Jobs:", "-" * 80)
         for job in jobs:
             _pr(f"  ID: {job['job_id']}", f"  Name: {job['name']}",
                 f"  State: {job.get('state', '?')}",
                 f"  Schedule: {job['schedule']} ({job.get('repeat', '?')})",
-                f"  Next run: {job.get('next_run_at', 'N/A')}")
+                "  %s: %s" % _next_run_row(job) if job.get("next_run_at") else "  Next run: N/A")
             if job.get("skills"):
                 print(f"  Skills: {', '.join(job['skills'])}")
             print(f"  Prompt: {job.get('prompt_preview', '')}")
diff --git a/tests/hermes_cli/test_cron.py b/tests/hermes_cli/test_cron.py
index 15c1104df9..4300cfbf5f 100644
--- a/tests/hermes_cli/test_cron.py
+++ b/tests/hermes_cli/test_cron.py
@@ -646,6 +646,35 @@ class TestStatusSurfacesDeadScheduler:
         assert "Scheduler last ticked" not in status_out  # no heartbeat file → nothing to date
         assert "Next run:" in list_out and "Overdue:" not in list_out
 
+    def test_slash_cron_and_list_flag_overdue_but_not_paused(self, tmp_cron_dir, capsys):
+        # The in-chat `/cron` overview and `/cron list` (classic CLI + Ink TUI forward to the
+        # same handler) read the same rows; a 7h-past stamp must not read as an upcoming run,
+        # while a paused job keeps its plain label — pausing is why it did not fire.
+        from hermes_cli.cli_commands_mixin import CLICommandsMixin
+
+        class _Host(CLICommandsMixin):
+            pass
+
+        stale = create_job(prompt="Hourly", schedule="every 60m")
+        paused = create_job(prompt="Parked", schedule="every 60m")
+        when = datetime.now(timezone.utc) - timedelta(hours=7)
+        self._park_next_run(stale["id"], when)
+        self._park_next_run(paused["id"], when)
+        jobs = load_jobs()
+        jobs[[j["id"] for j in jobs].index(paused["id"])]["enabled"] = False
+        save_jobs(jobs)
+
+        _Host()._handle_cron_command("/cron")
+        overview_out = capsys.readouterr().out
+        _Host()._handle_cron_command("/cron list --all")
+        list_out = capsys.readouterr().out
+
+        for out in (overview_out, list_out):
+            assert out.count("Overdue:") == 1 and "7h ago" in out
+        assert "Next" not in overview_out  # the overview lists enabled jobs only
+        assert list_out.count("Next run:") == 1  # only the paused job's stamp stays plain
+        assert list_out.index("Overdue:") < list_out.index("Next run:")
+
 
 class TestSlashCronRunSkipped:
     """``/cron run`` on a job whose claim is refused (paused here; a live claim held by another
diff --git a/tests/hermes_cli/test_web_server_cron_profiles.py b/tests/hermes_cli/test_web_server_cron_profiles.py
index 9e345c5faf..5bbb4eb089 100644
--- a/tests/hermes_cli/test_web_server_cron_profiles.py
+++ b/tests/hermes_cli/test_web_server_cron_profiles.py
@@ -1193,3 +1193,21 @@ async def test_create_cron_job_without_profile_defaults_when_unscoped(
 
     assert job["profile"] == "default"
     assert (isolated_profiles["default"] / "cron" / "jobs.json").exists()
+
+
+def test_list_cron_jobs_carries_each_profiles_ticker_heartbeat_age(isolated_profiles):
+    """#114309 — the dashboard must be able to say "scheduler last ticked X hours ago":
+    every listed job carries its own profile's ticker heartbeat age (None = never/unknown)."""
+    import time
+
+    for name, home in isolated_profiles.items():
+        with _web_server_cron._cron_store_scope(home) as cron_jobs:
+            cron_jobs.create_job(prompt=f"{name} hourly", schedule="every 1h")
+    (isolated_profiles["worker_alpha"] / "cron" / "ticker_heartbeat").write_text(
+        str(time.time() - 25 * 3600)
+    )
+
+    ages = {job["profile"]: job["scheduler_heartbeat_age_s"] for job in _rt_cron._list_cron_jobs_sync("all")}
+
+    assert ages["default"] is None  # no heartbeat file: cannot date the last tick
+    assert 25 * 3600 <= ages["worker_alpha"] < 25 * 3600 + 60

From 5179b5177dfae56d6776ea6ec51837c2e93778d2 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 03:53:30 -0700
Subject: [PATCH 015/190] fix(dashboard): say when the scheduler last ticked on
 the Cron page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

#114309 expects the dashboard, like `hermes cron status`, to say "scheduler last
ticked X hours ago" when a stopped ticker leaves next runs stranded in the past.
The Cron page only had the per-row `Overdue since` label and no way to date the
outage: GET /api/cron/jobs carried nothing about the ticker.

Every job the dashboard cron endpoints return now carries
`scheduler_heartbeat_age_s` — its own profile's ticker heartbeat age read inside
the same store scope as the job list (None when it cannot be dated) — and the Cron
page renders "Scheduler last ticked 7h ago — jobs that came due since then have not
fired" above the list when the oldest heartbeat among jobs expected to fire is
past the CLI's STALE_AFTER threshold (three missed 60s iterations plus slack).
Paused, disabled and completed jobs never raise the banner, matching the overdue
label's rule. The field is additive, so the response shape and every existing
consumer are unchanged.

Tests: one router test lists two profiles with one stale heartbeat file and checks
each job reports its own age (None for the profile without a heartbeat); one vitest
pins the stale-age selection and the relative label.
---
 hermes_cli/web_server_cron.py            | 15 +++++++++----
 web/src/i18n/en.ts                       |  2 ++
 web/src/i18n/types.ts                    |  1 +
 web/src/lib/api.ts                       |  2 ++
 web/src/lib/cron-job.test.ts             | 19 ++++++++++++++++
 web/src/lib/cron-job.ts                  | 28 ++++++++++++++++++++++++
 web/src/pages/CronPage.tsx               | 12 ++++++++++
 website/docs/user-guide/features/cron.md |  2 +-
 8 files changed, 76 insertions(+), 5 deletions(-)

diff --git a/hermes_cli/web_server_cron.py b/hermes_cli/web_server_cron.py
index 83267d27ad..26dabeebff 100644
--- a/hermes_cli/web_server_cron.py
+++ b/hermes_cli/web_server_cron.py
@@ -123,13 +123,19 @@ def _cron_profile_home(profile: Optional[str]) -> Tuple[str, Path]:
     return canon, profiles_mod.get_profile_dir(canon)
 
 
-def _annotate_cron_job(job: Dict[str, Any], profile: str, home: Path) -> Dict[str, Any]:
+def _annotate_cron_job(
+    job: Dict[str, Any], profile: str, home: Path, heartbeat_age: Optional[float] = None,
+) -> Dict[str, Any]:
     return {
         **job,
         "profile": profile,
         "profile_name": profile,
         "hermes_home": str(home),
-        "is_default_profile": profile == "default"}
+        "is_default_profile": profile == "default",
+        # Seconds since this profile's ticker last iterated (None = never/unknown): a
+        # `next_run_at` parked in the past is only explained by a scheduler that stopped
+        # ticking, so the dashboard can date it (#114309).
+        "scheduler_heartbeat_age_s": heartbeat_age}
 
 
 @contextlib.contextmanager
@@ -158,10 +164,11 @@ def _call_cron_for_profile(target_profile: Optional[str], func_name: str, *args,
             result = create_job_with_scheduler_registration(*args, **kwargs)
         else:
             result = getattr(cron_jobs, func_name)(*args, **kwargs)
+        heartbeat_age = cron_jobs.get_ticker_heartbeat_age()
     if isinstance(result, list):
-        return [_annotate_cron_job(j, profile_name, home) for j in result]
+        return [_annotate_cron_job(j, profile_name, home, heartbeat_age) for j in result]
     if isinstance(result, dict):
-        return _annotate_cron_job(result, profile_name, home)
+        return _annotate_cron_job(result, profile_name, home, heartbeat_age)
     return result
 
 
diff --git a/web/src/i18n/en.ts b/web/src/i18n/en.ts
index d5e4daeffb..9f208d63ac 100644
--- a/web/src/i18n/en.ts
+++ b/web/src/i18n/en.ts
@@ -310,6 +310,8 @@ export const en: Translations = {
     next: "Next",
     /** Replaces `next` when the stored next_run_at is already past the scheduler grace. */
     overdueSince: "Overdue since",
+    /** Banner when the ticker heartbeat is stale; {when} is a relative time such as "7h ago". */
+    schedulerLastTicked: "Scheduler last ticked {when} — jobs that came due since then have not fired",
     pause: "Pause",
     resume: "Resume",
     triggerNow: "Trigger now",
diff --git a/web/src/i18n/types.ts b/web/src/i18n/types.ts
index a97b79a21e..ddb367363e 100644
--- a/web/src/i18n/types.ts
+++ b/web/src/i18n/types.ts
@@ -323,6 +323,7 @@ export interface Translations {
     last: string;
     next: string;
     overdueSince?: string;
+    schedulerLastTicked?: string;
     pause: string;
     resume: string;
     triggerNow: string;
diff --git a/web/src/lib/api.ts b/web/src/lib/api.ts
index 3e0a2716f3..57440e93ee 100644
--- a/web/src/lib/api.ts
+++ b/web/src/lib/api.ts
@@ -2327,6 +2327,8 @@ export interface CronJob {
   workdir?: string | null;
   last_run_at?: string | null;
   next_run_at?: string | null;
+  /** Seconds since the job's profile ticker last iterated; null when it cannot be dated. */
+  scheduler_heartbeat_age_s?: number | null;
   last_status?: string | null;
   last_error?: string | null;
   last_delivery_error?: string | null;
diff --git a/web/src/lib/cron-job.test.ts b/web/src/lib/cron-job.test.ts
index f0d7424714..81806f5178 100644
--- a/web/src/lib/cron-job.test.ts
+++ b/web/src/lib/cron-job.test.ts
@@ -5,7 +5,9 @@ import {
   cronJobHasExecutionContent,
   cronJobFormFromJob,
   cronLastResult,
+  cronAgoLabel,
   cronNextRunOverdueMs,
+  cronSchedulerStaleAgeS,
   splitCronList,
   type CronJobFormState,
 } from "./cron-job";
@@ -220,3 +222,20 @@ describe("cronNextRunOverdueMs", () => {
     expect(cronNextRunOverdueMs({ next_run_at: "not-a-date", enabled: true }, now)).toBeNull();
   });
 });
+
+describe("cronSchedulerStaleAgeS", () => {
+  it("dates the oldest stale ticker among jobs expected to fire, and stays quiet otherwise (#114309)", () => {
+    expect(
+      cronSchedulerStaleAgeS([
+        { scheduler_heartbeat_age_s: 25 * 3600, enabled: true, state: "scheduled" },
+        { scheduler_heartbeat_age_s: 7 * 3600, enabled: true },
+        { scheduler_heartbeat_age_s: 90 * 3600, enabled: true, state: "paused" },
+      ]),
+    ).toBe(25 * 3600);
+    expect(cronSchedulerStaleAgeS([{ scheduler_heartbeat_age_s: 90, enabled: true }])).toBeNull();
+    expect(cronSchedulerStaleAgeS([{ scheduler_heartbeat_age_s: null, enabled: true }])).toBeNull();
+    expect(cronSchedulerStaleAgeS([{ scheduler_heartbeat_age_s: 25 * 3600, enabled: false }])).toBeNull();
+    expect(cronSchedulerStaleAgeS([])).toBeNull();
+    expect([7 * 3600 + 120, 90, 3 * 86400].map(cronAgoLabel)).toEqual(["7h ago", "1m ago", "3d ago"]);
+  });
+});
diff --git a/web/src/lib/cron-job.ts b/web/src/lib/cron-job.ts
index 2e9b103f7b..c137673f73 100644
--- a/web/src/lib/cron-job.ts
+++ b/web/src/lib/cron-job.ts
@@ -168,3 +168,31 @@ export function cronNextRunOverdueMs(
   const overdue = nowMs - at;
   return overdue > CRON_NEXT_RUN_OVERDUE_GRACE_MS ? overdue : null;
 }
+
+/** Mirrors hermes_cli/cron.py `STALE_AFTER`: ~3 missed ticker iterations (60s) plus slack. */
+export const CRON_SCHEDULER_STALE_S = 60 * 3 + 20;
+
+/**
+ * Seconds since the scheduler last ticked when that is long enough ago to strand jobs, or null
+ * while it ticks on time, when no listed job is expected to fire, or when the server could not
+ * date the last tick. Jobs from several profiles report their own ticker; the oldest wins.
+ */
+export function cronSchedulerStaleAgeS(
+  jobs: Pick<CronJob, "scheduler_heartbeat_age_s" | "enabled" | "state">[],
+): number | null {
+  let stale: number | null = null;
+  for (const job of jobs) {
+    const age = job.scheduler_heartbeat_age_s;
+    if (typeof age !== "number" || age <= CRON_SCHEDULER_STALE_S) continue;
+    if (job.enabled === false || job.state === "paused" || job.state === "completed") continue;
+    if (stale === null || age > stale) stale = age;
+  }
+  return stale;
+}
+
+/** "7h ago"-style label for an elapsed duration in seconds (no clock read, so it renders pure). */
+export function cronAgoLabel(seconds: number): string {
+  if (seconds < 3600) return `${Math.max(1, Math.floor(seconds / 60))}m ago`;
+  if (seconds < 86400) return `${Math.floor(seconds / 3600)}h ago`;
+  return `${Math.floor(seconds / 86400)}d ago`;
+}
diff --git a/web/src/pages/CronPage.tsx b/web/src/pages/CronPage.tsx
index 6869775bf1..ca57d51970 100644
--- a/web/src/pages/CronPage.tsx
+++ b/web/src/pages/CronPage.tsx
@@ -21,7 +21,9 @@ import type {
 import {
   buildCronJobPayload,
   cronJobHasExecutionContent,
+  cronAgoLabel,
   cronNextRunOverdueMs,
+  cronSchedulerStaleAgeS,
   cronJobFormFromJob,
   cronLastResult,
   focusCronField,
@@ -531,6 +533,7 @@ const STATUS_TONE: Record<string, "success" | "warning" | "destructive"> = {
 
 export default function CronPage() {
   const [jobs, setJobs] = useState<CronJob[]>([]);
+  const schedulerStaleAgeS = cronSchedulerStaleAgeS(jobs);
   const [triggeringJobKeys, setTriggeringJobKeys] = useState<ReadonlySet<string>>(
     () => new Set(),
   );
@@ -891,6 +894,15 @@ export default function CronPage() {
         />
       )}
 
+      {schedulerStaleAgeS !== null && (
+        <p className="text-sm text-warning font-medium" data-testid="cron-scheduler-stale">
+          {(t.cron.schedulerLastTicked ?? en.cron.schedulerLastTicked!).replace(
+            "{when}",
+            cronAgoLabel(schedulerStaleAgeS),
+          )}
+        </p>
+      )}
+
       <Segmented
         value={view}
         onChange={(v) => setView(v as "jobs" | "blueprints")}
diff --git a/website/docs/user-guide/features/cron.md b/website/docs/user-guide/features/cron.md
index 7256397c68..9d7681f806 100644
--- a/website/docs/user-guide/features/cron.md
+++ b/website/docs/user-guide/features/cron.md
@@ -347,7 +347,7 @@ hermes cron list
 hermes cron status
 ```
 
-`hermes cron status` reports whether the scheduler is alive (gateway process, ticker heartbeat, last successful tick) and the soonest scheduled run across your active jobs, ordered by actual instant even when jobs store different UTC offsets. A `next_run_at` that is already more than 15 minutes in the past is never shown as an upcoming "Next run": `cron status` prints `⚠ Next run <time> is OVERDUE — passed 7h ago but the job has not fired`, `cron list` labels the row `Overdue:`, the dashboard and the Desktop cron panel (including a Bot's Routines card) show `Overdue since`, and when the gateway is down `status` also says when the scheduler last ticked. That is the signature of a scheduler that stopped ticking — restart the gateway (`hermes gateway restart`) so the next tick picks the overdue job up, or run it right away with `hermes cron run <id>`.
+`hermes cron status` reports whether the scheduler is alive (gateway process, ticker heartbeat, last successful tick) and the soonest scheduled run across your active jobs, ordered by actual instant even when jobs store different UTC offsets. A `next_run_at` that is already more than 15 minutes in the past is never shown as an upcoming "Next run": `cron status` prints `⚠ Next run <time> is OVERDUE — passed 7h ago but the job has not fired`, `cron list` and the in-chat `/cron list` label the row `Overdue:`, the dashboard and the Desktop cron panel (including a Bot's Routines card) show `Overdue since`, and when the scheduler has stopped ticking `status` (with the gateway down) and the dashboard Cron page also say when it last ticked. That is the signature of a scheduler that stopped ticking — restart the gateway (`hermes gateway restart`) so the next tick picks the overdue job up, or run it right away with `hermes cron run <id>`.
 
 For a named profile served by the default-profile multiplexer, `hermes cron status` names that scheduler host and reports the named profile's own heartbeat health. Missing or stale heartbeats point to `hermes --profile default gateway restart`. `cron list` and `cron create` also warn when that heartbeat is missing or stale; `cron status` additionally checks the last successful tick and reports tick errors.
 

From e5fe22646ea30cee2c80b2154c055589e74b1364 Mon Sep 17 00:00:00 2001
From: KoNit-K <konit.block@protonmail.com>
Date: Thu, 17 Sep 2026 03:41:42 +0800
Subject: [PATCH 016/190] fix(update): clear fleet restart warning for
 multiplexers

---
 hermes_cli/update_cmd_fleet.py                | 44 +++++++++++++++---
 hermes_cli/update_receipt.py                  | 24 ++++++++--
 .../test_update_fleet_restart_pending.py      | 45 +++++++++++++++++++
 tests/hermes_cli/test_update_receipt.py       | 17 +++++++
 4 files changed, 121 insertions(+), 9 deletions(-)

diff --git a/hermes_cli/update_cmd_fleet.py b/hermes_cli/update_cmd_fleet.py
index 7f6d5ad95f..aa15026174 100644
--- a/hermes_cli/update_cmd_fleet.py
+++ b/hermes_cli/update_cmd_fleet.py
@@ -171,6 +171,29 @@ def _receipt_owed_gateways(receipt: dict, pending_manual: list[dict]) -> set[tup
     return None if unverified else owed
 
 
+def _fleet_row_covered_gateway_profiles(row: dict) -> set[str] | None:
+    """Profiles a current, identity-verified fleet row can vouch for.
+
+    A multiplexer writes its live ``served_profiles`` into the same runtime
+    status record that supplied the row.  Its default-profile row therefore
+    covers every listed satellite profile too.  Malformed entries are not
+    evidence: callers retain the pending obligation rather than guessing.
+    """
+    profile = row.get("profile")
+    if not isinstance(profile, str) or not profile or profile == "unknown":
+        return None
+    covered = {profile}
+    served_profiles = row.get("served_profiles")
+    if served_profiles is None:
+        return covered
+    if not isinstance(served_profiles, list) or not served_profiles:
+        return None
+    if any(not isinstance(name, str) or not name or name == "unknown" for name in served_profiles):
+        return None
+    covered.update(served_profiles)
+    return covered
+
+
 def _live_fleet_covers_receipt(expected_sha: str | None, receipt: dict, owed: set[tuple[str, str]] | None, *, accept_states: tuple = ("current",)) -> bool:
     """Require a successor at the expected SHA for every owed gateway identity."""
     if not expected_sha:
@@ -189,7 +212,13 @@ def _live_fleet_covers_receipt(expected_sha: str | None, receipt: dict, owed: se
             for row in fleet
         ):
             return False
-        return owed <= {("gateway", row.get("profile")) for row in fleet}
+        covered_profiles: set[str] = set()
+        for row in fleet:
+            covered = _fleet_row_covered_gateway_profiles(row)
+            if covered is None:
+                return False
+            covered_profiles.update(covered)
+        return owed <= {("gateway", profile) for profile in covered_profiles}
     except Exception as exc:
         logger.debug("Could not reconcile pending fleet identities: %s", exc)
         return False
@@ -246,13 +275,18 @@ def _marker_only_restart_obsolete() -> bool:
     for row in fleet:
         if not isinstance(row, dict):
             return False
-        profile = row.get("profile")
-        if not profile or profile == "unknown":
+        if _fleet_row_covered_gateway_profiles(row) is None:
             return False  # unidentified runtime: the matrix cannot vouch for it
         if row.get("state") != "current" or str(row.get("code_sha")) != expected_sha:
             return False  # stale / down / unknown-identity row still owes the restart
-    if not owed <= {("gateway", row.get("profile")) for row in fleet}:
-        return False  # A gateway this marker owns is absent.
+    covered_profiles: set[str] = set()
+    for row in fleet:
+        covered = _fleet_row_covered_gateway_profiles(row)
+        if covered is None:
+            return False
+        covered_profiles.update(covered)
+    if not owed <= {("gateway", profile) for profile in covered_profiles}:
+        return False  # A gateway this marker owns is absent (down) or unidentifiable.
     _clear_fleet_restart_pending_marker()
     logger.debug(
         "Fleet-restart-pending marker discharged: %d gateway(s) already serve %s",
diff --git a/hermes_cli/update_receipt.py b/hermes_cli/update_receipt.py
index d649e7486b..06d7ed8636 100644
--- a/hermes_cli/update_receipt.py
+++ b/hermes_cli/update_receipt.py
@@ -295,14 +295,24 @@ def _socket_identity(home: Path) -> Optional[tuple[int, dict]]:
 
 
 def _fleet_row(
-    profile: str, pid: int, code_sha: Any, code_version: Any, expected_sha: Any, state: str = "unknown"
+    profile: str, pid: int, code_sha: Any, code_version: Any, expected_sha: Any,
+    state: str = "unknown", served_profiles: Any = None,
 ) -> dict[str, Any]:
     if state == "unknown" and code_sha and expected_sha:
         state = "current" if str(code_sha) == str(expected_sha) else "stale"
-    return {
+    row = {
         "profile": profile, "pid": pid, "code_sha": str(code_sha) if code_sha else None,
         "code_version": code_version, "state": state,
     }
+    # A live, identity-verified multiplexer represents every profile in this
+    # list. Keep the field only when its shape is usable: callers use it to
+    # discharge per-profile restart obligations, so corrupt status must not
+    # widen coverage.
+    if isinstance(served_profiles, list) and served_profiles and all(
+        isinstance(name, str) and name for name in served_profiles
+    ):
+        row["served_profiles"] = list(dict.fromkeys(served_profiles))
+    return row
 
 
 # Runtime-status states that do not describe a gateway that should be running now — no down row.
@@ -341,7 +351,10 @@ def collect_fleet_versions(*, pre_restart_pids: Optional[list[int]] = None) -> l
             sock = _socket_identity(home)
             if sock is not None:
                 pid, identity = sock
-                row = _fleet_row(profile, pid, identity.get("code_sha"), identity.get("code_version"), expected_sha)
+                row = _fleet_row(
+                    profile, pid, identity.get("code_sha"), identity.get("code_version"), expected_sha,
+                    served_profiles=identity.get("served_profiles"),
+                )
                 results.append({**row, "source": "socket"})
                 continue
             record = read_runtime_status(home / "gateway_state.json")
@@ -356,7 +369,10 @@ def collect_fleet_versions(*, pre_restart_pids: Optional[list[int]] = None) -> l
             # verifies that same live gateway.
             if live_gateway_pid_for_home(home) == pid:
                 results.append(
-                    _fleet_row(profile, pid, record.get("code_sha"), record.get("code_version"), expected_sha)
+                    _fleet_row(
+                        profile, pid, record.get("code_sha"), record.get("code_version"), expected_sha,
+                        served_profiles=record.get("served_profiles"),
+                    )
                 )
                 continue
             # A live non-gateway (or a gateway for another profile) can write a
diff --git a/tests/hermes_cli/test_update_fleet_restart_pending.py b/tests/hermes_cli/test_update_fleet_restart_pending.py
index 139f1b02fc..8fbb906ed9 100644
--- a/tests/hermes_cli/test_update_fleet_restart_pending.py
+++ b/tests/hermes_cli/test_update_fleet_restart_pending.py
@@ -719,6 +719,51 @@ def test_startup_warn_discharged_when_fleet_current(monkeypatch, capsys):
     assert not update_cmd._fleet_restart_pending_marker_path().exists()
 
 
+def test_startup_warn_discharged_when_multiplexer_covers_owed_profiles(monkeypatch, capsys):
+    """A current multiplexer discharges every profile named in its live record (#113350)."""
+    disk_sha = "e" * 40
+    update_cmd._write_fleet_restart_pending_marker(expected_sha=disk_sha)
+    _patch_marker_sha(monkeypatch, disk_sha)
+    receipt_dir = get_hermes_home() / "logs" / "update_receipts"
+    receipt_dir.mkdir(parents=True)
+    (receipt_dir / "latest.json").write_text(
+        json.dumps(
+            {
+                "outcome": "partial",
+                "exit_code": 1,
+                "plan": {
+                    "runtimes": [
+                        {"kind": "gateway", "profile": profile, "pid": pid}
+                        for profile, pid in (("default", 42), ("coder", 43))
+                    ]
+                },
+            }
+        ),
+        encoding="utf-8",
+    )
+    monkeypatch.setattr(
+        "hermes_cli.update_receipt.collect_fleet_versions",
+        lambda **kwargs: [
+            {
+                "profile": "default",
+                "pid": 42,
+                "code_sha": disk_sha,
+                "code_version": "0.21.0",
+                "state": "current",
+                "served_profiles": ["default", "coder"],
+            }
+        ],
+    )
+
+    update_cmd._warn_pending_fleet_restart_on_startup()
+
+    assert capsys.readouterr().err == ""
+    assert not update_cmd._fleet_restart_pending_marker_path().exists()
+    # The same live multiplexer coverage also discharges the receipt fallback
+    # after an operator has already removed the marker.
+    assert update_cmd._pending_fleet_restart_needed() is False
+
+
 @pytest.mark.parametrize(
     "disk_sha, fleet",
     [
diff --git a/tests/hermes_cli/test_update_receipt.py b/tests/hermes_cli/test_update_receipt.py
index 5a35785832..664341c940 100644
--- a/tests/hermes_cli/test_update_receipt.py
+++ b/tests/hermes_cli/test_update_receipt.py
@@ -340,6 +340,23 @@ class TestFleetClassification:
         assert fleet[0]["state"] == "current"
         assert fleet[0]["pid"] == 4242
 
+    def test_current_multiplexer_reports_its_served_profiles(self, monkeypatch, tmp_path):
+        """One verified multiplexer is evidence for every profile it serves."""
+        sha = "a" * 40
+        fleet = self._fleet_with(
+            monkeypatch,
+            tmp_path,
+            {
+                "pid": 4242,
+                "code_sha": sha,
+                "code_version": "1.0",
+                "served_profiles": ["default", "coder"],
+            },
+            expected_sha=sha,
+        )
+
+        assert fleet[0]["served_profiles"] == ["default", "coder"]
+
     def test_stale_gateway(self, monkeypatch, tmp_path):
         fleet = self._fleet_with(
             monkeypatch, tmp_path,

From bb0c5c41985c4668be043f366fe9d7f3ff716ccb Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 00:51:29 -0700
Subject: [PATCH 017/190] refactor(update): one coverage helper for both
 pending-restart predicates

`_live_fleet_covers_receipt` and `_marker_only_restart_obsolete` each looped the fleet
twice to fold `served_profiles` into the covered identities and re-validated a shape
`_fleet_row` already enforces. One `_fleet_covered_gateways(fleet)` answers the
`(kind, profile)` set (or None for an unidentified row) for both.
---
 hermes_cli/update_cmd_fleet.py | 53 +++++++++++-----------------------
 1 file changed, 17 insertions(+), 36 deletions(-)

diff --git a/hermes_cli/update_cmd_fleet.py b/hermes_cli/update_cmd_fleet.py
index aa15026174..b4a7cd51c2 100644
--- a/hermes_cli/update_cmd_fleet.py
+++ b/hermes_cli/update_cmd_fleet.py
@@ -171,26 +171,19 @@ def _receipt_owed_gateways(receipt: dict, pending_manual: list[dict]) -> set[tup
     return None if unverified else owed
 
 
-def _fleet_row_covered_gateway_profiles(row: dict) -> set[str] | None:
-    """Profiles a current, identity-verified fleet row can vouch for.
+def _fleet_covered_gateways(fleet: list) -> set[tuple[str, str]] | None:
+    """``(kind, profile)`` identities the live rows vouch for; ``None`` when any row is unidentified.
 
-    A multiplexer writes its live ``served_profiles`` into the same runtime
-    status record that supplied the row.  Its default-profile row therefore
-    covers every listed satellite profile too.  Malformed entries are not
-    evidence: callers retain the pending obligation rather than guessing.
+    A multiplexer's row carries the ``served_profiles`` its runtime status records (``_fleet_row``
+    keeps the field only when well-formed), so one live process covers every profile it serves.
     """
-    profile = row.get("profile")
-    if not isinstance(profile, str) or not profile or profile == "unknown":
-        return None
-    covered = {profile}
-    served_profiles = row.get("served_profiles")
-    if served_profiles is None:
-        return covered
-    if not isinstance(served_profiles, list) or not served_profiles:
-        return None
-    if any(not isinstance(name, str) or not name or name == "unknown" for name in served_profiles):
-        return None
-    covered.update(served_profiles)
+    covered: set[tuple[str, str]] = set()
+    for row in fleet:
+        profile = row.get("profile") if isinstance(row, dict) else None
+        if not profile or profile == "unknown":
+            return None  # unidentified runtime: the matrix cannot vouch for it
+        covered.add(("gateway", profile))
+        covered.update(("gateway", served) for served in row.get("served_profiles") or [])
     return covered
 
 
@@ -212,13 +205,8 @@ def _live_fleet_covers_receipt(expected_sha: str | None, receipt: dict, owed: se
             for row in fleet
         ):
             return False
-        covered_profiles: set[str] = set()
-        for row in fleet:
-            covered = _fleet_row_covered_gateway_profiles(row)
-            if covered is None:
-                return False
-            covered_profiles.update(covered)
-        return owed <= {("gateway", profile) for profile in covered_profiles}
+        covered = _fleet_covered_gateways(fleet)
+        return covered is not None and owed <= covered
     except Exception as exc:
         logger.debug("Could not reconcile pending fleet identities: %s", exc)
         return False
@@ -272,20 +260,13 @@ def _marker_only_restart_obsolete() -> bool:
         return False
     if not fleet:
         return False  # Absence cannot prove recovery of the recorded inventory.
+    covered = _fleet_covered_gateways(fleet)
+    if covered is None:
+        return False  # unidentified runtime: the matrix cannot vouch for it
     for row in fleet:
-        if not isinstance(row, dict):
-            return False
-        if _fleet_row_covered_gateway_profiles(row) is None:
-            return False  # unidentified runtime: the matrix cannot vouch for it
         if row.get("state") != "current" or str(row.get("code_sha")) != expected_sha:
             return False  # stale / down / unknown-identity row still owes the restart
-    covered_profiles: set[str] = set()
-    for row in fleet:
-        covered = _fleet_row_covered_gateway_profiles(row)
-        if covered is None:
-            return False
-        covered_profiles.update(covered)
-    if not owed <= {("gateway", profile) for profile in covered_profiles}:
+    if not owed <= covered:
         return False  # A gateway this marker owns is absent (down) or unidentifiable.
     _clear_fleet_restart_pending_marker()
     logger.debug(

From db302ada44738594f6f73db205a6f4320c694e1f Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 00:51:29 -0700
Subject: [PATCH 018/190] fix(update): `hermes gateway restart` onto a moved
 checkout clears the startup hint

`_update_owes_fleet_restart` held a receipt whose restart phase completed to exactly
`post_update.sha`. A gateway restarted afterwards onto a checkout moved by hand runs code
NEWER than the update pulled, so the remedy the warning itself names (`hermes gateway
restart`) could not clear it until the next `hermes update` wrote a fresh receipt
(#113350 steps 3-4). A completed update is discharged when every owed gateway serves the
code it pulled OR today's checkout; the catch-up predicate `hermes update` runs is
unchanged.
---
 hermes_cli/update_cmd_fleet.py                |  6 ++--
 .../test_update_fleet_restart_pending.py      | 36 +++++++++++++++++++
 2 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/hermes_cli/update_cmd_fleet.py b/hermes_cli/update_cmd_fleet.py
index b4a7cd51c2..52a4a83a83 100644
--- a/hermes_cli/update_cmd_fleet.py
+++ b/hermes_cli/update_cmd_fleet.py
@@ -325,8 +325,10 @@ def _update_owes_fleet_restart(*, receipt: dict | None = None, pending_manual: l
     if not _receipt_reports_stale_runtime(receipt):
         return False
     restarted_to = _receipt_restart_phase_completed(receipt)
-    if restarted_to:
-        return not _live_fleet_covers_receipt(restarted_to, receipt, owed, accept_states=("current", "stale"))
+    # A fleet an operator has since restarted onto a moved checkout (``hermes gateway restart`` —
+    # the remedy this warning names) has nothing of the update left to owe either.
+    if restarted_to and _live_fleet_covers_receipt(restarted_to, receipt, owed, accept_states=("current", "stale")):
+        return False
     return not _live_fleet_covers_receipt(_current_checkout_sha(), receipt, owed)
 
 
diff --git a/tests/hermes_cli/test_update_fleet_restart_pending.py b/tests/hermes_cli/test_update_fleet_restart_pending.py
index 8fbb906ed9..7d52f8eaac 100644
--- a/tests/hermes_cli/test_update_fleet_restart_pending.py
+++ b/tests/hermes_cli/test_update_fleet_restart_pending.py
@@ -858,3 +858,39 @@ def test_startup_warn_silent_when_failed_receipt_already_restarted_fleet(monkeyp
 
     assert capsys.readouterr().err == ""
     assert update_cmd_fleet._pending_fleet_restart_needed() is True
+
+
+def test_startup_warn_silent_when_completed_update_fleet_restarted_onto_moved_checkout(monkeypatch, capsys):
+    """The remedy the warning names must clear it: after a completed update, a manual ``git pull``
+    plus ``hermes gateway restart`` leaves every owed gateway on today's checkout — newer than the
+    update's ``post_update.sha`` — which is nothing that update still owes (#113350 steps 3–4)."""
+    pre, pulled, checkout = "a" * 40, "b" * 40, "c" * 40
+    _patch_marker_sha(monkeypatch, checkout)
+    receipt_dir = get_hermes_home() / "logs" / "update_receipts"
+    receipt_dir.mkdir(parents=True)
+    (receipt_dir / "latest.json").write_text(
+        json.dumps(
+            {
+                "outcome": "success", "exit_code": 0,
+                "pre_update": {"sha": pre}, "post_update": {"sha": pulled},
+                "gateway_restart": {
+                    "restarted_services": ["hermes-gateway"], "relaunched_profiles": [],
+                    "externally_supervised_profiles": [], "killed_pids": [], "failed_units": [],
+                    "incomplete": False, "phase_error": "",
+                },
+                "fleet": [{"profile": "default", "pid": 7, "code_sha": pulled, "state": "current"}],
+                "plan": {"runtimes": [{"kind": "gateway", "profile": "default", "code_sha": pre, "pid": 1}]},
+            }
+        ),
+        encoding="utf-8",
+    )
+    monkeypatch.setattr(
+        "hermes_cli.update_receipt.collect_fleet_versions",
+        lambda **kwargs: [
+            {"profile": "default", "pid": 42, "code_sha": checkout, "code_version": "0.21.3", "state": "current"}
+        ],
+    )
+
+    update_cmd._warn_pending_fleet_restart_on_startup()
+
+    assert capsys.readouterr().err == ""

From 3b9cb0d0765eaf7daa6777a13b9b1df9f4bb2604 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 00:55:19 -0700
Subject: [PATCH 019/190] docs(update): a multiplexer covers every served
 profile in the fleet check

Explain that the matrix shows one row per gateway process, that `served_profiles`
carries coverage for the satellites, and that `hermes gateway restart` now clears the
pending-restart hint on such a fleet.
---
 website/docs/getting-started/updating.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/website/docs/getting-started/updating.md b/website/docs/getting-started/updating.md
index 57fea5acc0..02fe14630a 100644
--- a/website/docs/getting-started/updating.md
+++ b/website/docs/getting-started/updating.md
@@ -130,6 +130,8 @@ The same inventory is embedded in every real update's receipt (`~/.hermes/logs/u
 
 Every `hermes update` run writes a machine-readable receipt to `~/.hermes/logs/update_receipts/` (last 20 kept, `latest.json` always points at the most recent): the pre-update fleet plan, each step taken, anything skipped and why, the gateway restart outcome, and the final fleet version matrix. The SQLite runtime repair is one of those steps (`sqlite_runtime_repair`): a failed repair records the actual reason (for example the `uv sync` error) and the SQLite version pair, a deferred or not-applicable repair lands in the skips with its reason. After the restart phase the updater compares each live gateway's running code against the freshly updated checkout and prints a per-profile matrix — a gateway still serving pre-update code is reported loudly with the exact restart command, and the update exits non-zero so automation never treats a mixed-version fleet as healthy. Both `--plan` and the fleet check ask each running gateway directly over its local control socket (`gateway.sock` in the profile's data directory, a named pipe on Windows) when available, so version and supervisor information comes from the gateway itself; gateways from older versions are still discovered through their state files as before.
 
+A multiplexed default gateway is one process serving several profiles, so it appears once in the matrix and vouches for every profile in its `served_profiles` record. The same coverage clears the "A previous `hermes update` pulled new code but did not restart running gateways" hint: once that gateway (or, after a manual `git pull`, every gateway an update restarted) runs the current code, `hermes gateway restart` is enough — the hint no longer waits for the next `hermes update` to write a fresh receipt.
+
 ### Manual backend restart reminders
 
 After updating, ask the owner of each manually launched backend to relaunch `hermes serve` or `hermes dashboard`; reconnect Desktop for an SSH backend. Restarting gateways alone does not refresh these processes.

From a1cbfc546c95af9f79af3c3a366794804a20d0b0 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 11:54:34 -0700
Subject: [PATCH 020/190] test(update): multiplexer-coverage marker test writes
 the inventory main's marker now owns

Since the fleet-restart-pending marker carries its own runtime inventory on main (a marker
without one stays fail-closed), the #113350 multiplexer test must record the two owed
gateways in the marker it writes, matching its sibling test_startup_warn_discharged_when_fleet_current.
---
 tests/hermes_cli/test_update_fleet_restart_pending.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/tests/hermes_cli/test_update_fleet_restart_pending.py b/tests/hermes_cli/test_update_fleet_restart_pending.py
index 7d52f8eaac..41c63d2825 100644
--- a/tests/hermes_cli/test_update_fleet_restart_pending.py
+++ b/tests/hermes_cli/test_update_fleet_restart_pending.py
@@ -722,7 +722,11 @@ def test_startup_warn_discharged_when_fleet_current(monkeypatch, capsys):
 def test_startup_warn_discharged_when_multiplexer_covers_owed_profiles(monkeypatch, capsys):
     """A current multiplexer discharges every profile named in its live record (#113350)."""
     disk_sha = "e" * 40
-    update_cmd._write_fleet_restart_pending_marker(expected_sha=disk_sha)
+    # The marker owns its inventory (two gateways owed); a marker without one stays fail-closed.
+    update_cmd._write_fleet_restart_pending_marker(
+        expected_sha=disk_sha,
+        runtimes=[{"kind": "gateway", "profile": p} for p in ("default", "coder")],
+    )
     _patch_marker_sha(monkeypatch, disk_sha)
     receipt_dir = get_hermes_home() / "logs" / "update_receipts"
     receipt_dir.mkdir(parents=True)

From d968db3c4b9f26765707a948a94273a4af70b353 Mon Sep 17 00:00:00 2001
From: chelsealong <chelsealong@126.com>
Date: Sat, 5 Sep 2026 12:12:18 +0000
Subject: [PATCH 021/190] fix(mcp): propagate an extended connect_timeout into
 config for OAuth probes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

_probe_single_server's `connect_timeout` override (e.g. hermes mcp login's
315s, given so a user has time to finish a browser OAuth flow) only bounded
the outer asyncio.wait_for(_connect_server(...)). The deep transport code
(_negotiate_session) reads its own session.initialize() bound straight from
config["connect_timeout"], which was left at the unrelated 60s default. Any
OAuth login taking longer than a minute got its still-pending callback wait
cancelled mid-flow, then retried — reopening a second authorization against
the same still-tearing-down callback port ("port already in use").

Related #103633.
---
 hermes_cli/mcp_config.py            |  7 +++++++
 tests/hermes_cli/test_mcp_config.py | 28 ++++++++++++++++++++++++++++
 2 files changed, 35 insertions(+)

diff --git a/hermes_cli/mcp_config.py b/hermes_cli/mcp_config.py
index 2216a45bd0..d5955cb708 100644
--- a/hermes_cli/mcp_config.py
+++ b/hermes_cli/mcp_config.py
@@ -434,6 +434,13 @@ def _probe_single_server(
             connect_timeout = max(1.0, float(config.get("connect_timeout", 30)))
         except (TypeError, ValueError):
             connect_timeout = 30.0
+    # Deep transport code (tools/mcp_tool_transport.py::_negotiate_session) reads its OWN
+    # session.initialize() bound straight off config["connect_timeout"], independent of the
+    # `connect_timeout` param above. Callers that extend the param to give a user time to finish
+    # an OAuth browser flow (e.g. `hermes mcp login`'s 315s) left that inner bound at the
+    # (unrelated) 60s default, so the still-pending OAuth callback wait got cancelled mid-flow —
+    # surfacing as a retry that re-opens a second authorization against the same callback port.
+    config["connect_timeout"] = connect_timeout
 
     _ensure_mcp_loop()
     tools_found: List[Tuple[str, str]] = []
diff --git a/tests/hermes_cli/test_mcp_config.py b/tests/hermes_cli/test_mcp_config.py
index 3a291d849d..2f868e5078 100644
--- a/tests/hermes_cli/test_mcp_config.py
+++ b/tests/hermes_cli/test_mcp_config.py
@@ -562,6 +562,34 @@ class TestProbeEnvResolution:
         assert tools == [("do_thing", "a tool")]
         assert seen["config"]["headers"]["Authorization"] == "Bearer jwt-token-xyz"
 
+    def test_probe_propagates_explicit_connect_timeout_to_config(self, monkeypatch):
+        """An explicit `connect_timeout=` override (e.g. `hermes mcp login`'s 315s, extended so a
+        user has time to finish an OAuth browser flow) must reach `config["connect_timeout"]` —
+        that's what tools/mcp_tool_transport.py::_negotiate_session bounds session.initialize()
+        with. Left stale at its unrelated 60s default, the still-pending OAuth callback wait gets
+        cancelled mid-flow well before the caller's intended deadline."""
+        import hermes_cli.mcp_config as mc
+
+        seen = {}
+
+        class _FakeServer:
+            _tools = []
+
+            async def shutdown(self):
+                return None
+
+        async def _fake_connect(name, config):
+            seen["config"] = config
+            return _FakeServer()
+
+        monkeypatch.setattr("tools.mcp_tool_discovery._connect_server", _fake_connect)
+
+        mc._probe_single_server(
+            "travelermd", {"url": "https://mcp.traveler.md/mcp", "auth": "oauth"}, connect_timeout=315.0
+        )
+
+        assert seen["config"]["connect_timeout"] == 315.0
+
 
 class TestProbeCapabilityGating:
     """The ``details`` probe must not fire prompts/list or resources/list at

From 7eed615690ec528282543cb587bedcb9fd570807 Mon Sep 17 00:00:00 2001
From: Ivyleaguelawyer <anthony@franciscofrancisco.com>
Date: Sun, 23 Aug 2026 10:50:01 -0700
Subject: [PATCH 022/190] fix(mcp): send a User-Agent on SDK-built OAuth
 discovery/registration requests

The MCP SDK builds /.well-known discovery and dynamic client registration
requests as bare httpx.Request objects inside async_auth_flow, so the
client's default headers never apply and they leave with no User-Agent at
all. Some WAFs reject header-less requests outright: coda.io returns 403
on every discovery and registration call, which Hermes then misreports as
"'<server>' only allows pre-approved OAuth clients". The existing
oauth.user_agent option does not help because it is stamped only on
token-endpoint requests.

HermesMCPOAuthProvider's generator bridge now gives SDK-built requests a
default User-Agent ("Hermes-Agent") when the header is absent. The
caller's own MCP request is never touched, and an explicitly configured
oauth.user_agent on token requests still wins.

Reproduced against https://coda.io/apis/mcp: before, every well-known
and /register call returned 403; after, registration returns 200 and the
browser authorization flow proceeds.

Co-Authored-By: claude-flow <ruv@ruv.net>
---
 .../test_mcp_oauth_discovery_user_agent.py    | 105 ++++++++++++++++++
 tools/mcp_oauth_manager.py                    |  35 ++++++
 2 files changed, 140 insertions(+)
 create mode 100644 tests/tools/test_mcp_oauth_discovery_user_agent.py

diff --git a/tests/tools/test_mcp_oauth_discovery_user_agent.py b/tests/tools/test_mcp_oauth_discovery_user_agent.py
new file mode 100644
index 0000000000..8c6bec55bb
--- /dev/null
+++ b/tests/tools/test_mcp_oauth_discovery_user_agent.py
@@ -0,0 +1,105 @@
+"""SDK-built OAuth discovery/registration requests must carry a User-Agent.
+
+The MCP SDK constructs ``/.well-known/...`` discovery and dynamic client
+registration requests as bare ``httpx.Request`` objects inside
+``async_auth_flow``. The client's default headers never apply to them, so
+they leave with NO ``User-Agent`` at all. Some WAFs reject header-less
+requests outright: coda.io answers 403 on every discovery and registration
+call, which Hermes then misreports as "only allows pre-approved OAuth
+clients". (``oauth.user_agent`` does not help — it is stamped only on
+token-endpoint requests.)
+
+``HermesMCPOAuthProvider`` now gives such requests a default User-Agent.
+These tests drive the bridge through the 401 branch so the SDK yields a
+real discovery request, then assert on its headers.
+"""
+from __future__ import annotations
+
+import pytest
+
+
+pytest.importorskip("mcp.client.auth.oauth2", reason="MCP SDK 1.26.0+ required")
+
+
+async def _noop_redirect(url: str) -> None:
+    pass
+
+
+async def _noop_callback():
+    return ("code", None)
+
+
+async def _make_flow(tmp_path, monkeypatch):
+    from tools.mcp_tool import sdk_httpx
+    httpx = sdk_httpx()
+    from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
+    from pydantic import AnyUrl
+
+    from tools.mcp_oauth import HermesTokenStorage
+    from tools.mcp_oauth_manager import _HERMES_PROVIDER_CLS, reset_manager_for_tests
+
+    assert _HERMES_PROVIDER_CLS is not None
+
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+    reset_manager_for_tests()
+
+    storage = HermesTokenStorage("srv")
+    await storage.set_tokens(
+        OAuthToken(access_token="old_access", token_type="Bearer", expires_in=3600, refresh_token="old_refresh")
+    )
+    await storage.set_client_info(
+        OAuthClientInformationFull(
+            client_id="test-client",
+            redirect_uris=[AnyUrl("http://127.0.0.1:12345/callback")],
+            grant_types=["authorization_code", "refresh_token"],
+            response_types=["code"],
+            token_endpoint_auth_method="none",
+        )
+    )
+    provider = _HERMES_PROVIDER_CLS(
+        server_name="srv",
+        server_url="https://example.com/mcp",
+        client_metadata=OAuthClientMetadata(
+            redirect_uris=[AnyUrl("http://127.0.0.1:12345/callback")],
+            client_name="Hermes Agent",
+        ),
+        storage=storage,
+        redirect_handler=_noop_redirect,
+        callback_handler=_noop_callback,
+    )
+    req = httpx.Request("POST", "https://example.com/mcp")
+    return httpx, req, provider.async_auth_flow(req)
+
+
+@pytest.mark.asyncio
+async def test_discovery_request_gets_default_user_agent(tmp_path, monkeypatch):
+    from tools.mcp_oauth_manager import DEFAULT_AUTH_REQUEST_USER_AGENT
+
+    httpx, req, flow = await _make_flow(tmp_path, monkeypatch)
+    outbound = await flow.__anext__()
+
+    fake_401 = httpx.Response(
+        401,
+        request=outbound,
+        headers={"www-authenticate": 'Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource"'},
+    )
+    discovery = await flow.asend(fake_401)
+
+    assert discovery is not req, "SDK must have yielded its own discovery request"
+    assert ".well-known" in str(discovery.url)
+    assert discovery.headers.get("user-agent") == DEFAULT_AUTH_REQUEST_USER_AGENT
+
+    await flow.aclose()
+
+
+@pytest.mark.asyncio
+async def test_callers_mcp_request_is_left_untouched(tmp_path, monkeypatch):
+    """The bridge must not decorate the caller's own MCP request — those
+    headers belong to the transport client, not the OAuth layer."""
+    _httpx, req, flow = await _make_flow(tmp_path, monkeypatch)
+    outbound = await flow.__anext__()
+
+    assert outbound is req
+    assert "user-agent" not in outbound.headers
+
+    await flow.aclose()
diff --git a/tools/mcp_oauth_manager.py b/tools/mcp_oauth_manager.py
index 721756a805..4c66483360 100644
--- a/tools/mcp_oauth_manager.py
+++ b/tools/mcp_oauth_manager.py
@@ -41,6 +41,22 @@ class _ProviderEntry:
     pending_401: dict[str, "asyncio.Future[bool]"] = field(default_factory=dict)
 
 
+def _default_auth_request_user_agent() -> str:
+    """``Hermes-Agent/<version>`` for SDK-built OAuth discovery/registration
+    requests that would otherwise carry no User-Agent at all (see
+    ``_ensure_auth_request_user_agent``). Versioned so server operators
+    debugging a WAF block can tell which client they are looking at — same
+    shape as ``tools.xai_http.hermes_xai_user_agent``."""
+    try:
+        from hermes_cli import __version__
+    except Exception:  # pragma: no cover — defensive
+        __version__ = "unknown"
+    return f"Hermes-Agent/{__version__}"
+
+
+DEFAULT_AUTH_REQUEST_USER_AGENT = _default_auth_request_user_agent()
+
+
 class HermesMCPOAuthProvider(HermesProviderMixin, *_SDK_BASES):
     """OAuthClientProvider with pre-flow disk-mtime reload (external refreshes become visible to
     a running session), expiry seeding on cold load, pre-flight metadata discovery, dead-client
@@ -72,6 +88,24 @@ class HermesMCPOAuthProvider(HermesProviderMixin, *_SDK_BASES):
     def _log_nonfatal(self, what: str, exc: BaseException) -> None:
         logger.debug("MCP OAuth '%s': %s failed (non-fatal): %s", self._hermes_server_name, what, exc)
 
+    def _ensure_auth_request_user_agent(self, outgoing, original) -> None:
+        """Give SDK-built auth requests a User-Agent if they have none.
+
+        The SDK constructs discovery (``/.well-known/...``) and dynamic
+        client registration requests as bare ``httpx.Request`` objects, so
+        the client's default headers never apply and they leave with NO
+        User-Agent at all. Some WAFs reject header-less requests outright
+        (coda.io returns 403 on every one, which Hermes then misreports as
+        "only allows pre-approved OAuth clients").
+
+        Only requests the SDK built itself are touched — never the caller's
+        MCP request — and only when the header is absent, so an
+        ``oauth.user_agent`` stamped on token requests still wins.
+        """
+        if outgoing is original or "user-agent" in outgoing.headers:
+            return
+        outgoing.headers["User-Agent"] = DEFAULT_AUTH_REQUEST_USER_AGENT
+
     async def _initialize(self) -> None:
         """Load stored state, seed ``token_expiry_time``, restore/prefetch metadata. The SDK's
         ``_initialize`` never calls ``update_token_expiry``, so a restarted process would ship stale
@@ -226,6 +260,7 @@ class HermesMCPOAuthProvider(HermesProviderMixin, *_SDK_BASES):
         try:
             outgoing = await inner.__anext__()
             while True:
+                self._ensure_auth_request_user_agent(outgoing, request)
                 # The SDK holds context.lock for its whole generator, even while HTTPX waits on
                 # the MCP request. Release it for that request only; OAuth transitions stay serialized.
                 if outgoing is request:

From 668e505ac7b7c7ec11acadc88cfbe52d24c92748 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 00:57:58 -0700
Subject: [PATCH 023/190] fix(mcp): OAuth discovery/registration carry a
 User-Agent; cancelled login frees its callback port

Widen the salvaged fixes to the whole class and add the pieces they missed:

- The default User-Agent for SDK-built OAuth requests moves from the manager's
  bridge into HermesProviderMixin.async_auth_flow, so the legacy build_oauth_auth
  provider gets it too, and the manager's pre-flight metadata discovery (its own
  client.send of a bare Request) stamps it as well. Why: the SDK sends discovery,
  registration and token requests through client.send(), which never merges the
  client's default headers; www.tradingview.com's WAF answers a header-less GET
  with 403 while curl gets 200, so metadata looked unreadable, the SDK guessed
  /register and /authorize on the MCP host, and the login died with
  "Registration failed: 404" (or, with a pre-registered client, "iss mismatch:
  ... != None" because no issuer was ever discovered).

- The callback listener now runs serve_forever() and is shut down before
  server_close(). A thread parked in handle_request()'s select() keeps the
  closed listening socket alive (the kernel holds the file for the duration
  of the poll), so a flow cancelled mid-wait left the port bound and the
  retry on the same pinned/cached port raised "OAuth callback port N is
  already in use" with no external collider.

- When every authorization-server metadata fetch failed, a registration error
  is re-raised leading with those statuses ("Could not read
  authorization-server metadata (403 from ...); dynamic client registration
  then fell back to a guessed endpoint on the MCP host and failed: ...").
  humanize_oauth_registration_error leaves that message alone so the 403 in
  it is not mistaken for a DCR allowlist refusal.

Docs: mcp-config-reference notes the discovery/registration User-Agent and
the new error lead.
---
 tests/tools/test_mcp_oauth.py                 | 26 ++++++++
 ...y => test_mcp_oauth_discovery_requests.py} | 50 +++++++++++----
 tools/mcp_oauth.py                            | 10 ++-
 tools/mcp_oauth_manager.py                    | 38 +-----------
 tools/mcp_oauth_provider.py                   | 62 +++++++++++++++++++
 .../docs/reference/mcp-config-reference.md    |  4 +-
 6 files changed, 141 insertions(+), 49 deletions(-)
 rename tests/tools/{test_mcp_oauth_discovery_user_agent.py => test_mcp_oauth_discovery_requests.py} (58%)

diff --git a/tests/tools/test_mcp_oauth.py b/tests/tools/test_mcp_oauth.py
index 6a3e2c2946..0cde66ccf5 100644
--- a/tests/tools/test_mcp_oauth.py
+++ b/tests/tools/test_mcp_oauth.py
@@ -1249,6 +1249,32 @@ def test_wait_for_callback_port_in_use_reports_clear_error(monkeypatch):
     assert "timed out" not in msg
 
 
+def test_cancelled_waiter_releases_pinned_port_for_retry(monkeypatch):
+    """A flow cancelled mid-wait (handshake timeout) must leave its pinned/cached port bindable: the
+    retry reuses the same port and previously died with EADDRINUSE because the listener thread parked
+    in select() kept the closed socket alive (#113771)."""
+    import socket
+    import tools.mcp_oauth as mo
+
+    monkeypatch.setattr(mo, "_is_interactive", lambda: False)
+    monkeypatch.setattr(mo, "_raise_if_non_interactive", lambda lead: None)
+    with socket.socket() as probe:
+        probe.bind(("127.0.0.1", 0))
+        port = probe.getsockname()[1]
+    waiter = mo._make_callback_waiter(port, timeout=30)
+
+    async def drive():
+        task = asyncio.create_task(waiter())
+        await asyncio.sleep(0.3)  # listener bound and parked in its poll
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+        with socket.socket() as again:  # what the retry's _start_callback_server does
+            again.bind(("127.0.0.1", port))
+
+    asyncio.run(drive())
+
+
 # ---------------------------------------------------------------------------
 # Figma remote MCP DCR allowlist workarounds
 # ---------------------------------------------------------------------------
diff --git a/tests/tools/test_mcp_oauth_discovery_user_agent.py b/tests/tools/test_mcp_oauth_discovery_requests.py
similarity index 58%
rename from tests/tools/test_mcp_oauth_discovery_user_agent.py
rename to tests/tools/test_mcp_oauth_discovery_requests.py
index 8c6bec55bb..8d312dc467 100644
--- a/tests/tools/test_mcp_oauth_discovery_user_agent.py
+++ b/tests/tools/test_mcp_oauth_discovery_requests.py
@@ -1,4 +1,4 @@
-"""SDK-built OAuth discovery/registration requests must carry a User-Agent.
+"""SDK-built OAuth discovery/registration requests: default User-Agent, and discovery context on failure.
 
 The MCP SDK constructs ``/.well-known/...`` discovery and dynamic client
 registration requests as bare ``httpx.Request`` objects inside
@@ -29,7 +29,7 @@ async def _noop_callback():
     return ("code", None)
 
 
-async def _make_flow(tmp_path, monkeypatch):
+async def _make_flow(tmp_path, monkeypatch, *, registered=True):
     from tools.mcp_tool import sdk_httpx
     httpx = sdk_httpx()
     from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
@@ -47,15 +47,16 @@ async def _make_flow(tmp_path, monkeypatch):
     await storage.set_tokens(
         OAuthToken(access_token="old_access", token_type="Bearer", expires_in=3600, refresh_token="old_refresh")
     )
-    await storage.set_client_info(
-        OAuthClientInformationFull(
-            client_id="test-client",
-            redirect_uris=[AnyUrl("http://127.0.0.1:12345/callback")],
-            grant_types=["authorization_code", "refresh_token"],
-            response_types=["code"],
-            token_endpoint_auth_method="none",
+    if registered:
+        await storage.set_client_info(
+            OAuthClientInformationFull(
+                client_id="test-client",
+                redirect_uris=[AnyUrl("http://127.0.0.1:12345/callback")],
+                grant_types=["authorization_code", "refresh_token"],
+                response_types=["code"],
+                token_endpoint_auth_method="none",
+            )
         )
-    )
     provider = _HERMES_PROVIDER_CLS(
         server_name="srv",
         server_url="https://example.com/mcp",
@@ -73,7 +74,7 @@ async def _make_flow(tmp_path, monkeypatch):
 
 @pytest.mark.asyncio
 async def test_discovery_request_gets_default_user_agent(tmp_path, monkeypatch):
-    from tools.mcp_oauth_manager import DEFAULT_AUTH_REQUEST_USER_AGENT
+    from tools.mcp_oauth_provider import DEFAULT_AUTH_REQUEST_USER_AGENT
 
     httpx, req, flow = await _make_flow(tmp_path, monkeypatch)
     outbound = await flow.__anext__()
@@ -103,3 +104,30 @@ async def test_callers_mcp_request_is_left_untouched(tmp_path, monkeypatch):
     assert "user-agent" not in outbound.headers
 
     await flow.aclose()
+
+
+@pytest.mark.asyncio
+async def test_registration_failure_after_failed_discovery_leads_with_discovery(tmp_path, monkeypatch):
+    """When every authorization-server metadata fetch fails, the SDK guesses ``/register`` on the MCP
+    host; the surfaced error must name the metadata refusal first, not only the fallback 404 (#113771),
+    and must not be mistaken for a DCR allowlist refusal by the humanizer."""
+    from mcp.client.auth.oauth2 import OAuthRegistrationError
+    from tools.mcp_oauth import humanize_oauth_registration_error
+
+    httpx, req, flow = await _make_flow(tmp_path, monkeypatch, registered=False)
+    outbound = await flow.__anext__()
+    response = httpx.Response(401, request=outbound, headers={"www-authenticate": "Bearer"})
+    with pytest.raises(OAuthRegistrationError) as excinfo:
+        for _ in range(10):
+            outbound = await flow.asend(response)
+            url = str(outbound.url)
+            if "oauth-authorization-server" in url or "openid-configuration" in url:
+                response = httpx.Response(403, request=outbound, text="Forbidden")
+            elif outbound.method == "POST":  # the guessed /register on the MCP host
+                response = httpx.Response(404, request=outbound, text='{"detail":"Not Found"}')
+            else:
+                response = httpx.Response(404, request=outbound)
+    msg = str(excinfo.value)
+    assert msg.startswith("Could not read authorization-server metadata (403 from https://example.com/.well-known/oauth-authorization-server")
+    assert "Registration failed: 404" in msg
+    assert humanize_oauth_registration_error("srv", excinfo.value, server_url="https://example.com/mcp") is None
diff --git a/tools/mcp_oauth.py b/tools/mcp_oauth.py
index a65acf8c6c..0c699aad2b 100644
--- a/tools/mcp_oauth.py
+++ b/tools/mcp_oauth.py
@@ -868,7 +868,11 @@ def _make_callback_waiter(port: int, cimd_url: str | None = None, timeout: float
             "context); skipping browser authorization without binding a callback listener.")
         handler_cls, result = _make_callback_handler()
         server = _start_callback_server(port, handler_cls)
-        threading.Thread(target=server.handle_request, daemon=True).start()
+        # serve_forever/shutdown, not a bare handle_request thread: a thread parked in handle_request's
+        # select() keeps the listening socket alive past server_close() (the kernel holds the file for
+        # the duration of the poll), so a cancelled flow — e.g. the handshake timeout firing mid-login —
+        # left the port bound and the retry on the same pinned/cached port died with EADDRINUSE (#113771).
+        threading.Thread(target=server.serve_forever, kwargs={"poll_interval": 0.25}, daemon=True).start()
         # Paste fallback races the HTTP listener; whichever fills result first wins (no stdin reader
         # under a dashboard flow — the gateway's stdin is not the user's).
         if _is_interactive() and dashboard_flow is None:
@@ -883,6 +887,7 @@ def _make_callback_waiter(port: int, cimd_url: str | None = None, timeout: float
                 await asyncio.sleep(0.5)
                 elapsed += 0.5
         finally:
+            server.shutdown()  # returns once the serve loop exits (≤ poll_interval) — the port is free after close
             server.server_close()
         return _callback_outcome(result, cimd_url)
 
@@ -1164,6 +1169,9 @@ def humanize_oauth_registration_error(
     when the user overrode it or an older Hermes is running."""
     msg = str(exc)
     lowered = msg.lower()
+    from tools.mcp_oauth_provider import _DISCOVERY_CONTEXT_LEAD
+    if msg.startswith(_DISCOVERY_CONTEXT_LEAD):  # the 403 there is the metadata fetch, not a DCR refusal
+        return None
     looks_like_registration = ("403" in msg or "forbidden" in lowered) and (
         any(k in lowered for k in ("regist", "dcr", "dynamic client"))
         or lowered.strip() in {"forbidden", "403 forbidden", "http 403: forbidden"}
diff --git a/tools/mcp_oauth_manager.py b/tools/mcp_oauth_manager.py
index 4c66483360..bf9507f460 100644
--- a/tools/mcp_oauth_manager.py
+++ b/tools/mcp_oauth_manager.py
@@ -41,22 +41,6 @@ class _ProviderEntry:
     pending_401: dict[str, "asyncio.Future[bool]"] = field(default_factory=dict)
 
 
-def _default_auth_request_user_agent() -> str:
-    """``Hermes-Agent/<version>`` for SDK-built OAuth discovery/registration
-    requests that would otherwise carry no User-Agent at all (see
-    ``_ensure_auth_request_user_agent``). Versioned so server operators
-    debugging a WAF block can tell which client they are looking at — same
-    shape as ``tools.xai_http.hermes_xai_user_agent``."""
-    try:
-        from hermes_cli import __version__
-    except Exception:  # pragma: no cover — defensive
-        __version__ = "unknown"
-    return f"Hermes-Agent/{__version__}"
-
-
-DEFAULT_AUTH_REQUEST_USER_AGENT = _default_auth_request_user_agent()
-
-
 class HermesMCPOAuthProvider(HermesProviderMixin, *_SDK_BASES):
     """OAuthClientProvider with pre-flow disk-mtime reload (external refreshes become visible to
     a running session), expiry seeding on cold load, pre-flight metadata discovery, dead-client
@@ -88,24 +72,6 @@ class HermesMCPOAuthProvider(HermesProviderMixin, *_SDK_BASES):
     def _log_nonfatal(self, what: str, exc: BaseException) -> None:
         logger.debug("MCP OAuth '%s': %s failed (non-fatal): %s", self._hermes_server_name, what, exc)
 
-    def _ensure_auth_request_user_agent(self, outgoing, original) -> None:
-        """Give SDK-built auth requests a User-Agent if they have none.
-
-        The SDK constructs discovery (``/.well-known/...``) and dynamic
-        client registration requests as bare ``httpx.Request`` objects, so
-        the client's default headers never apply and they leave with NO
-        User-Agent at all. Some WAFs reject header-less requests outright
-        (coda.io returns 403 on every one, which Hermes then misreports as
-        "only allows pre-approved OAuth clients").
-
-        Only requests the SDK built itself are touched — never the caller's
-        MCP request — and only when the header is absent, so an
-        ``oauth.user_agent`` stamped on token requests still wins.
-        """
-        if outgoing is original or "user-agent" in outgoing.headers:
-            return
-        outgoing.headers["User-Agent"] = DEFAULT_AUTH_REQUEST_USER_AGENT
-
     async def _initialize(self) -> None:
         """Load stored state, seed ``token_expiry_time``, restore/prefetch metadata. The SDK's
         ``_initialize`` never calls ``update_token_expiry``, so a restarted process would ship stale
@@ -144,11 +110,12 @@ class HermesMCPOAuthProvider(HermesProviderMixin, *_SDK_BASES):
             build_oauth_authorization_server_metadata_discovery_urls,
             build_protected_resource_metadata_discovery_urls, create_oauth_metadata_request,
             handle_auth_metadata_response, handle_protected_resource_response)
+        from tools.mcp_oauth_provider import stamp_default_user_agent
         server_url = self.context.server_url
 
         async def _send(client, url: str, label: str):
             try:
-                return await client.send(create_oauth_metadata_request(url))
+                return await client.send(stamp_default_user_agent(create_oauth_metadata_request(url)))
             except httpx.HTTPError as exc:
                 logger.debug("MCP OAuth '%s': %s discovery to %s failed: %s", self._hermes_server_name, label, url, exc)
                 return None
@@ -260,7 +227,6 @@ class HermesMCPOAuthProvider(HermesProviderMixin, *_SDK_BASES):
         try:
             outgoing = await inner.__anext__()
             while True:
-                self._ensure_auth_request_user_agent(outgoing, request)
                 # The SDK holds context.lock for its whole generator, even while HTTPX waits on
                 # the MCP request. Release it for that request only; OAuth transitions stay serialized.
                 if outgoing is request:
diff --git a/tools/mcp_oauth_provider.py b/tools/mcp_oauth_provider.py
index 94e216e0a1..cc145827e9 100644
--- a/tools/mcp_oauth_provider.py
+++ b/tools/mcp_oauth_provider.py
@@ -19,6 +19,55 @@ logger = logging.getLogger(__name__)
 # omit ``iss`` from the redirect (#111135). Exact issuer match, nothing else is relaxed.
 _ISS_OMITTING_ISSUERS = frozenset({"https://api.figma.com"})
 
+# Authorization-server metadata documents the SDK tries in its 401 branch (RFC 8414 / OIDC discovery).
+_ASM_DISCOVERY_PATHS = ("/.well-known/oauth-authorization-server", "/.well-known/openid-configuration")
+_DISCOVERY_CONTEXT_LEAD = "Could not read authorization-server metadata"
+
+
+def _default_auth_request_user_agent() -> str:
+    """``Hermes-Agent/<version>`` for SDK-built OAuth requests that would otherwise carry no User-Agent at
+    all; versioned so an operator debugging a WAF block can tell which client they are looking at."""
+    try:
+        from hermes_cli import __version__
+    except Exception:  # pragma: no cover — defensive
+        __version__ = "unknown"
+    return f"Hermes-Agent/{__version__}"
+
+
+DEFAULT_AUTH_REQUEST_USER_AGENT = _default_auth_request_user_agent()
+
+
+def stamp_default_user_agent(request):
+    """Give an SDK-built OAuth request (discovery, registration, token) a User-Agent if it has none.
+
+    The SDK builds those as bare ``httpx.Request`` objects and sends them through ``client.send()``,
+    which never merges the client's default headers, so they leave with NO ``User-Agent`` at all.
+    WAF-fronted authorization servers (www.tradingview.com, coda.io) answer 403 to header-less
+    requests while curl and a plain ``client.get()`` get 200 — the metadata document is then "not
+    found", the SDK falls back to guessing ``/register`` and ``/authorize`` on the MCP host, and the
+    user sees ``Registration failed: 404`` (#113771). Only an absent header is filled, so a
+    configured ``oauth.user_agent`` (token requests) still wins."""
+    if "user-agent" not in request.headers:
+        request.headers["User-Agent"] = DEFAULT_AUTH_REQUEST_USER_AGENT
+    return request
+
+
+def _asm_discovery_failure(response) -> str | None:
+    """``"<status> from <url>"`` when *response* is a failed authorization-server metadata fetch."""
+    req = getattr(response, "request", None)
+    status = getattr(response, "status_code", None)
+    if req is None or status is None or 200 <= status < 300:
+        return None
+    url = str(req.url)
+    return f"{status} from {url}" if any(p in url for p in _ASM_DISCOVERY_PATHS) else None
+
+
+def _with_discovery_context(exc: Exception, failures: list[str]):
+    """Re-shape a registration error raised after every metadata fetch failed: lead with the discovery
+    failure, since the 404 on the guessed ``/register`` URL is only its consequence (#113771)."""
+    return type(exc)(f"{_DISCOVERY_CONTEXT_LEAD} ({'; '.join(failures)}); dynamic client registration "
+                     f"then fell back to a guessed endpoint on the MCP host and failed: {exc}")
+
 
 
 class _RefreshCompletedByPeer(Exception):
@@ -122,6 +171,7 @@ class HermesProviderMixin:
         """
         while True:
             inner = super().async_auth_flow(request)
+            discovery_failures: list[str] = []
             try:
                 sent, thrown = None, None
                 while True:
@@ -135,6 +185,14 @@ class HermesProviderMixin:
                         return
                     except _RefreshCompletedByPeer:
                         break
+                    except Exception as exc:
+                        from mcp.client.auth.oauth2 import OAuthRegistrationError
+                        if (isinstance(exc, OAuthRegistrationError) and discovery_failures
+                                and self.context.oauth_metadata is None):
+                            raise _with_discovery_context(exc, discovery_failures) from exc
+                        raise
+                    if out is not request:
+                        stamp_default_user_agent(out)
                     # Full bidirectional delegation: the SDK drives this flow with
                     # asend(response), so `async for` would swallow the response and
                     # feed the inner generator None. Async generators have no
@@ -146,6 +204,10 @@ class HermesProviderMixin:
                         raise
                     except BaseException as exc:
                         sent, thrown = None, exc
+                    else:
+                        failure = _asm_discovery_failure(sent)
+                        if failure:
+                            discovery_failures.append(failure)
             finally:
                 await self._hermes_release_refresh_fence()
 
diff --git a/website/docs/reference/mcp-config-reference.md b/website/docs/reference/mcp-config-reference.md
index ad3339e3d2..fdd6efd0c1 100644
--- a/website/docs/reference/mcp-config-reference.md
+++ b/website/docs/reference/mcp-config-reference.md
@@ -415,7 +415,9 @@ mcp_servers:
 
 `client_metadata_url` must be an HTTPS URL with a path (no bare origin, no fragment, no userinfo, no `.`/`..` segments) that returns `200` and `Content-Type: application/json` with **no redirect** — authorization servers are forbidden from following redirects when fetching it. Hermes still pins its callback to the same `27890`–`27894` range, so a self-hosted document must declare all ten loopback URIs (`http://127.0.0.1:<port>/callback` and `http://localhost:<port>/callback` for each port), and its `client_id` must be its own URL.
 
-`user_agent` replaces the HTTP library's default `User-Agent` on **token-endpoint requests only** (authorization-code exchange and refresh) — some authorization servers and WAFs reject the default `python-httpx/...` value there. It never applies to MCP traffic or OAuth discovery, and no other token-request headers are configurable. Empty or null values are ignored.
+`user_agent` replaces the HTTP library's default `User-Agent` on **token-endpoint requests only** (authorization-code exchange and refresh) — some authorization servers and WAFs reject the default `python-httpx/...` value there. It never applies to MCP traffic, and no other token-request headers are configurable. Empty or null values are ignored.
+
+OAuth discovery and dynamic-client-registration requests (the `/.well-known/...` metadata documents and the `registration_endpoint` POST) always carry `User-Agent: Hermes-Agent/<version>`. The MCP SDK builds those requests without any client default headers, and WAF-fronted authorization servers answer a header-less request with `403` — the metadata document then looks unreadable, registration falls back to a guessed `/register` on the MCP host, and the login fails with `Registration failed: 404`. When every metadata fetch does fail, the error now leads with those statuses (`Could not read authorization-server metadata (403 from https://…/.well-known/oauth-authorization-server; …)`) before the registration fallback's own error.
 
 ## Add to Hermes link
 

From b5298c387c0fbbe16e163cb8e6aa5e420b4b77c7 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 00:58:31 -0700
Subject: [PATCH 024/190] chore: map contributor email for Ivyleaguelawyer

Attribution mapping for the salvaged #93095 commit.
---
 contributors/emails/anthony@franciscofrancisco.com | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 contributors/emails/anthony@franciscofrancisco.com

diff --git a/contributors/emails/anthony@franciscofrancisco.com b/contributors/emails/anthony@franciscofrancisco.com
new file mode 100644
index 0000000000..e622780d9f
--- /dev/null
+++ b/contributors/emails/anthony@franciscofrancisco.com
@@ -0,0 +1 @@
+Ivyleaguelawyer

From 5a64a888dac3a90db96585bbaf8d5db15a9f3d25 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 04:30:08 -0700
Subject: [PATCH 025/190] fix(mcp): pin the pre-flight discovery User-Agent in
 a test; drop the unfailing version import guard

Review follow-up: swapping tools/mcp_oauth_manager.py back to origin/main kept every
PR test green, so the pre-flight PRM/ASM discovery stamp had no invariant. The existing
prefetch test now records the User-Agent of each mocked discovery request and asserts
it is DEFAULT_AUTH_REQUEST_USER_AGENT (red without the stamp, green with it).

hermes_cli/__init__.py is stdlib-only and defines __version__ at module top, so the
try/except around its import could never fire; import directly.
---
 tests/tools/test_mcp_oauth_cold_load_expiry.py | 7 +++++++
 tools/mcp_oauth_provider.py                    | 5 +----
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/tests/tools/test_mcp_oauth_cold_load_expiry.py b/tests/tools/test_mcp_oauth_cold_load_expiry.py
index 13017d9502..867052512c 100644
--- a/tests/tools/test_mcp_oauth_cold_load_expiry.py
+++ b/tests/tools/test_mcp_oauth_cold_load_expiry.py
@@ -421,8 +421,11 @@ async def test_initialize_prefetches_oauth_metadata_when_missing(
     # MockTransport that mimics BetterStack's split-origin discovery:
     #   PRM at mcp.example.com/.well-known/oauth-protected-resource -> points to auth.example.com
     #   ASM at auth.example.com/.well-known/oauth-authorization-server -> token_endpoint at auth.example.com/oauth/token
+    seen_user_agents: list = []
+
     def mock_handler(request: httpx.Request) -> httpx.Response:
         url = str(request.url)
+        seen_user_agents.append(request.headers.get("User-Agent"))
         if url.endswith("/.well-known/oauth-protected-resource"):
             return httpx.Response(
                 200,
@@ -489,6 +492,10 @@ async def test_initialize_prefetches_oauth_metadata_when_missing(
     assert str(provider.context.oauth_metadata.token_endpoint) == (
         "https://auth.example.com/oauth/token"
     )
+    # Pre-flight discovery requests are SDK-built (no client default headers merged),
+    # so they must carry the stamped User-Agent or WAF-fronted providers 403 them (#113771).
+    from tools.mcp_oauth_provider import DEFAULT_AUTH_REQUEST_USER_AGENT
+    assert seen_user_agents and set(seen_user_agents) == {DEFAULT_AUTH_REQUEST_USER_AGENT}
 
 
 @pytest.mark.asyncio
diff --git a/tools/mcp_oauth_provider.py b/tools/mcp_oauth_provider.py
index cc145827e9..6a35edc7c9 100644
--- a/tools/mcp_oauth_provider.py
+++ b/tools/mcp_oauth_provider.py
@@ -27,10 +27,7 @@ _DISCOVERY_CONTEXT_LEAD = "Could not read authorization-server metadata"
 def _default_auth_request_user_agent() -> str:
     """``Hermes-Agent/<version>`` for SDK-built OAuth requests that would otherwise carry no User-Agent at
     all; versioned so an operator debugging a WAF block can tell which client they are looking at."""
-    try:
-        from hermes_cli import __version__
-    except Exception:  # pragma: no cover — defensive
-        __version__ = "unknown"
+    from hermes_cli import __version__
     return f"Hermes-Agent/{__version__}"
 
 

From edd4ec3124341a5e0e8aebe237433de91739c9e4 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 00:59:11 -0700
Subject: [PATCH 026/190] fix(kanban): book a dead worker the same way
 whichever process notices it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The dead-worker sweep learned a worker's exit status only from
``_recent_worker_exits``, which ``reap_worker_zombies`` fills via
``os.waitpid`` — so only the process that spawned the worker ever knows
how it exited. With ``kanban.dispatch_in_gateway: false`` every
``hermes kanban dispatch`` tick is a fresh process, the registry is
empty, and a worker that exited rc=0 without a terminal board call was
booked as a bare ``crashed`` / ``pid N not alive``: no
``protocol_violation`` marker, no corrective error text for the retry
worker, no violation streak — and a rc=75 quota wall was counted as a
failure instead of a neutral ``rate_limited`` requeue.

A Kanban worker (``HERMES_KANBAN_TASK`` set) now writes
``[kanban-worker-exit] rc=<code>`` as the last line of its own log on
every one-shot exit path; when the registry has no entry for a dead PID
the sweep reads that trailer and books the exit through the same
code -> kind mapping. A worker killed before its exit epilogue leaves no
trailer and stays a plain crash. ``_worker_final_output`` strips the
trailer so it never leaks into the board diagnostic.

Direction (a durable, process-independent witness in the worker log)
from PR #113638; its predicate keyed on the ``Resume this session with:``
summary, which the CLI prints before ``sys.exit`` for rc 0, 1, 75 and 130
alike and so would have booked quota walls and failed turns as protocol
violations.

Co-authored-by: kokhlo <konstantin.khlopkov93@gmail.com>
---
 cli.py                                        |  15 +--
 hermes_cli/kanban_db_dispatch.py              |  68 +++++++++--
 hermes_cli/quiet_single_query.py              |  19 +++
 .../test_kanban_worker_exit_trailer.py        | 114 ++++++++++++++++++
 website/docs/user-guide/features/kanban.md    |   7 +-
 5 files changed, 205 insertions(+), 18 deletions(-)
 create mode 100644 tests/hermes_cli/test_kanban_worker_exit_trailer.py

diff --git a/cli.py b/cli.py
index 21144c3f48..ffc124df4b 100644
--- a/cli.py
+++ b/cli.py
@@ -4153,7 +4153,7 @@ def _run_quiet_single_query(cli, effective_query, emitter=None):
     from agent.turn_author import take_turn_author_from_env
     from hermes_cli.quiet_single_query import (
         adopt_unanswered_turn, bind_quiet_session_key, continue_quiet_notify_completions,
-        quiet_notify_linger_seconds, take_turn_report_path, write_turn_report,
+        exit_single_query, quiet_notify_linger_seconds, take_turn_report_path, write_turn_report,
     )
 
     author = take_turn_author_from_env()
@@ -4171,9 +4171,9 @@ def _run_quiet_single_query(cli, effective_query, emitter=None):
         except KeyboardInterrupt:
             _emit_interrupted_session_end(cli, reason="keyboard_interrupt")
             if emitter is not None:
-                sys.exit(emitter.emit_result({"failed": True, "error": "Interrupted"}, session_id=cli.session_id or "", exit_code=130))
+                exit_single_query(emitter.emit_result({"failed": True, "error": "Interrupted"}, session_id=cli.session_id or "", exit_code=130))
             print(f"\nsession_id: {cli.session_id}", file=sys.stderr)
-            sys.exit(130)
+            exit_single_query(130)
         # The exit line below reports session_id to stderr for automation wrappers;
         # without this sync it would point at the ended parent after compression.
         _sync_cli_session_id_from_agent(cli)
@@ -4242,7 +4242,7 @@ def _run_quiet_single_query(cli, effective_query, emitter=None):
     _exit_code = _single_query_exit_code(result)
     if emitter is not None:
         _exit_code = emitter.emit_result(result, session_id=cli.session_id or "", exit_code=_exit_code)
-    sys.exit(_exit_code)
+    exit_single_query(_exit_code)
 
 
 def _route_single_query_images(cli, query, effective_query, single_query_images, single_query_image_urls):
@@ -4541,8 +4541,9 @@ def _run_single_query_mode(cli, query, image, quiet, oneshot, stream_json: bool
     # isn't engaged) and takes the deterministic approvals.single_query_mode path instead of waiting the
     # full timeout. See #86878.
     os.environ["HERMES_SINGLE_QUERY_SESSION"] = "1"
+    from hermes_cli.quiet_single_query import exit_single_query
     if not cli._claim_active_session("cli", stderr=bool(quiet)):
-        sys.exit(1)
+        exit_single_query(1)
     try:
         query, single_query_images = _collect_query_images(query, image)
         single_query_image_urls = _collect_kanban_task_images(single_query_images)
@@ -4575,7 +4576,7 @@ def _run_single_query_mode(cli, query, image, quiet, oneshot, stream_json: bool
             if emitter is not None:
                 emitter.emit_result({"failed": True, "error": "credentials or agent init failed"},
                                     session_id=cli.session_id or "", exit_code=1)
-            sys.exit(1)  # credentials or agent init failed
+            exit_single_query(1)  # credentials or agent init failed
         # No welcome banner (~420 ms cold); session id / resume hint come from _print_exit_summary().
         _query_label = query or ("[image attached]" if single_query_images else "")
         if _query_label:
@@ -4593,7 +4594,7 @@ def _run_single_query_mode(cli, query, image, quiet, oneshot, stream_json: bool
         cli._print_exit_summary(clear_screen=False)
         # Same exit contract as `-Q`: scripts and the Kanban dispatcher read the outcome from
         # the exit code. This path used to fall through to an implicit 0 for every outcome.
-        sys.exit(_single_query_exit_code(cli._last_turn_result))
+        exit_single_query(_single_query_exit_code(cli._last_turn_result))
     finally:
         _finalize_single_query(cli)
 
diff --git a/hermes_cli/kanban_db_dispatch.py b/hermes_cli/kanban_db_dispatch.py
index 419d653d14..3c195ff61e 100644
--- a/hermes_cli/kanban_db_dispatch.py
+++ b/hermes_cli/kanban_db_dispatch.py
@@ -25,6 +25,8 @@ from typing import Mapping
 from typing import Optional
 from typing import TYPE_CHECKING
 
+from hermes_cli.quiet_single_query import KANBAN_WORKER_EXIT_TRAILER
+
 if TYPE_CHECKING:
     from hermes_cli.kanban_db import Task
 
@@ -179,7 +181,10 @@ def describe_suppression(results: Iterable[Optional["DispatchResult"]]) -> str:
 # ``dispatch_once`` and read by ``detect_crashed_workers`` to classify a dead-pid
 # task. Entry: ``pid -> (raw_wait_status, reaped_at_epoch)``; raw status kept so
 # both WIFEXITED/WEXITSTATUS and WIFSIGNALED can be consulted. Trimmed by age
-# plus a total size cap.
+# plus a total size cap. Process-local by nature (``waitpid`` only reaps our own
+# children): a per-tick ``hermes kanban dispatch`` process finds it empty, so
+# ``_classify_dead_worker_exit`` falls back to the exit trailer the worker
+# leaves in its own log (``KANBAN_WORKER_EXIT_TRAILER``).
 _RECENT_WORKER_EXIT_TTL_SECONDS = 600
 _RECENT_WORKER_EXITS_MAX = 4096
 _recent_worker_exits: "dict[int, tuple[int, float]]" = {}
@@ -229,17 +234,42 @@ def _classify_worker_exit(pid: int) -> "tuple[str, Optional[int]]":
     raw = int(raw)
     signal_number = raw & 0x7F
     if signal_number == 0:
-        code = (raw >> 8) & 0xFF
-        if code == 0:
-            return ("clean_exit", 0)
-        if code == _kb.KANBAN_RATE_LIMIT_EXIT_CODE:
-            return ("rate_limited", code)
-        return ("nonzero_exit", code)
+        return _exit_code_kind((raw >> 8) & 0xFF)
     if signal_number != 0x7F:
         return ("signaled", signal_number)
     return ("unknown", None)
 
 
+def _exit_code_kind(code: int) -> "tuple[str, int]":
+    """``(kind, code)`` for a worker's exit code, however it was observed."""
+    if code == 0:
+        return ("clean_exit", 0)
+    if code == _kb.KANBAN_RATE_LIMIT_EXIT_CODE:
+        return ("rate_limited", code)
+    return ("nonzero_exit", code)
+
+
+_EXIT_TRAILER_RE = re.compile(
+    r"^" + re.escape(KANBAN_WORKER_EXIT_TRAILER) + r"(\d+)\s*$", re.MULTILINE,
+)
+
+
+def _worker_log_exit_code(task_id: str, board: Optional[str] = None) -> Optional[int]:
+    """Exit code from the trailer the worker CLI wrote to its own log; None when absent.
+
+    The durable twin of ``_recent_worker_exits``: written by the worker itself
+    (``hermes_cli.quiet_single_query.exit_single_query``), so it is there whether
+    or not the process running this sweep ever reaped the worker. Last trailer
+    wins — the log is append-mode across re-runs.
+    """
+    try:
+        raw = _kb.read_worker_log(task_id, tail_bytes=4000, board=board)
+    except Exception:
+        return None
+    matches = _EXIT_TRAILER_RE.findall(raw or "")
+    return int(matches[-1]) if matches else None
+
+
 def reap_worker_zombies() -> "list[int]":
     """Reap exited workers without blocking; returns reaped PIDs. POSIX reaps
     every child via ``waitpid(-1)``; Windows polls the ``Popen`` handles
@@ -963,6 +993,7 @@ def _worker_final_output(task_id: str, board: Optional[str] = None) -> str:
         return ""
     if not raw:
         return ""
+    raw = _EXIT_TRAILER_RE.sub("", raw)
     cut = raw.rfind(_EXIT_SUMMARY_MARKER)
     if cut != -1:
         raw = raw[:cut]
@@ -1002,7 +1033,7 @@ def _classify_dead_worker(
     in the event payload, appended to the error text) so the board and the retry
     worker see WHY instead of a bare label; a rate-limited requeue does not need it.
     """
-    dead = _classify_dead_worker_exit(pid, claimer)
+    dead = _classify_dead_worker_exit(pid, claimer, task_id=task_id, board=board)
     if task_id and not dead.rate_limited:
         worker_output = _worker_final_output(task_id, board=board)
         if worker_output:
@@ -1011,9 +1042,26 @@ def _classify_dead_worker(
     return dead
 
 
-def _classify_dead_worker_exit(pid: int, claimer: Optional[str]) -> _DeadWorker:
-    """Exit status -> reclaim bookkeeping, before the worker's own words are folded in."""
+def _classify_dead_worker_exit(
+    pid: int,
+    claimer: Optional[str],
+    *,
+    task_id: Optional[str] = None,
+    board: Optional[str] = None,
+) -> _DeadWorker:
+    """Exit status -> reclaim bookkeeping, before the worker's own words are folded in.
+
+    The reap registry only knows children of THIS process; a per-tick dispatcher
+    reads the exit trailer the worker left in its log instead, so the same death
+    gets the same booking (protocol violation / rate-limit requeue / crash) as
+    under the gateway-embedded dispatcher. A worker that never reached its exit
+    epilogue (killed, OOM) leaves no trailer and stays a plain crash.
+    """
     kind, code = _classify_worker_exit(pid)
+    if kind == "unknown" and task_id:
+        logged = _worker_log_exit_code(task_id, board=board)
+        if logged is not None:
+            kind, code = _exit_code_kind(logged)
     if kind == "clean_exit":
         # rc=0 while still ``running``: usually the work succeeded and only the
         # paperwork was skipped; the corrective sentence reaches the retry
diff --git a/hermes_cli/quiet_single_query.py b/hermes_cli/quiet_single_query.py
index 751ee28a4b..8088a1d7d3 100644
--- a/hermes_cli/quiet_single_query.py
+++ b/hermes_cli/quiet_single_query.py
@@ -13,12 +13,31 @@ from __future__ import annotations
 import contextlib
 import json
 import os
+import sys
 import time
 from typing import Any, Callable, MutableMapping
 
 # Nested A→B→C is one extra turn; this caps a runaway message_agent chain.
 _MAX_QUIET_NOTIFY_ROUNDS = 8
 
+# Last line a Kanban worker leaves in its own log: ``[kanban-worker-exit] rc=<code>``. A per-tick
+# ``hermes kanban dispatch`` process never reaped the worker, so ``os.waitpid`` cannot tell it how
+# the worker exited; the trailer is the process-independent witness the dead-worker sweep reads
+# instead, so a clean exit without a terminal board call is booked as the same protocol violation
+# (and a 75 as the same rate-limit requeue) whichever process notices the death.
+KANBAN_WORKER_EXIT_TRAILER = "[kanban-worker-exit] rc="
+
+
+def exit_single_query(code: int) -> None:
+    """``sys.exit(code)`` for a one-shot turn; a Kanban worker first writes the exit trailer to its log."""
+    if os.environ.get("HERMES_KANBAN_TASK"):
+        with contextlib.suppress(Exception):
+            # stderr: stdout may be the ``--stream-json`` record stream, and the worker log
+            # captures both streams.
+            print(f"\n{KANBAN_WORKER_EXIT_TRAILER}{int(code)}", file=sys.stderr, flush=True)
+    sys.exit(code)
+
+
 # A spawner that bounds only the TURN (the cron Bot Chat lane) hands the quiet child a report
 # path here. The child records the turn's outcome there the moment the turn ends, BEFORE the
 # one-shot exit linger, so the spawner can book the delivery and stop waiting while the linger
diff --git a/tests/hermes_cli/test_kanban_worker_exit_trailer.py b/tests/hermes_cli/test_kanban_worker_exit_trailer.py
new file mode 100644
index 0000000000..8162bf64c9
--- /dev/null
+++ b/tests/hermes_cli/test_kanban_worker_exit_trailer.py
@@ -0,0 +1,114 @@
+"""A dead Kanban worker is booked the same way whichever process notices it.
+
+``_recent_worker_exits`` is filled by ``os.waitpid`` and so only knows children of
+the process running the sweep; a per-tick ``hermes kanban dispatch`` process finds it
+empty. The worker's own exit trailer in its log is the durable witness the sweep reads
+instead, and a tripped protocol-violation budget must hold the card until an operator
+unblocks it.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import pytest
+
+from hermes_cli import kanban_db as kb
+from hermes_cli import kanban_db_connect as kbc
+from hermes_cli import kanban_db_dispatch as kbd
+from hermes_cli.quiet_single_query import KANBAN_WORKER_EXIT_TRAILER, exit_single_query
+
+
+@pytest.fixture
+def kanban_home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    monkeypatch.setenv("HERMES_KANBAN_CRASH_GRACE_SECONDS", "0")
+    monkeypatch.setattr(kb, "_pid_alive", lambda _pid: False)
+    kbd._recent_worker_exits.clear()
+    kb.init_db()
+    return home
+
+
+def _dead_worker_with_log(conn, tid: str, pid: int, rc: int) -> None:
+    """Claim ``tid`` for a worker that already exited ``rc`` and wrote its log — never reaped here."""
+    host = kb._claimer_id().split(":", 1)[0]
+    kb.claim_task(conn, tid, claimer=f"{host}:w{pid}")
+    conn.execute(
+        "UPDATE tasks SET worker_pid=?, worker_started_at=NULL, started_at=? WHERE id=?",
+        (pid, int(time.time()) - 120, tid),
+    )
+    conn.commit()
+    log = kb.worker_log_path(tid)
+    log.parent.mkdir(parents=True, exist_ok=True)
+    with open(log, "a", encoding="utf-8") as f:
+        f.write(f"the model said something\n\nResume this session with:\n  hermes --resume x\n\n{KANBAN_WORKER_EXIT_TRAILER}{rc}\n")
+
+
+@pytest.mark.parametrize(
+    "rc, event, failure_counted",
+    [(0, "protocol_violation", False), (kb.KANBAN_RATE_LIMIT_EXIT_CODE, "rate_limited", False)],
+)
+def test_fresh_process_sweep_books_the_logged_exit_code(kanban_home, rc, event, failure_counted):
+    """Empty reap registry + exit trailer in the log: a clean exit is the protocol violation
+    (marker, streak, no unified-budget hit) and a 75 is a rate-limit requeue — not a bare
+    ``pid N not alive`` crash that counts a failure."""
+    with kbc.connect() as conn:
+        tid = kb.create_task(conn, title="t", assignee="a")
+        _dead_worker_with_log(conn, tid, 70001, rc)
+
+        kbd.detect_crashed_workers(conn)
+
+        ev = conn.execute(
+            "SELECT kind FROM task_events WHERE task_id=? ORDER BY id DESC LIMIT 1", (tid,)).fetchone()
+        run = conn.execute(
+            "SELECT outcome, error, metadata FROM task_runs WHERE task_id=? ORDER BY id DESC LIMIT 1",
+            (tid,)).fetchone()
+        task = kb.get_task(conn, tid)
+        assert ev["kind"] == event
+        assert "not alive" not in (run["error"] or "")
+        assert task.status == "ready"
+        assert task.consecutive_failures == (1 if failure_counted else 0)
+        if rc == 0:
+            assert kb._json_dict(run["metadata"]).get("protocol_violation") is True
+            assert kbd._protocol_violation_streak(conn, tid) == 1
+            assert KANBAN_WORKER_EXIT_TRAILER not in (run["error"] or "")
+        else:
+            assert run["outcome"] == "rate_limited"
+
+
+def test_violation_budget_trip_holds_until_operator_unblock(kanban_home):
+    """The third consecutive clean exit trips the violation budget and ``recompute_ready``
+    must not promote the card back the same tick (``consecutive_failures`` is still below
+    ``failure_limit``); ``unblock_task`` lifts the hold."""
+    with kbc.connect() as conn:
+        tid = kb.create_task(conn, title="loop", assignee="a")
+        for i in range(kbd._PROTOCOL_VIOLATION_FAILURE_LIMIT):
+            _dead_worker_with_log(conn, tid, 71000 + i, 0)
+            kbd.detect_crashed_workers(conn)
+            kb.recompute_ready(conn, failure_limit=10)
+        task = kb.get_task(conn, tid)
+        assert task.status == "blocked"
+        assert task.consecutive_failures < 10
+
+        kb.unblock_task(conn, tid)
+        assert kb.get_task(conn, tid).status == "ready"
+        kb.recompute_ready(conn, failure_limit=10)
+        assert kb.get_task(conn, tid).status == "ready"
+
+
+def test_exit_single_query_writes_trailer_only_for_kanban_workers(monkeypatch, capsys):
+    monkeypatch.delenv("HERMES_KANBAN_TASK", raising=False)
+    with pytest.raises(SystemExit) as exc:
+        exit_single_query(1)
+    assert exc.value.code == 1
+    assert KANBAN_WORKER_EXIT_TRAILER not in capsys.readouterr().err
+
+    monkeypatch.setenv("HERMES_KANBAN_TASK", "t_1")
+    with pytest.raises(SystemExit) as exc:
+        exit_single_query(kb.KANBAN_RATE_LIMIT_EXIT_CODE)
+    assert exc.value.code == kb.KANBAN_RATE_LIMIT_EXIT_CODE
+    assert f"{KANBAN_WORKER_EXIT_TRAILER}{kb.KANBAN_RATE_LIMIT_EXIT_CODE}" in capsys.readouterr().err
diff --git a/website/docs/user-guide/features/kanban.md b/website/docs/user-guide/features/kanban.md
index 837799590e..f164858d27 100644
--- a/website/docs/user-guide/features/kanban.md
+++ b/website/docs/user-guide/features/kanban.md
@@ -565,7 +565,12 @@ therefore exits non-zero: `1` for an ordinary failure, and `75`
 (`EX_TEMPFAIL`) when the provider was rate-limited, overloaded, returning
 5xx or timing out, or the account hit a billing/quota wall — the dispatcher records that run as `rate_limited` and
 requeues the task without counting a failure, so a quota window is never
-booked as a protocol violation.
+booked as a protocol violation. The worker also writes its exit code as the
+last line of its own log (`[kanban-worker-exit] rc=<code>`), so a per-tick
+`hermes kanban dispatch` process — which never reaped the worker and cannot
+read its exit status — books the same death the same way the gateway-embedded
+dispatcher does; a worker killed before it reaches that line is a plain
+`crashed` (`pid <n> not alive`).
 
 **Agent-side prevention:** Before the worker exits, Hermes injects up to two
 synthetic nudges when it detects the model is about to stop without a terminal

From e21a9e502df3a9faa5099020ab67418a84c4ccae Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 00:59:12 -0700
Subject: [PATCH 027/190] fix(kanban): a breaker trip is not promoted back to
 ready in the same tick
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

``_account_crashes`` trips the protocol-violation budget with
``force_trip`` after three consecutive clean exits, but the task's
``consecutive_failures`` is still 1 — so ``recompute_ready``, which
re-derives the threshold from its caller's ``failure_limit`` (default 2),
promoted the just-blocked card straight back to ``ready`` in the same
tick: ``protocol_violation -> gave_up -> promoted -> claimed`` forever
whenever ``failure_limit`` exceeds the violation count (the systemic
same-error trip at limit 1 had the same hole).

``_has_sticky_block`` now also honours the breaker's own verdict: the
newest ``gave_up`` since the last ``unblocked`` holds the card when it
recorded a violation-streak trip or ``failures >= effective_limit``.
``hermes kanban unblock`` remains the release path and still grants a
fresh budget. Tests cover the fresh-process classification (rc=0 and
rc=75), the held trip + operator unblock, and the trailer emission gate.
---
 hermes_cli/kanban_db.py                    | 35 +++++++++++++++-------
 website/docs/user-guide/features/kanban.md |  5 +++-
 2 files changed, 29 insertions(+), 11 deletions(-)

diff --git a/hermes_cli/kanban_db.py b/hermes_cli/kanban_db.py
index d895d1210c..1565f9babf 100644
--- a/hermes_cli/kanban_db.py
+++ b/hermes_cli/kanban_db.py
@@ -2062,22 +2062,37 @@ def _synthesize_ended_run(
 # --- Dependency resolution (todo -> ready) ---
 
 def _has_sticky_block(conn: sqlite3.Connection, task_id: str) -> bool:
-    """True when the newest ``blocked``/``unblocked`` event is ``blocked`` — an
-    explicit ``kanban_block`` that must wait for an operator. A breaker trip
-    emits ``gave_up`` (not ``blocked``) and so auto-recovers, as does a task
-    with no such event at all (direct DB edit).
-
-    See #28712.
-    Returns ``False`` when there is no such event at all (e.g. the task was set to ``status='blocked'`` by
-    the circuit breaker or by direct DB manipulation) — preserves the pre-#28712 auto-recover semantics for
-    that path.
+    """True when the newest ``blocked``/``unblocked``/``gave_up`` event says the
+    block must wait for an operator: an explicit ``kanban_block`` (#28712), or a
+    breaker trip that exhausted the clean-exit protocol-violation budget. The
+    violation budget is a run-history streak independent of
+    ``consecutive_failures``, so ``recompute_ready``'s counter check cannot see
+    it — without this the trip is promoted back to ``ready`` in the same tick and
+    the card respawns forever. A plain (unified-budget) ``gave_up`` is judged by
+    the counter, and a task with no such event at all (direct DB edit) auto-recovers.
     """
     row = conn.execute(
         "SELECT kind FROM task_events "
         "WHERE task_id = ? AND kind IN ('blocked', 'unblocked') "
         "ORDER BY id DESC LIMIT 1", (task_id,),
     ).fetchone()
-    return bool(row) and row["kind"] == "blocked"
+    if row and row["kind"] == "blocked":
+        return True
+    trip = conn.execute(
+        "SELECT payload FROM task_events "
+        "WHERE task_id = ? AND kind = 'gave_up' AND id > COALESCE("
+        "  (SELECT MAX(id) FROM task_events WHERE task_id = ? AND kind = 'unblocked'), 0) "
+        "ORDER BY id DESC LIMIT 1", (task_id, task_id),
+    ).fetchone()
+    if not trip:
+        return False
+    verdict = _json_dict(trip["payload"])
+    # The breaker's own verdict: a violation-streak trip, or a trip whose limit
+    # was not the caller's ``failure_limit`` (systemic same-error crashes trip at 1).
+    return "protocol_violation_limit" in verdict or (
+        "effective_limit" in verdict
+        and int(verdict.get("failures") or 0) >= int(verdict["effective_limit"])
+    )
 
 
 def _latest_event(
diff --git a/website/docs/user-guide/features/kanban.md b/website/docs/user-guide/features/kanban.md
index f164858d27..99d45aadcf 100644
--- a/website/docs/user-guide/features/kanban.md
+++ b/website/docs/user-guide/features/kanban.md
@@ -591,7 +591,10 @@ before reaching the nudge, the dispatcher gives the violation a **bounded retry*
 before auto-blocking the task instead of respawning it into the same loop. The
 budget counts only *consecutive* clean-exit protocol violations — interleaved
 rate-limited requeues are neutral, and any other failure kind resets the
-streak — and a per-task `max_retries` overrides the bound. This usually means
+streak — and a per-task `max_retries` overrides the bound. A card blocked by
+this budget stays blocked (it is not auto-promoted like a below-`failure_limit`
+breaker block) until `hermes kanban unblock <id>`, which also grants a fresh
+retry budget. This usually means
 the model wrote a plain-text answer and exited without using the Kanban tool
 surface.
 

From 84c6e5033989ecb0c24595da4289d5fd87331b58 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 04:01:53 -0700
Subject: [PATCH 028/190] fix(kanban): only a breaker trip stamped sticky holds
 the card past recompute_ready

_has_sticky_block held on 'effective_limit in verdict and failures >= effective_limit',
which is true for every plain unified-budget trip (_record_task_failure only trips when
failures >= effective_limit). That made every breaker trip operator-only and regressed two
recovery paths main relies on: raising the dispatcher failure_limit past the counter
(#35072) and assign_task to a fresh profile (counter reset by design).

_record_task_failure now stamps 'sticky': true on the gave_up payload only for force_trip
(the clean-exit protocol-violation budget) and _account_crashes adds it for the systemic
same-error trip at limit 1; _has_sticky_block reads that marker and nothing else. A plain
gave_up carries no marker and is judged by the counter as before.

The fresh-process sweep test also pins that the decoded rc lands in the run row metadata
(exit_code), so quota (75) vs crash stays tellable after the fact even though the
worker_output tail is trimmed (#113611 related observation).
---
 hermes_cli/kanban_db.py                       | 24 ++++++--------
 hermes_cli/kanban_db_dispatch.py              | 10 +++++-
 .../test_kanban_worker_exit_trailer.py        | 32 +++++++++++++++++++
 3 files changed, 50 insertions(+), 16 deletions(-)

diff --git a/hermes_cli/kanban_db.py b/hermes_cli/kanban_db.py
index 1565f9babf..38396ade79 100644
--- a/hermes_cli/kanban_db.py
+++ b/hermes_cli/kanban_db.py
@@ -2064,12 +2064,14 @@ def _synthesize_ended_run(
 def _has_sticky_block(conn: sqlite3.Connection, task_id: str) -> bool:
     """True when the newest ``blocked``/``unblocked``/``gave_up`` event says the
     block must wait for an operator: an explicit ``kanban_block`` (#28712), or a
-    breaker trip that exhausted the clean-exit protocol-violation budget. The
-    violation budget is a run-history streak independent of
-    ``consecutive_failures``, so ``recompute_ready``'s counter check cannot see
-    it — without this the trip is promoted back to ``ready`` in the same tick and
-    the card respawns forever. A plain (unified-budget) ``gave_up`` is judged by
-    the counter, and a task with no such event at all (direct DB edit) auto-recovers.
+    breaker trip ``_record_task_failure`` stamped ``sticky`` — the clean-exit
+    protocol-violation budget or a systemic same-error wave. Those trip on a
+    policy independent of ``consecutive_failures``, so ``recompute_ready``'s
+    counter check cannot see them — without this the trip is promoted back to
+    ``ready`` in the same tick and the card respawns forever. A plain
+    (unified-budget) ``gave_up`` carries no marker and is judged by the counter,
+    so raising ``failure_limit`` or ``assign_task`` to a fresh profile still
+    releases it; a task with no such event at all (direct DB edit) auto-recovers.
     """
     row = conn.execute(
         "SELECT kind FROM task_events "
@@ -2084,15 +2086,7 @@ def _has_sticky_block(conn: sqlite3.Connection, task_id: str) -> bool:
         "  (SELECT MAX(id) FROM task_events WHERE task_id = ? AND kind = 'unblocked'), 0) "
         "ORDER BY id DESC LIMIT 1", (task_id, task_id),
     ).fetchone()
-    if not trip:
-        return False
-    verdict = _json_dict(trip["payload"])
-    # The breaker's own verdict: a violation-streak trip, or a trip whose limit
-    # was not the caller's ``failure_limit`` (systemic same-error crashes trip at 1).
-    return "protocol_violation_limit" in verdict or (
-        "effective_limit" in verdict
-        and int(verdict.get("failures") or 0) >= int(verdict["effective_limit"])
-    )
+    return bool(trip) and bool(_json_dict(trip["payload"]).get("sticky"))
 
 
 def _latest_event(
diff --git a/hermes_cli/kanban_db_dispatch.py b/hermes_cli/kanban_db_dispatch.py
index 3c195ff61e..5f30da9ef0 100644
--- a/hermes_cli/kanban_db_dispatch.py
+++ b/hermes_cli/kanban_db_dispatch.py
@@ -1229,6 +1229,10 @@ def _account_crashes(conn: sqlite3.Connection, crash_details: list) -> list[str]
             )
         else:
             is_systemic = fp_counts.get(_error_fingerprint(error_text), 0) >= 3
+            extra = {"pid": pid, "claimer": claimer}
+            if is_systemic:
+                # Trips at 1, below any ``failure_limit``: hold it for an operator.
+                extra["sticky"] = True
             tripped = _record_task_failure(
                 conn, tid,
                 error=error_text,
@@ -1236,7 +1240,7 @@ def _account_crashes(conn: sqlite3.Connection, crash_details: list) -> list[str]
                 failure_limit=1 if is_systemic else None,
                 release_claim=False,
                 end_run=False,
-                event_payload_extra={"pid": pid, "claimer": claimer},
+                event_payload_extra=extra,
             )
         if tripped:
             auto_blocked.append(tid)
@@ -1405,6 +1409,10 @@ def _record_task_failure(
                     "retry_status": retry_status,
                 },
             )
+        if force_trip:
+            # The caller applied its own bounded policy, so the counter cannot
+            # judge this block: ``recompute_ready`` holds it for an operator.
+            payload["sticky"] = True
         if event_payload_extra:
             payload.update(event_payload_extra)
         _kb._append_event(conn, task_id, "gave_up", payload, run_id=run_id)
diff --git a/tests/hermes_cli/test_kanban_worker_exit_trailer.py b/tests/hermes_cli/test_kanban_worker_exit_trailer.py
index 8162bf64c9..85a86b1857 100644
--- a/tests/hermes_cli/test_kanban_worker_exit_trailer.py
+++ b/tests/hermes_cli/test_kanban_worker_exit_trailer.py
@@ -72,6 +72,9 @@ def test_fresh_process_sweep_books_the_logged_exit_code(kanban_home, rc, event,
         assert "not alive" not in (run["error"] or "")
         assert task.status == "ready"
         assert task.consecutive_failures == (1 if failure_counted else 0)
+        # The decoded rc lands in the run row so quota (75) vs crash stays tellable after
+        # the fact even though the worker_output tail is trimmed (#113611).
+        assert kb._json_dict(run["metadata"]).get("exit_code") == rc
         if rc == 0:
             assert kb._json_dict(run["metadata"]).get("protocol_violation") is True
             assert kbd._protocol_violation_streak(conn, tid) == 1
@@ -100,6 +103,35 @@ def test_violation_budget_trip_holds_until_operator_unblock(kanban_home):
         assert kb.get_task(conn, tid).status == "ready"
 
 
+def test_plain_budget_trip_still_auto_recovers(kanban_home):
+    """A unified-budget trip carries no ``sticky`` marker, so the two recovery paths on main
+    survive: raising the dispatcher ``failure_limit`` past the counter promotes the card, and
+    ``assign_task`` to a fresh profile (counter reset by design) promotes it too."""
+    with kbc.connect() as conn:
+        tids = [kb.create_task(conn, title=t, assignee="a") for t in ("raise-limit", "reassign")]
+        for tid in tids:
+            for i in range(2):
+                kbd._record_task_failure(
+                    conn, tid, error=f"boom{i}", outcome="crashed", failure_limit=2,
+                    release_claim=False, end_run=False,
+                )
+            assert kb.get_task(conn, tid).status == "blocked"
+        assert kb.recompute_ready(conn, failure_limit=2) == 0
+
+        assert kb.recompute_ready(conn, failure_limit=5) == 2
+        assert kb.get_task(conn, tids[0]).status == "ready"
+
+        for i in range(2):
+            kbd._record_task_failure(
+                conn, tids[1], error=f"again{i}", outcome="crashed", failure_limit=2,
+                release_claim=False, end_run=False,
+            )
+        assert kb.get_task(conn, tids[1]).status == "blocked"
+        kb.assign_task(conn, tids[1], "other-profile")
+        assert kb.recompute_ready(conn, failure_limit=2) == 1
+        assert kb.get_task(conn, tids[1]).status == "ready"
+
+
 def test_exit_single_query_writes_trailer_only_for_kanban_workers(monkeypatch, capsys):
     monkeypatch.delenv("HERMES_KANBAN_TASK", raising=False)
     with pytest.raises(SystemExit) as exc:

From f0c26f0554c4fa89b7554b7fb76adbb4b12da7bd Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 00:49:21 -0700
Subject: [PATCH 029/190] fix(mcp): name the HTTP status, URL and body behind
 "Server returned an error response"
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

mcp >= 2.0's Streamable HTTP client folds any non-2xx whose body it cannot parse
as a JSON-RPC error into the opaque `-32603 Server returned an error response`.
Hermes printed that text verbatim in the SSE-fallback warning and in the
"both transports failed" ConnectionError, so users saw no status, no URL and
none of the server's own words (e.g. `400 {"code":-32020,"message":"Unsupported
MCP-Protocol-Version"}`) and had to reach for curl to learn what the server
actually said (#114350, #113359).

- `_make_http_rejection_recorder`: response hook on the owned SDK-httpx client
  that remembers the last 4xx/5xx (status, method, URL, head of the body; SSE
  bodies are never read). Sibling of the redirect-header stripper hook.
- `_describe_http_failure`: appends that detail only when the root cause is
  the SDK's opaque -32603 text, so a real JSON-RPC error or an httpx status
  error is never duplicated.
- `_run_http`: the fallback warning and both raise paths (both-transports
  ConnectionError; the no-fallback re-raise after a proven session, strict
  redirect headers or a non-rejection) carry the detail. Debug-logs the
  endpoint each connect attempt uses.
- Docs: troubleshooting entry for reading the new message.

Verified live against a real Streamable HTTP server (`hermes mcp test`, temp
HERMES_HOME): base prints `Streamable HTTP: Server returned an error response`;
fixed head prints `... (HTTP 400 from POST http://127.0.0.1:PORT/mcp:
{"jsonrpc":"2.0","id":null,"error":{"code":-32020,...}})`. Control: a 400
served as application/json already surfaces the JSON-RPC message and gets no
appendix; servers negotiating `initialize` down to 2025-06-18 (fixture and a
real FastMCP on mcp 1.12.4) connect and list tools on base and fix alike — the
pinned mcp 2.0.0 stamps the negotiated version on every post-handshake request
(wire-recorded), so the sticky seed in `_run_http` is not the cause of the
reported 400 and stays as designed (#14816).

Co-authored-by: JoaoMarcos44 <joaomarcosdias444@gmail.com>
---
 tests/tools/test_mcp_sse_fallback.py    | 58 +++++++++++++++++++++++++
 tools/mcp_tool.py                       |  3 ++
 tools/mcp_tool_errors.py                | 43 ++++++++++++++++++
 tools/mcp_tool_transport.py             | 17 ++++++--
 website/docs/user-guide/features/mcp.md | 16 +++++++
 5 files changed, 133 insertions(+), 4 deletions(-)

diff --git a/tests/tools/test_mcp_sse_fallback.py b/tests/tools/test_mcp_sse_fallback.py
index 16b5b957b2..cc5433bdb8 100644
--- a/tests/tools/test_mcp_sse_fallback.py
+++ b/tests/tools/test_mcp_sse_fallback.py
@@ -84,3 +84,61 @@ def test_both_transports_failing_names_both_and_suggests_config(monkeypatch):
         asyncio.run(task._run_http(dict(_CONFIG)))
     assert calls == ["HTTP", "SSE"] or calls == ["legacy HTTP", "SSE"]
     assert task._sse_fallback is False  # failed fallback must not latch
+
+
+def test_opaque_sdk_rejection_is_reported_with_the_servers_status_and_body(monkeypatch, caplog):
+    """mcp >= 2.0 folds a non-JSON 4xx into ``-32603 Server returned an error response``; the
+    warning and the both-transports ConnectionError must still name the HTTP status, the URL that
+    was requested and the body the server sent (#114350, #113359). A root that already carries the
+    status (httpx ``HTTPStatusError``) is left alone — no duplicated detail."""
+    from tools.mcp_tool_errors import _make_http_rejection_recorder
+    from tools.mcp_tool import sdk_httpx
+
+    httpx2 = sdk_httpx()
+    body = '{"jsonrpc":"2.0","error":{"code":-32020,"message":"Unsupported MCP-Protocol-Version"}}'
+
+    async def _real_client_roundtrip(status, content_type):
+        """The recorder on a real SDK-httpx client, through the streaming API the SDK uses; the
+        SDK's own later ``aread()`` must still see the bytes."""
+        sink: dict = {}
+        transport = httpx2.MockTransport(
+            lambda req: httpx2.Response(status, text=body, headers={"content-type": content_type}))
+        async with httpx2.AsyncClient(transport=transport, event_hooks={
+                "response": [_make_http_rejection_recorder(sink)]}) as client:
+            async with client.stream("POST", "http://127.0.0.1:1/mcp", json={}) as resp:
+                assert (await resp.aread()).decode() == body
+        return sink
+
+    assert asyncio.run(_real_client_roundtrip(200, "application/json")) == {}  # 2xx: nothing recorded
+    recorded = asyncio.run(_real_client_roundtrip(400, "text/plain; charset=utf-8"))
+    assert recorded == {"status": 400, "method": "POST", "url": "http://127.0.0.1:1/mcp", "body": body}
+
+    def _connect_sees(rejection):
+        task, _calls = _task(monkeypatch, ExceptionGroup("g", [_SdkInternalError()]),
+                             sse_exc=ConnectionRefusedError("no sse"))
+        monkeypatch.setattr(MCPServerTask, "_streamable_http_transport",
+                            lambda self, *a, **k: self._http_rejection.update(rejection) or object())
+        with pytest.raises(ConnectionError) as info:
+            asyncio.run(task._run_http(dict(_CONFIG)))
+        return str(info.value)
+
+    with caplog.at_level("WARNING", logger="tools.mcp_tool"):
+        message = _connect_sees(recorded)
+    detail = "Server returned an error response (HTTP 400 from POST http://127.0.0.1:1/mcp: " + body + ")"
+    assert detail in message and "SSE: no sse" in message
+    assert any(detail in rec.getMessage() for rec in caplog.records), caplog.text
+
+    # No rejection observed (the hook never fired): the SDK text stands alone, no fabricated detail.
+    assert "Streamable HTTP: Server returned an error response; SSE" in _connect_sees({})
+
+
+def test_opaque_rejection_without_fallback_surfaces_the_status(monkeypatch):
+    """After a proven session the SSE fallback is off; the opaque SDK error still leaves ``_run_http``
+    naming the recorded rejection instead of the bare ``Server returned an error response``."""
+    task, calls = _task(monkeypatch, ExceptionGroup("g", [_SdkInternalError()]))
+    task._ever_connected = True
+    monkeypatch.setattr(MCPServerTask, "_streamable_http_transport", lambda self, *a, **k: self._http_rejection.update(
+        status=503, method="POST", url="http://127.0.0.1:1/mcp", body="upstream down") or object())
+    with pytest.raises(ConnectionError, match=r"HTTP 503 from POST http://127\.0\.0\.1:1/mcp: upstream down"):
+        asyncio.run(task._run_http(dict(_CONFIG)))
+    assert "SSE" not in calls
diff --git a/tools/mcp_tool.py b/tools/mcp_tool.py
index 69fee3176c..b4abae11ef 100644
--- a/tools/mcp_tool.py
+++ b/tools/mcp_tool.py
@@ -348,6 +348,9 @@ class MCPServerTask(MCPServerRunMixin, MCPServerTransportMixin, MCPServerHealthM
         self._ever_connected: bool = False
         # Latched when the Streamable HTTP -> SSE fallback connects: reconnects reuse SSE directly.
         self._sse_fallback: bool = False
+        # Status/URL/body of the last HTTP rejection the Streamable HTTP client saw; names the real
+        # cause when the SDK reports only ``Server returned an error response``.
+        self._http_rejection: dict = {}
         # True from park until proven healthy again; logs the revival once.
         self._was_parked: bool = False
         # Why the server is parked (the revival_reason handed to _park), None once healthy again.
diff --git a/tools/mcp_tool_errors.py b/tools/mcp_tool_errors.py
index d74bdbb050..2052d99afd 100644
--- a/tools/mcp_tool_errors.py
+++ b/tools/mcp_tool_errors.py
@@ -82,6 +82,49 @@ def _is_streamable_http_rejection(exc: BaseException) -> bool:
     return code == -32603 and "server returned an error response" in str(root).lower()
 
 
+_HTTP_REJECTION_BODY_CHARS = 300
+
+
+def _make_http_rejection_recorder(sink: dict):
+    """httpx response hook for the owned Streamable HTTP client: remembers the last 4xx/5xx the server
+    sent (status, method, URL, head of the body). mcp >= 2.0 folds a non-2xx whose body it cannot
+    parse as a JSON-RPC error into the opaque ``-32603 Server returned an error response`` — the
+    status and the server's own words (e.g. ``400 {"code":-32020,"message":"Unsupported
+    MCP-Protocol-Version"}``) never reach the exception, so this is the only place they can be
+    observed. SSE bodies are never read (a stream would block the hook)."""
+
+    async def _record(response):
+        if response.status_code < 400:
+            return
+        body = ""
+        if response.headers.get("content-type", "").split(";")[0].strip().lower() != "text/event-stream":
+            try:
+                raw = await response.aread()  # buffered: the SDK's own aread() afterwards sees the same bytes
+                body = " ".join(raw[:_HTTP_REJECTION_BODY_CHARS * 4].decode("utf-8", "replace").split())
+            except Exception:  # the failure itself is still reported, just without the body
+                body = ""
+        sink.update(status=response.status_code, method=response.request.method,
+                    url=str(response.request.url), body=body[:_HTTP_REJECTION_BODY_CHARS])
+
+    return _record
+
+
+def _describe_http_failure(exc: BaseException, rejection: dict) -> str:
+    """``str(root cause)`` of a Streamable HTTP connect failure; when that root is the SDK's opaque
+    ``-32603 Server returned an error response`` and the recorder saw the rejection, the HTTP status,
+    request URL and body head are appended so the message names what the server actually said."""
+    root = _unwrap_exception_group(exc)
+    text = str(root)
+    opaque = (getattr(getattr(root, "error", None), "code", None) == -32603
+              and "server returned an error response" in text.lower())
+    if not (opaque and rejection):
+        return text
+    detail = f"HTTP {rejection['status']} from {rejection['method']} {rejection['url']}"
+    if rejection["body"]:
+        detail += f": {rejection['body']}"
+    return f"{text} ({detail})"
+
+
 def _unwrap_exception_group(exc: BaseException) -> BaseException:
     """Root-cause leaf of anyio ``(Base)ExceptionGroup`` wrappers (group ``str()`` is opaque). A
     ``KeyboardInterrupt``/``SystemExit`` leaf anywhere is re-raised, never flattened into a loggable
diff --git a/tools/mcp_tool_transport.py b/tools/mcp_tool_transport.py
index 1c4372f180..835a2bfe65 100644
--- a/tools/mcp_tool_transport.py
+++ b/tools/mcp_tool_transport.py
@@ -12,7 +12,7 @@ from typing import Dict, Optional, Set
 from utils import normalize_proxy_url
 from agent.proxy_bypass import is_loopback_host, should_bypass_proxy
 from agent import runtime_cwd as _runtime_cwd
-from tools.mcp_tool_errors import NonMcpEndpointError, _apply_identity_header, _handshake_rejected_as_modern, _is_streamable_http_rejection, _make_mcp_body_cap_transport, _make_redirect_header_stripper, _resolve_client_cert, _unwrap_exception_group
+from tools.mcp_tool_errors import NonMcpEndpointError, _apply_identity_header, _describe_http_failure, _handshake_rejected_as_modern, _is_streamable_http_rejection, _make_http_rejection_recorder, _make_mcp_body_cap_transport, _make_redirect_header_stripper, _resolve_client_cert, _unwrap_exception_group
 from tools.mcp_tool_lifecycle import _filter_mcp_children, _orphan_stdio_pid_servers, _orphan_stdio_pids, _stdio_pgids, _stdio_pids
 from tools.mcp_tool_common import _core
 from tools import mcp_tool_config as _config
@@ -442,7 +442,8 @@ class MCPServerTransportMixin:
         inner_transport = httpx.AsyncHTTPTransport(verify=ssl_verify, **_present(cert=client_cert))
         client_kwargs: dict = {"follow_redirects": True, "timeout": httpx.Timeout(float(connect_timeout), read=300.0),
                                **({"headers": headers} if headers else {}),
-                               "event_hooks": {"response": [_strip_auth_on_cross_origin_redirect]},
+                               "event_hooks": {"response": [_strip_auth_on_cross_origin_redirect,
+                                                            _make_http_rejection_recorder(self._http_rejection)]},
                                "transport": _make_mcp_body_cap_transport(httpx, inner_transport),
                                **_present(mounts=_mcp_proxy_mounts(httpx, url, ssl_verify, client_cert, self.name),
                                           auth=oauth_auth)}
@@ -462,6 +463,8 @@ class MCPServerTransportMixin:
                               "mcp.client.streamable_http is not available. "
                               "Upgrade the mcp package to get HTTP support.")
         url = config["url"]
+        logger.debug("MCP server '%s': connecting to %s", self.name, url)
+        self._http_rejection = {}  # last 4xx/5xx the owned client saw this attempt (recorder hook)
         headers = dict(config.get("headers") or {})
         # Agent Plugins v1 strict_redirect_headers: configured headers MUST NOT follow a cross-origin
         # redirect — capture their names BEFORE client-generated headers are merged in.
@@ -486,6 +489,9 @@ class MCPServerTransportMixin:
         try:
             return await self._serve_transport(transport, label, float(connect_timeout))
         except Exception as exc:
+            # The SDK folds a non-2xx it cannot parse into ``-32603 Server returned an error response``;
+            # the recorder hook kept the status/URL/body the server actually sent (#114350, #113359).
+            http_detail = _describe_http_failure(exc, self._http_rejection)
             # SSE-only servers (or their load balancers) reject the Streamable HTTP chunked
             # ``initialize`` POST — with a 400-family status or an opaque SDK INTERNAL_ERROR —
             # previously a permanent failure with 0 active tools unless the user set
@@ -496,12 +502,15 @@ class MCPServerTransportMixin:
             # transport mismatch — ``_is_streamable_http_rejection`` matches neither), and never
             # with ``strict_redirect_headers`` (SSE cannot enforce that boundary).
             if (self._ever_connected or common[-1] or not _is_streamable_http_rejection(exc)):
+                if http_detail != str(_unwrap_exception_group(exc)):  # opaque SDK error + a recorded rejection
+                    raise ConnectionError(f"MCP server '{self.name}': Streamable HTTP connect failed "
+                                          f"({http_detail})") from exc
                 raise
             logger.warning(
                 "MCP server '%s': Streamable HTTP rejected the initial connect (%s) — retrying "
                 "over SSE. If this connects, set `transport: sse` for this server in config.yaml "
                 "to skip the failed attempt on future startups.",
-                self.name, _unwrap_exception_group(exc))
+                self.name, http_detail)
             try:
                 self._sse_fallback = True
                 return await self._serve_transport(self._sse_transport(*common), "SSE", float(connect_timeout))
@@ -511,7 +520,7 @@ class MCPServerTransportMixin:
                 self._sse_fallback = False
                 raise ConnectionError(
                     f"MCP server '{self.name}': both Streamable HTTP and SSE transports failed "
-                    f"(Streamable HTTP: {_unwrap_exception_group(exc)}; SSE: "
+                    f"(Streamable HTTP: {http_detail}; SSE: "
                     f"{_unwrap_exception_group(sse_exc)}). Check the URL points at an MCP "
                     "endpoint, or pin `transport: sse` if the server is SSE-only.") from sse_exc
 
diff --git a/website/docs/user-guide/features/mcp.md b/website/docs/user-guide/features/mcp.md
index 3dfb377f26..fced6aaf4e 100644
--- a/website/docs/user-guide/features/mcp.md
+++ b/website/docs/user-guide/features/mcp.md
@@ -800,6 +800,22 @@ npx --version
 
 Then verify your config and restart Hermes.
 
+### Remote (HTTP) server rejects the connection
+
+`hermes mcp test <name>` reports what the server actually answered. When the MCP SDK can only say
+`Server returned an error response` (a 4xx/5xx whose body is not a JSON-RPC error), Hermes appends
+the HTTP status, the URL it requested and the start of the response body:
+
+```
+Streamable HTTP: Server returned an error response (HTTP 400 from POST http://host:27200/mcp:
+{"jsonrpc":"2.0","error":{"code":-32020,"message":"Unsupported MCP-Protocol-Version"}})
+```
+
+Read the status and body first: a `400`/`405` on the `initialize` POST usually means the endpoint
+speaks SSE only (set `transport: sse`) or a proxy in front of it rejects the request; a `401`/`403`
+means the token or OAuth grant is wrong; an HTML body means the URL points at a web page, not an MCP
+endpoint. `hermes logs --level debug` additionally shows the exact endpoint each connect attempt used.
+
 ### Tools not appearing
 
 Possible causes:

From 9bd8257c027444fcac9094e8cf8626086c42a167 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 05:14:08 -0700
Subject: [PATCH 030/190] fix(mcp): complete the handshake when a stateless
 server names a modern protocolVersion and lacks server/discover

A server that answers the legacy initialize with HTTP 200 but reports
2026-07-28 (regardless of the version offered) makes the SDK raise
'Unsupported protocol version from the server'. auto mode then falls back
to server/discover, which such a server rejects with a non-JSON 4xx, and
the connect died with 'both Streamable HTTP and SSE transports failed
(Streamable HTTP: Server returned an error response; SSE: 405)' even
though the same initialize/tools/list POSTs succeed from curl (#113359).

When both fail for that reason, re-run initialize ourselves, adopt the
result pinned to the version we offered (keeps later requests
legacy-shaped, which the handshake just proved the server accepts), send
notifications/initialized and proceed to tools/list.
---
 tests/tools/test_mcp_protocol_negotiation.py | 46 ++++++++++++++++++++
 tools/mcp_tool_errors.py                     |  7 +++
 tools/mcp_tool_transport.py                  | 39 ++++++++++++++++-
 3 files changed, 90 insertions(+), 2 deletions(-)

diff --git a/tests/tools/test_mcp_protocol_negotiation.py b/tests/tools/test_mcp_protocol_negotiation.py
index aff171bac3..b1cdc6c0a6 100644
--- a/tests/tools/test_mcp_protocol_negotiation.py
+++ b/tests/tools/test_mcp_protocol_negotiation.py
@@ -139,3 +139,49 @@ class TestModernRejectionClassifier:
         assert _handshake_rejected_as_modern(Exception("Unsupported protocol version"))
         assert _handshake_rejected_as_modern(Exception("Unknown method: initialize"))
         assert not _handshake_rejected_as_modern(Exception("connection reset by peer"))
+
+
+class _EchoingStatelessSession(_Session):
+    """A stateless server that answers the legacy ``initialize`` 200 but names a protocolVersion
+    outside the SDK's handshake set (#113359): the SDK raises RuntimeError AFTER the wire exchange
+    succeeded, and the server has no ``server/discover``. Exposes the SDK's manual-handshake
+    surface (``send_request`` / ``adopt`` / ``send_notification``)."""
+
+    def __init__(self, disc):
+        super().__init__(init=RuntimeError("Unsupported protocol version from the server: 2026-07-28"), disc=disc)
+        self.adopted = None
+
+    async def send_request(self, request, result_type):
+        self.calls.append(("send_request", request.method))
+        import mcp.types as types
+        return types.InitializeResult(
+            protocolVersion="2026-07-28", capabilities=types.ServerCapabilities(tools=types.ToolsCapability()),
+            serverInfo=types.Implementation(name="StatelessServer", version="ESF"))
+
+    def adopt(self, result):
+        self.calls.append("adopt")
+        self.adopted = result
+
+    async def send_notification(self, notification):
+        self.calls.append(("notify", notification.method))
+
+
+class TestModernVersionEchoedToLegacyHandshake:
+    """#113359: a stateless server that accepts ``initialize`` but reports 2026-07-28 and 400s
+    ``server/discover`` must still connect — the handshake succeeded on the wire."""
+
+    def test_auto_completes_the_handshake_at_the_offered_version_when_discover_fails(self):
+        from tools import mcp_tool as _core
+        s = _EchoingStatelessSession(disc=_Err(-32603, "Server returned an error response"))
+        out = _run(_task()._negotiate_session(s, 5))
+        assert out.capabilities.tools is not None
+        assert s.calls == ["initialize", "discover", ("send_request", "initialize"), "adopt",
+                           ("notify", "notifications/initialized")]
+        assert s.adopted.protocol_version == _core.LATEST_HANDSHAKE_VERSION  # later requests stay legacy-shaped
+
+    def test_genuine_unsupported_version_error_never_re_handshakes(self):
+        s = _Session(init=_Err(_JSONRPC_UNSUPPORTED_PROTOCOL_VERSION, "unsupported protocol version"),
+                     disc=_Err(-32603, "Server returned an error response"))
+        with pytest.raises(_Err, match="Server returned an error response"):
+            _run(_task()._negotiate_session(s, 5))
+        assert s.calls == ["initialize", "discover"]
diff --git a/tools/mcp_tool_errors.py b/tools/mcp_tool_errors.py
index 2052d99afd..2227ea8d91 100644
--- a/tools/mcp_tool_errors.py
+++ b/tools/mcp_tool_errors.py
@@ -34,6 +34,13 @@ def _handshake_rejected_as_modern(exc: BaseException) -> bool:
         code=getattr(exc, "code", None)) or _is_method_not_found_error(exc)
 
 
+def _handshake_answered_with_unsupported_version(exc: BaseException) -> bool:
+    """True when ``initialize`` SUCCEEDED on the wire (HTTP 200, a valid InitializeResult) but the SDK
+    refused the ``protocolVersion`` the server named — its ``RuntimeError("Unsupported protocol version
+    from the server: ...")``. Distinct from a JSON-RPC -32022 rejection, where the server refused us."""
+    return "unsupported protocol version from the server" in str(_unwrap_exception_group(exc)).lower()
+
+
 def _is_method_not_found_error(exc: BaseException) -> bool:
     """True if *exc* is a JSON-RPC ``method not found`` (-32601; ``ping`` is optional in MCP). The
     substring fallback includes "Unknown method: <name>" — without it the ping→list_tools keepalive
diff --git a/tools/mcp_tool_transport.py b/tools/mcp_tool_transport.py
index 835a2bfe65..b042ebad0a 100644
--- a/tools/mcp_tool_transport.py
+++ b/tools/mcp_tool_transport.py
@@ -12,7 +12,7 @@ from typing import Dict, Optional, Set
 from utils import normalize_proxy_url
 from agent.proxy_bypass import is_loopback_host, should_bypass_proxy
 from agent import runtime_cwd as _runtime_cwd
-from tools.mcp_tool_errors import NonMcpEndpointError, _apply_identity_header, _describe_http_failure, _handshake_rejected_as_modern, _is_streamable_http_rejection, _make_http_rejection_recorder, _make_mcp_body_cap_transport, _make_redirect_header_stripper, _resolve_client_cert, _unwrap_exception_group
+from tools.mcp_tool_errors import NonMcpEndpointError, _apply_identity_header, _describe_http_failure, _handshake_answered_with_unsupported_version, _handshake_rejected_as_modern, _is_streamable_http_rejection, _make_http_rejection_recorder, _make_mcp_body_cap_transport, _make_redirect_header_stripper, _resolve_client_cert, _unwrap_exception_group
 from tools.mcp_tool_lifecycle import _filter_mcp_children, _orphan_stdio_pid_servers, _orphan_stdio_pids, _stdio_pgids, _stdio_pids
 from tools.mcp_tool_common import _core
 from tools import mcp_tool_config as _config
@@ -131,7 +131,20 @@ class MCPServerTransportMixin:
                 if isinstance(exc, asyncio.TimeoutError) or not should_fallback(exc):
                     raise
                 logger.info(log_fmt, self.name, exc, *log_extra)
-                return await call(fallback)
+                try:
+                    return await call(fallback)
+                except Exception as fallback_exc:
+                    # #113359: the server ANSWERED ``initialize`` (200, valid result) but named a version the
+                    # SDK's handshake refuses (e.g. 2026-07-28 echoed to a 2025-11-25 offer), and it has no
+                    # ``server/discover`` either. The wire handshake succeeded, so complete it ourselves.
+                    if (isinstance(fallback_exc, asyncio.TimeoutError) or primary != "initialize"
+                            or not _handshake_answered_with_unsupported_version(exc)):
+                        raise
+                    logger.info("MCP server '%s': server/discover also failed (%s) — completing the handshake "
+                                "at %s, the version this client offered", self.name, fallback_exc,
+                                _core.LATEST_HANDSHAKE_VERSION)
+                    return await asyncio.wait_for(self._complete_handshake_at_offered_version(session),
+                                                  timeout=connect_timeout)
         mode = str((self._config or {}).get("protocol", "auto")).lower().strip()
         if mode in ("stateless", "modern", "2026-07-28"):
             return await attempt("discover", "initialize", lambda exc: True,
@@ -147,6 +160,28 @@ class MCPServerTransportMixin:
             "initialize", "discover", lambda exc: _handshake_rejected_as_modern(exc) and hasattr(session, "discover"),
             "MCP server '%s': legacy handshake rejected (%s) — retrying via server/discover (2026-07-28 stateless server)")
 
+    async def _complete_handshake_at_offered_version(self, session):
+        """Re-run the legacy ``initialize`` exchange the SDK already proved works against this server and
+        adopt its result pinned to the version WE offered (#113359). ``ClientSession.initialize()`` raises
+        on a ``protocolVersion`` outside its handshake set even though the server answered 200, and a
+        stateless server that echoes 2026-07-28 to every offer has no ``server/discover`` — so this is the
+        only way to reach ``notifications/initialized`` and ``tools/list``. Pinning to the offered version
+        keeps later requests legacy-shaped (envelope and MCP-Protocol-Version header), the form the
+        handshake itself just proved the server accepts. The returned result keeps the server's own
+        version for logging/diagnostics."""
+        import mcp.types as types  # late: keeps the SDK import lazy
+        offered = _core.LATEST_HANDSHAKE_VERSION
+        build_caps = getattr(session, "_build_capabilities", None)
+        capabilities = build_caps(offered) if callable(build_caps) else types.ClientCapabilities()
+        client_info = getattr(session, "_client_info", None) or types.Implementation(name="hermes-agent", version="0")
+        result = await session.send_request(
+            types.InitializeRequest(params=types.InitializeRequestParams(
+                protocolVersion=offered, capabilities=capabilities, clientInfo=client_info)),
+            types.InitializeResult)
+        session.adopt(result.model_copy(update={"protocol_version": offered}))
+        await session.send_notification(types.InitializedNotification())
+        return result
+
     async def _serve_session(self, session, connect_timeout: float,
                              label: str = "", mark_lifecycle: bool = False) -> str:
         """Handshake, discover, publish readiness, then serve until a lifecycle event. Clears stale

From 339ee5b9dc75b63abd594088eea6fb16eb72d221 Mon Sep 17 00:00:00 2001
From: KoNit-K <konit.block@protonmail.com>
Date: Thu, 17 Sep 2026 10:04:47 +0800
Subject: [PATCH 031/190] fix(cron): block taskkill gateway interpreter

(cherry picked from commit 72f033c5823af00176c3b730b8e8502ad9b2b772)
---
 cron/lifecycle_guard.py                       | 26 ++++++++++++++++---
 tests/hermes_cli/test_gateway_restart_loop.py | 20 ++++++++++++++
 2 files changed, 43 insertions(+), 3 deletions(-)

diff --git a/cron/lifecycle_guard.py b/cron/lifecycle_guard.py
index 168801e29e..b5a68288c7 100644
--- a/cron/lifecycle_guard.py
+++ b/cron/lifecycle_guard.py
@@ -60,6 +60,17 @@ _GATEWAY_LIFECYCLE_PATTERN = re.compile(
     r"|(?:\bp?kill\b[^\n]*\bgateway\b[^\n]*\bhermes)"
 )
 
+# Branch E: Windows image-name termination of the interpreter that runs the gateway.  A gateway
+# process normally has the image name ``python.exe``; unlike a PID-targeted taskkill, ``/IM
+# python.exe`` terminates it even when the agent does not know its PID.  Keep this tied to the
+# concrete taskkill command and its ``/IM`` option so other image names remain available to jobs.
+# The tokenized re-scan in ``contains_gateway_lifecycle_command`` applies this pattern after shell
+# quotes and escapes are resolved, just as it does for the other lifecycle branches (#113667).
+_TASKKILL_GATEWAY_INTERPRETER_PATTERN = re.compile(
+    r"(?i)(?<![/\w.\-])taskkill(?:\.exe)?\b"
+    r"(?=[^;\n|&]*(?:/im(?:\s+|:)\s*(?:['\"]?python\.exe['\"]?)(?=$|[\s,;|&\)])))"
+)
+
 # Every branch uses `[^\n]*` between verb and label so matches cannot span unrelated lines. A POSIX
 # backslash-newline continuation is therefore collapsed to a space before matching (as the shell
 # does) rather than loosening `[^\n]*`.
@@ -268,7 +279,10 @@ def contains_gateway_lifecycle_command(text: str) -> bool:
 
     text = strip_inert_heredoc_bodies(text)
     normalized = _SHELL_LINE_CONTINUATION.sub(" ", text)
-    if _GATEWAY_LIFECYCLE_PATTERN.search(normalized):
+    if (
+        _GATEWAY_LIFECYCLE_PATTERN.search(normalized)
+        or _TASKKILL_GATEWAY_INTERPRETER_PATTERN.search(normalized)
+    ):
         return True
     # Profile-flag form: blocked only when the named profile IS the one running the guard.
     # Profile-flag form (#78028): `hermes -p <profile> gateway restart|stop` bypasses Branch A because the
@@ -289,10 +303,16 @@ def contains_gateway_lifecycle_command(text: str) -> bool:
     # passes apply independently.
     for segment in _iter_command_segments(normalized):
         joined = " ".join(segment)
-        if joined and _GATEWAY_LIFECYCLE_PATTERN.search(joined):
+        if joined and (
+            _GATEWAY_LIFECYCLE_PATTERN.search(joined)
+            or _TASKKILL_GATEWAY_INTERPRETER_PATTERN.search(joined)
+        ):
             return True
         stripped = _ARGV_LIST_PUNCTUATION.sub(" ", joined)
-        if stripped != joined and _GATEWAY_LIFECYCLE_PATTERN.search(stripped):
+        if stripped != joined and (
+            _GATEWAY_LIFECYCLE_PATTERN.search(stripped)
+            or _TASKKILL_GATEWAY_INTERPRETER_PATTERN.search(stripped)
+        ):
             return True
     # The label may be built in an earlier `;`-segment, so no pass above sees verb + label together.
     # Order-independent launchctl pass (#77083): a shell loop can build the gateway label from a variable
diff --git a/tests/hermes_cli/test_gateway_restart_loop.py b/tests/hermes_cli/test_gateway_restart_loop.py
index ce185516de..7a727206c8 100644
--- a/tests/hermes_cli/test_gateway_restart_loop.py
+++ b/tests/hermes_cli/test_gateway_restart_loop.py
@@ -23,6 +23,26 @@ from hermes_cli.cron import cron_command
 class TestGatewayLifecyclePattern:
     """Verify the regex catches gateway lifecycle commands."""
 
+    @pytest.mark.parametrize("text", [
+        "taskkill /F /IM python.exe",
+        "taskkill /IM python.exe /F",
+        'taskkill /F /IM "python.exe"',
+        '"taskkill" /IM "python.exe" /F',
+        'task"kill" /I"M" "python.exe" /F',
+        "taskkill.exe /T /IM python.exe",
+        'subprocess.run(["taskkill", "/IM", "python.exe", "/F"])',
+    ])
+    def test_taskkill_gateway_interpreter_image_is_blocked(self, text):
+        """Image-name taskkill can terminate the gateway's Python process (#113667)."""
+        assert _contains_gateway_lifecycle_command(text), f"Should match: {text!r}"
+
+    @pytest.mark.parametrize("text", [
+        "taskkill /F /IM notepad.exe",
+        "taskkill /IM chrome.exe /F",
+    ])
+    def test_taskkill_other_image_names_are_allowed(self, text):
+        assert not _contains_gateway_lifecycle_command(text), f"Should NOT match: {text!r}"
+
     @pytest.mark.parametrize("text", [
         "hermes gateway restart",
         "hermes gateway stop",

From d966b34cc36f875de00c8cdb8f3eb55b3278d202 Mon Sep 17 00:00:00 2001
From: hotragn <hotragn.pettugani_2024@woxsen.edu.in>
Date: Mon, 24 Aug 2026 22:16:48 -0400
Subject: [PATCH 032/190] fix(security): gateway lifecycle guard recognises
 Windows command spellings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The guard that stops a supervised gateway from restarting, stopping or
uninstalling itself only knew POSIX spellings of those commands, so the
Windows spellings of the very same operations walked straight past it.

Branch A anchored on the bare CLI name, but on Windows the CLI is spelled
with an executable suffix, and npm-style shims install `hermes.cmd` and
`hermes.ps1` beside the `hermes.exe`. Every one of these was allowed
while the unsuffixed form was blocked:

    hermes.exe gateway restart      -> ALLOWED (now blocked)
    hermes.cmd gateway stop         -> ALLOWED (now blocked)
    hermes.bat gateway restart      -> ALLOWED (now blocked)
    hermes.ps1 gateway uninstall    -> ALLOWED (now blocked)
    C:\tools\hermes.exe gateway stop-> ALLOWED (now blocked)

Branch D had the same gap for process termination: `\bp?kill\b` cannot
reach inside `taskkill` (there is no word boundary between the two `k`s),
so `taskkill /F /IM hermes-gateway.exe` and `Stop-Process -Name
hermes-gateway` were allowed while `pkill -f hermes gateway` was blocked.

This is reachable. The guard is gated on `_is_supervised_gateway_process()`
— PID-file ownership — not on platform, and its callers (terminal_tool,
code_execution_tool, approval, cron) all run on Windows.

Service-control spellings (`net stop`, `sc stop`, `Stop-Service`) are
deliberately left out: they presuppose a service install this guard has
no evidence of, and guessing at one risks blocking unrelated services.
`C:/tools/hermes.exe` (forward slashes) also stays allowed — the `/` in
the Branch A lookbehind is the deliberate #77173 path false-positive
fix, and narrowing it is a separate decision.

19 new cases pin the caught spellings, the quoted/wrapped forms that
reach the same place through the tokenizing rescan, and that the suffix
does not widen the match — `hermes.exe gateway start` stays benign,
`my-hermes.exe` is still a different binary. 13 of the 19 fail without
this change.

(cherry picked from commit e81c42e4482cb72a93f6468d7571f98aa5fcb848)
---
 cron/lifecycle_guard.py                       | 11 +++--
 tests/hermes_cli/test_gateway_restart_loop.py | 48 +++++++++++++++++++
 2 files changed, 56 insertions(+), 3 deletions(-)

diff --git a/cron/lifecycle_guard.py b/cron/lifecycle_guard.py
index b5a68288c7..f85c46076e 100644
--- a/cron/lifecycle_guard.py
+++ b/cron/lifecycle_guard.py
@@ -34,7 +34,9 @@ _GATEWAY_LIFECYCLE_PATTERN = re.compile(
     # while every real command position (text start, whitespace, `;`/`&`/`|`, `$(`, backtick,
     # U+FFFD) still matches.
     # See #77173.
-    r"(?:(?<![/\w.\-])hermes\s+gateway\s+(?:restart|stop|uninstall)\b)"
+    # Windows spells the CLI with a launcher suffix (`hermes.exe`, npm-style `hermes.cmd`/`.ps1`);
+    # same command, so the suffix is optional here.
+    r"(?:(?<![/\w.\-])hermes(?:\.(?:exe|cmd|bat|com|ps1))?\s+gateway\s+(?:restart|stop|uninstall)\b)"
     # Branch B: launchctl ops anchored on a hermes-gateway label so unrelated hermes services stay
     # unblocked. `submit`/`bootstrap` register a NEW keepalive job wrapping an arbitrary helper (a
     # laundered restart); neutral-label submissions are caught by
@@ -56,8 +58,11 @@ _GATEWAY_LIFECYCLE_PATTERN = re.compile(
     r"|(?:systemctl\s+(?:-\S+\s+)*(?:restart|stop|start)\b[^\n]*\bhermes[.\-]?gateway)"
     # Branch D: pkill/kill of the gateway process, both token orders. Leading \b keeps "skill" from
     # matching as "kill".
-    r"|(?:\bp?kill\b[^\n]*\bhermes\b[^\n]*\bgateway)"
-    r"|(?:\bp?kill\b[^\n]*\bgateway\b[^\n]*\bhermes)"
+    # `taskkill` / `Stop-Process` are the Windows spellings of the same operation; `\bp?kill\b`
+    # cannot reach inside `taskkill`, so they are named outright. Service-control forms (`net stop`,
+    # `sc stop`) presuppose a service install this guard has no evidence of and stay uncovered.
+    r"|(?:\b(?:p?kill|taskkill|stop-process)\b[^\n]*\bhermes\b[^\n]*\bgateway)"
+    r"|(?:\b(?:p?kill|taskkill|stop-process)\b[^\n]*\bgateway\b[^\n]*\bhermes)"
 )
 
 # Branch E: Windows image-name termination of the interpreter that runs the gateway.  A gateway
diff --git a/tests/hermes_cli/test_gateway_restart_loop.py b/tests/hermes_cli/test_gateway_restart_loop.py
index 7a727206c8..4a15c8e89d 100644
--- a/tests/hermes_cli/test_gateway_restart_loop.py
+++ b/tests/hermes_cli/test_gateway_restart_loop.py
@@ -54,6 +54,54 @@ class TestGatewayLifecyclePattern:
     def test_hermes_gateway_commands(self, text):
         assert _contains_gateway_lifecycle_command(text), f"Should match: {text!r}"
 
+    @pytest.mark.parametrize("text", [
+        # Windows spells the CLI with an executable suffix, and npm-style
+        # shims install `hermes.cmd` / `hermes.ps1` beside the `.exe`.
+        # Anchoring Branch A on the bare name let every one of these walk past
+        # a guard that stops `hermes gateway restart`. The guard is gated on
+        # PID-file ownership, not on platform, so the bypass was live for any
+        # supervised gateway running on Windows.
+        "hermes.exe gateway restart",
+        "hermes.cmd gateway stop",
+        "hermes.bat gateway restart",
+        "hermes.ps1 gateway uninstall",
+        "HERMES.EXE gateway restart",
+        r"C:\tools\hermes.exe gateway stop",
+        r".\hermes.exe gateway restart",
+        # Quoted and wrapped spellings reach the same place via the
+        # tokenizing rescan; pin them so the suffix survives that path too.
+        r'"C:\Program Files\hermes.exe" gateway restart',
+        "cmd /c hermes.exe gateway restart",
+        'powershell -Command "hermes.exe gateway restart"',
+    ])
+    def test_windows_executable_suffix_is_caught(self, text):
+        assert _contains_gateway_lifecycle_command(text), f"Should match: {text!r}"
+
+    @pytest.mark.parametrize("text", [
+        # `taskkill` / `Stop-Process` are the Windows spellings of pkill.
+        # `\bp?kill\b` cannot reach inside `taskkill` — there is no word
+        # boundary between the two `k`s — so they need naming outright.
+        "taskkill /F /IM hermes-gateway.exe",
+        "Stop-Process -Name hermes-gateway -Force",
+        "stop-process -name hermes-gateway",
+    ])
+    def test_windows_process_kill_forms_are_caught(self, text):
+        assert _contains_gateway_lifecycle_command(text), f"Should match: {text!r}"
+
+    @pytest.mark.parametrize("text", [
+        # The suffix must not widen the match. `start` stays deliberately
+        # benign, an unrelated process is not the gateway, and the word-tail
+        # exclusion still holds once a suffix is attached.
+        "hermes.exe gateway start",
+        "hermes.exe chat",
+        "taskkill /F /IM notepad.exe",
+        "Stop-Process -Name chrome",
+        "my-hermes.exe gateway restart",
+        "hermesexe gateway restart",
+    ])
+    def test_windows_forms_do_not_overmatch(self, text):
+        assert not _contains_gateway_lifecycle_command(text), f"Should NOT match: {text!r}"
+
     @pytest.mark.parametrize("text", [
         # #62891: a blocked direct restart/kill laundered through a NEW
         # launchd keepalive job wrapping a helper script, instead of a

From 726bccd28d700a167a981e7e7f90f34e7c1b7206 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 00:57:43 -0700
Subject: [PATCH 033/190] fix(cron): lifecycle guard blocks kills aimed at the
 gateway's own interpreter image

An agent-issued `taskkill /F /IM python.exe` (or `pkill -9 python3`, `killall python`,
`Stop-Process -Name python`, `taskkill /FI "IMAGENAME eq python.exe"`, `pgrep python | xargs
kill`) from inside the supervised gateway killed the gateway: every branch of
_GATEWAY_LIFECYCLE_PATTERN was anchored on a hermes/gateway token, and the supervised gateway is
literally a `python` process. Branch E is token-aware (not a line regex) so option values are
never read as targets, `-f` cmdline patterns are judged as patterns (`pkill -f 'python
my_script.py'` passes, `pkill -f 'python -m hermes_cli.main'` does not), and other image names
(`taskkill /F /IM agent-browser.exe`) stay killable. Numeric-PID kills stay out of scope: the
explicit PID / `proc_*` id is the ownership-scoped route the terminal rejection now names.

The guard never ran on the Windows Scheduled-Task topology either: the launcher exports only the
generalized HERMES_SUPERVISED_CHILD marker, which gateway/restart.py never read.
is_supervised_gateway_launch() reads it and gates the self-kill guards;
is_gateway_supervisor_process() deliberately keeps ignoring it because it also selects the
exit-75 restart route, which the task has no restart policy to honour (#113670).

Supersedes the narrow `/IM python.exe` regex from #113671 (kept for authorship); the Windows
spellings from #94379 (`hermes.exe gateway restart`, `taskkill`/`Stop-Process` on hermes-gateway
tokens) ride along.

Fixes #113667
---
 cron/lifecycle_guard.py                       | 168 +++++++++++++++---
 gateway/restart.py                            |  24 ++-
 .../gateway/test_restart_service_detection.py |  15 ++
 tests/hermes_cli/test_gateway_restart_loop.py |  95 ++++------
 .../tools/test_launchctl_guard_diagnostic.py  |  29 +++
 tools/process_registry.py                     |   9 +-
 tools/terminal_tool_guards.py                 |  11 ++
 website/docs/user-guide/security.md           |  12 ++
 8 files changed, 276 insertions(+), 87 deletions(-)

diff --git a/cron/lifecycle_guard.py b/cron/lifecycle_guard.py
index f85c46076e..7565b02d0f 100644
--- a/cron/lifecycle_guard.py
+++ b/cron/lifecycle_guard.py
@@ -14,6 +14,7 @@ import os
 import re
 import shlex
 import stat
+import sys
 from pathlib import Path
 from typing import Callable, Iterator, Optional
 
@@ -65,16 +66,145 @@ _GATEWAY_LIFECYCLE_PATTERN = re.compile(
     r"|(?:\b(?:p?kill|taskkill|stop-process)\b[^\n]*\bgateway\b[^\n]*\bhermes)"
 )
 
-# Branch E: Windows image-name termination of the interpreter that runs the gateway.  A gateway
-# process normally has the image name ``python.exe``; unlike a PID-targeted taskkill, ``/IM
-# python.exe`` terminates it even when the agent does not know its PID.  Keep this tied to the
-# concrete taskkill command and its ``/IM`` option so other image names remain available to jobs.
-# The tokenized re-scan in ``contains_gateway_lifecycle_command`` applies this pattern after shell
-# quotes and escapes are resolved, just as it does for the other lifecycle branches (#113667).
-_TASKKILL_GATEWAY_INTERPRETER_PATTERN = re.compile(
-    r"(?i)(?<![/\w.\-])taskkill(?:\.exe)?\b"
-    r"(?=[^;\n|&]*(?:/im(?:\s+|:)\s*(?:['\"]?python\.exe['\"]?)(?=$|[\s,;|&\)])))"
-)
+# Branch E: process killers whose TARGET is the interpreter image hosting the gateway. A supervised
+# gateway is literally `python.exe` / `python3.12` (`python -m hermes_cli.main gateway run`), so
+# `taskkill /F /IM python.exe`, `pkill -9 python3` or `killall python` carry no hermes/gateway token
+# yet terminate it (#113667). Token-aware rather than a line regex: option VALUES are never read as
+# targets (`pkill -u <user> chrome`), `-f` cmdline patterns are judged as patterns, and other image
+# names (`taskkill /F /IM agent-browser.exe`) stay available. Numeric-PID kills are out of scope:
+# the explicit PID / `proc_*` id IS the ownership-scoped route the rejection points to.
+_INTERPRETER_IMAGE_RE = re.compile(r"^pythonw?(?:\d+(?:\.\d+)*)?(?:\.exe)?$")
+_HOST_INTERPRETER_NAME = Path(sys.executable).name.lower() if sys.executable else ""
+_KILLER_VALUE_OPTIONS = {
+    # procps pkill/pgrep options that consume the next token, so the value is never the pattern.
+    "pkill": frozenset({
+        "-g", "--pgroup", "-G", "--group", "-P", "--parent", "-s", "--session", "-t", "--terminal",
+        "-u", "--euid", "-U", "--uid", "-F", "--pidfile", "--ns", "--nslist", "-d", "--delimiter",
+        "--signal", "-O", "--older", "-r", "--runstates", "--cgroup", "-A", "--ignore-ancestors",
+    }),
+    "killall": frozenset({"-s", "--signal", "-u", "--user", "-o", "--older-than", "-y", "--younger-than",
+                          "-n", "--ns", "-Z", "--context"}),
+}
+_KILLER_VALUE_OPTIONS["pgrep"] = _KILLER_VALUE_OPTIONS["pkill"]
+_KILLER_VALUE_OPTIONS["pidof"] = frozenset({"-o", "--omit-pid", "-S", "--separator"})
+# Regex metacharacters a pkill/pgrep ERE may carry around the interpreter name (`^python3?$`, `python.*`).
+_ERE_TAIL = re.compile(r"[.*+?\\\[\](){}|].*$")
+_ERE_WILDCARD_ONLY = re.compile(r"^[.*+?$\s]*$")
+_NAME_KILLERS = frozenset({"pkill", "killall", "taskkill", "stop-process"})
+_NAME_ENUMERATORS = frozenset({"pgrep", "pidof", "get-process"})
+_KILL_VERB_RE = re.compile(r"(?i)\b(?:kill|taskkill|stop-process)\b")
+
+
+def _is_interpreter_image(value: str, *, substring: bool = False) -> bool:
+    """True when *value* (a process/image name, `*`-wildcard allowed) denotes the Python interpreter
+    that hosts the gateway. *substring*: pkill/pgrep match an ERE anywhere in the name, so `py`
+    reaches `python3` too."""
+    name = value.strip().strip("\"'").lower().removesuffix(".exe")
+    if not name:
+        return False
+    if name.endswith("*"):
+        prefix = name.rstrip("*")
+        return "python".startswith(prefix) or _HOST_INTERPRETER_NAME.startswith(prefix)
+    if _INTERPRETER_IMAGE_RE.match(name) or name == _HOST_INTERPRETER_NAME.removesuffix(".exe"):
+        return True
+    return substring and len(name) >= 2 and "python".startswith(name)
+
+
+def _pattern_reaches_host_interpreter(pattern: str, *, full_cmdline: bool, exact: bool) -> bool:
+    """pkill/pgrep/killall operand semantics: an ERE against the process NAME (or, with `-f`, the full
+    command line). `python -m hermes_cli.main …` is the gateway's own cmdline, so a `-f` pattern
+    that names the interpreter and then only wildcards or a `hermes` token reaches it, while
+    `python mt_add.py` (a specific script) does not."""
+    core = pattern.strip().strip("\"'").lstrip("^")
+    if core.endswith("$"):
+        core = core[:-1]
+    head, _, rest = core.partition(" ") if full_cmdline else (core, "", "")
+    # A literal interpreter name first (`python3.12`: the dot is a version separator, not an ERE
+    # wildcard); only then read the head as an ERE with a metacharacter tail (`python3?`, `python.*`).
+    match = None if _is_interpreter_image(head, substring=not exact) else _ERE_TAIL.search(head)
+    if match:
+        rest = head[match.start():] + " " + rest
+        head = head[: match.start()]
+    if not _is_interpreter_image(head, substring=not exact):
+        return full_cmdline and "hermes" in core.lower()
+    return not rest.strip() or bool(_ERE_WILDCARD_ONLY.match(rest)) or "hermes" in rest.lower()
+
+
+def _killer_targets_host_interpreter(name: str, args: list[str]) -> bool:
+    """Whether killer/enumerator *name* with argv *args* would select the host interpreter."""
+    if name in ("pkill", "pgrep", "killall", "pidof"):
+        # pkill/pgrep: ERE anywhere in the name unless -x; killall: exact name unless -r; pidof: exact.
+        exact = name == "pidof" or (name == "killall") != any(t in ("-r", "--regexp", "-x", "--exact") for t in args)
+        full_cmdline = name in ("pkill", "pgrep") and any(t in ("-f", "--full") for t in args)
+        operands: list[str] = []
+        position = 0
+        while position < len(args):
+            token = args[position]
+            if token == "--":
+                operands += args[position + 1:]
+                break
+            if token in _KILLER_VALUE_OPTIONS[name]:
+                position += 2
+                continue
+            if not token.startswith("-"):
+                operands.append(token)
+            position += 1
+        return any(_pattern_reaches_host_interpreter(op, full_cmdline=full_cmdline, exact=exact) for op in operands)
+    if name == "taskkill":
+        for position, token in enumerate(args[:-1]):
+            option = token.lower().lstrip("/-")
+            value = args[position + 1]
+            if option == "im" and _is_interpreter_image(value):
+                return True
+            if option == "fi":
+                filter_match = re.match(r"(?i)\s*['\"]?imagename\s+eq\s+(\S+)", value)
+                if filter_match and _is_interpreter_image(filter_match.group(1)):
+                    return True
+        return False
+    # Stop-Process / Get-Process: `-Name`/`-ProcessName` (also `-Name:value`), comma lists, positional
+    # names for Get-Process.
+    values: list[str] = []
+    for position, token in enumerate(args):
+        option, _, inline_value = token.partition(":")
+        if option.lower() in ("-name", "-processname", "-n"):
+            values.append(inline_value if inline_value else (args[position + 1] if position + 1 < len(args) else ""))
+        elif name == "get-process" and not token.startswith("-") and (position == 0 or not args[position - 1].startswith("-")):
+            values.append(token)
+    return any(_is_interpreter_image(part) for value in values for part in value.split(","))
+
+
+def _segment_names_host_interpreter(tokens: list[str], killers: frozenset[str]) -> bool:
+    """Whether a tokenized segment runs one of *killers* against the host interpreter. The
+    executable is read at the wrapper-peeled position first, then at the first killer token anywhere
+    in the segment (`xargs kill`, Python argv lists)."""
+    index = _executed_command_index(tokens)
+    candidates = [index] if index is not None else []
+    candidates += [i for i, token in enumerate(tokens) if _executable_name(token).lower().removesuffix(".exe") in killers]
+    for position in candidates:
+        name = _executable_name(tokens[position]).lower().removesuffix(".exe")
+        if name in killers and _killer_targets_host_interpreter(name, tokens[position + 1:]):
+            return True
+    return False
+
+
+def contains_host_interpreter_kill(text: str) -> bool:
+    """Branch E entrypoint: a process killer aimed at the interpreter image hosting the gateway, or a
+    name-derived PID feed into one (`pgrep python | xargs kill`, `kill $(pidof python3)`,
+    `Get-Process python | Stop-Process`). Segment-tokenized, so quoted/spliced spellings and Python
+    argv lists resolve the same way the shell resolves them."""
+    normalized = _SHELL_LINE_CONTINUATION.sub(" ", text)
+    kill_verb_present = bool(_KILL_VERB_RE.search(normalized))
+    for segment in _iter_command_segments(normalized):
+        joined = " ".join(segment)
+        stripped = _ARGV_LIST_PUNCTUATION.sub(" ", joined)
+        # Python argv lists (`subprocess.run(["taskkill", "/IM", "python.exe"])`) re-split only when
+        # list punctuation was present, so a quoted `-f 'python my_script.py'` stays one operand.
+        for tokens in ([segment, stripped.split()] if stripped != joined else [segment]):
+            if _segment_names_host_interpreter(tokens, _NAME_KILLERS):
+                return True
+            if kill_verb_present and _segment_names_host_interpreter(tokens, _NAME_ENUMERATORS):
+                return True
+    return False
 
 # Every branch uses `[^\n]*` between verb and label so matches cannot span unrelated lines. A POSIX
 # backslash-newline continuation is therefore collapsed to a space before matching (as the shell
@@ -284,10 +414,7 @@ def contains_gateway_lifecycle_command(text: str) -> bool:
 
     text = strip_inert_heredoc_bodies(text)
     normalized = _SHELL_LINE_CONTINUATION.sub(" ", text)
-    if (
-        _GATEWAY_LIFECYCLE_PATTERN.search(normalized)
-        or _TASKKILL_GATEWAY_INTERPRETER_PATTERN.search(normalized)
-    ):
+    if _GATEWAY_LIFECYCLE_PATTERN.search(normalized):
         return True
     # Profile-flag form: blocked only when the named profile IS the one running the guard.
     # Profile-flag form (#78028): `hermes -p <profile> gateway restart|stop` bypasses Branch A because the
@@ -308,23 +435,18 @@ def contains_gateway_lifecycle_command(text: str) -> bool:
     # passes apply independently.
     for segment in _iter_command_segments(normalized):
         joined = " ".join(segment)
-        if joined and (
-            _GATEWAY_LIFECYCLE_PATTERN.search(joined)
-            or _TASKKILL_GATEWAY_INTERPRETER_PATTERN.search(joined)
-        ):
+        if joined and _GATEWAY_LIFECYCLE_PATTERN.search(joined):
             return True
         stripped = _ARGV_LIST_PUNCTUATION.sub(" ", joined)
-        if stripped != joined and (
-            _GATEWAY_LIFECYCLE_PATTERN.search(stripped)
-            or _TASKKILL_GATEWAY_INTERPRETER_PATTERN.search(stripped)
-        ):
+        if stripped != joined and _GATEWAY_LIFECYCLE_PATTERN.search(stripped):
             return True
     # The label may be built in an earlier `;`-segment, so no pass above sees verb + label together.
     # Order-independent launchctl pass (#77083): a shell loop can build the gateway label from a variable
     # defined in an earlier `;`-separated segment (`label=${item%%:*}; launchctl bootout
     # "gui/$uid/$label"`), so neither the same-span regex nor same-segment tokenization sees verb and label
     # together. Check "verb anywhere AND label anywhere" instead.
-    return _contains_launchctl_gateway_lifecycle(normalized)
+    # Branch E (#113667): killers aimed at the interpreter image itself carry no hermes/gateway token.
+    return _contains_launchctl_gateway_lifecycle(normalized) or contains_host_interpreter_kill(normalized)
 
 
 # Whole-walk work limits. The per-file cap and depth bound above limit one read, not the walk: a
diff --git a/gateway/restart.py b/gateway/restart.py
index 2598feb28c..05dd27d83b 100644
--- a/gateway/restart.py
+++ b/gateway/restart.py
@@ -75,13 +75,35 @@ def is_global_startup_conflict(error_code: str | None) -> bool:
 
 
 def is_gateway_supervisor_process(environ: Mapping[str, str] | None = None) -> bool:
-    """Return whether this gateway process is owned by a supervisor."""
+    """Return whether this gateway process is owned by a supervisor that RESTARTS it.
+
+    Selects the exit-75 restart route, so only markers of a manager with a restart policy count:
+    systemd ``INVOCATION_ID``, launchd ``XPC_SERVICE_NAME``, the s6 sentinel, or the explicit
+    ``--external-supervisor`` opt-in. The generalized ``HERMES_SUPERVISED_CHILD`` launcher marker is
+    deliberately NOT read here: the Windows Scheduled-Task launcher sets it without a restart policy
+    (#113670), and routing its ``/restart`` through exit 75 would leave the gateway dead.
+    """
     env = os.environ if environ is None else environ
     xpc_service = env.get("XPC_SERVICE_NAME", "")
     return bool(env.get("INVOCATION_ID") or env.get("HERMES_S6_SUPERVISED_CHILD") or (xpc_service and xpc_service != "0")
                 or str(env.get(EXTERNAL_GATEWAY_SUPERVISOR_ENV, "")).strip().lower() in _TRUTHY)
 
 
+def is_supervised_gateway_launch(environ: Mapping[str, str] | None = None) -> bool:
+    """Return whether this gateway was launched by a generated service/launcher rather than a shell.
+
+    Superset of :func:`is_gateway_supervisor_process` that also honours ``HERMES_SUPERVISED_CHILD``,
+    the marker every generated launcher exports (systemd unit, launchd plist, s6 run script, Windows
+    Scheduled Task — see ``hermes_cli.main._apply_profile_override``). This is the identity the
+    self-targeting guards key on: a kill or lifecycle command issued from inside such a gateway takes
+    down the process hosting the caller with nobody at a terminal to bring it back (#113667).
+    """
+    env = os.environ if environ is None else environ
+    if env.get("HERMES_SUPERVISED_CHILD"):
+        return True
+    return is_gateway_supervisor_process() if environ is None else is_gateway_supervisor_process(environ)
+
+
 def is_container_restart_context() -> bool:
     """In a container (Docker/Podman) the detached setsid restart path dies with the cgroup,
     so exit-75 service restart is the only viable path.  Own function so tests can mock it."""
diff --git a/tests/gateway/test_restart_service_detection.py b/tests/gateway/test_restart_service_detection.py
index aeb1611cf5..80d84c355a 100644
--- a/tests/gateway/test_restart_service_detection.py
+++ b/tests/gateway/test_restart_service_detection.py
@@ -76,3 +76,18 @@ async def test_false_external_supervisor_marker_keeps_detached_path(
     await runner._handle_restart_command(_make_restart_event())
 
     runner.request_restart.assert_called_once_with(detached=True, via_service=False)
+
+
+def test_supervised_child_marker_is_a_launch_not_a_restart_route():
+    """The Windows Scheduled-Task launcher exports only ``HERMES_SUPERVISED_CHILD``: that must make
+    the gateway a supervised LAUNCH (self-kill guards active, #113667) without selecting the exit-75
+    restart route, which the task cannot honour (#113670)."""
+    from gateway.restart import is_gateway_supervisor_process, is_supervised_gateway_launch
+    from hermes_cli.gateway_windows import _GATEWAY_ENV
+
+    task_env = dict(_GATEWAY_ENV)
+    assert task_env["HERMES_SUPERVISED_CHILD"] == "1"
+    assert is_supervised_gateway_launch(task_env) is True
+    assert is_gateway_supervisor_process(task_env) is False
+    assert is_supervised_gateway_launch({}) is False
+    assert is_supervised_gateway_launch({"INVOCATION_ID": "abc"}) is True
diff --git a/tests/hermes_cli/test_gateway_restart_loop.py b/tests/hermes_cli/test_gateway_restart_loop.py
index 4a15c8e89d..54c625acb1 100644
--- a/tests/hermes_cli/test_gateway_restart_loop.py
+++ b/tests/hermes_cli/test_gateway_restart_loop.py
@@ -24,82 +24,57 @@ class TestGatewayLifecyclePattern:
     """Verify the regex catches gateway lifecycle commands."""
 
     @pytest.mark.parametrize("text", [
+        # Branch E (#113667): the supervised gateway IS the interpreter image, so a killer aimed at
+        # `python*` carries no hermes/gateway token yet takes it down — on every platform.
         "taskkill /F /IM python.exe",
-        "taskkill /IM python.exe /F",
-        'taskkill /F /IM "python.exe"',
-        '"taskkill" /IM "python.exe" /F',
+        "taskkill /F /IM python.exe 2>/dev/null | head -2; echo done",
+        'taskkill /F /FI "IMAGENAME eq python.exe"',
+        "taskkill.exe /T /IM pythonw.exe",
         'task"kill" /I"M" "python.exe" /F',
-        "taskkill.exe /T /IM python.exe",
         'subprocess.run(["taskkill", "/IM", "python.exe", "/F"])',
-    ])
-    def test_taskkill_gateway_interpreter_image_is_blocked(self, text):
-        """Image-name taskkill can terminate the gateway's Python process (#113667)."""
-        assert _contains_gateway_lifecycle_command(text), f"Should match: {text!r}"
-
-    @pytest.mark.parametrize("text", [
-        "taskkill /F /IM notepad.exe",
-        "taskkill /IM chrome.exe /F",
-    ])
-    def test_taskkill_other_image_names_are_allowed(self, text):
-        assert not _contains_gateway_lifecycle_command(text), f"Should NOT match: {text!r}"
-
-    @pytest.mark.parametrize("text", [
-        "hermes gateway restart",
-        "hermes gateway stop",
-        "hermes gateway uninstall",
-        "hermes  gateway  restart",         # double spaces
-        "Hermez Gateway Restart".lower().replace("z", "s"),  # case handled
-        "HERMES GATEWAY RESTART",           # uppercase
-    ])
-    def test_hermes_gateway_commands(self, text):
-        assert _contains_gateway_lifecycle_command(text), f"Should match: {text!r}"
-
-    @pytest.mark.parametrize("text", [
-        # Windows spells the CLI with an executable suffix, and npm-style
-        # shims install `hermes.cmd` / `hermes.ps1` beside the `.exe`.
-        # Anchoring Branch A on the bare name let every one of these walk past
-        # a guard that stops `hermes gateway restart`. The guard is gated on
-        # PID-file ownership, not on platform, so the bypass was live for any
-        # supervised gateway running on Windows.
+        "Stop-Process -Name python -Force",
+        "Stop-Process -ProcessName python3.12",
+        "Get-Process python | Stop-Process -Force",
+        "pkill python",
+        "pkill -9 python3",
+        "pkill -f python",
+        'pkill -f "python -m hermes_cli.main"',
+        "pkill -f hermes_cli",
+        "killall -9 python3.12",
+        "sudo pkill -9 python3",
+        "pgrep python | xargs kill -9",
+        "kill $(pidof python3)",
+        # Windows spellings of the hermes-gateway forms (salvaged from #94379).
         "hermes.exe gateway restart",
         "hermes.cmd gateway stop",
-        "hermes.bat gateway restart",
-        "hermes.ps1 gateway uninstall",
-        "HERMES.EXE gateway restart",
-        r"C:\tools\hermes.exe gateway stop",
-        r".\hermes.exe gateway restart",
-        # Quoted and wrapped spellings reach the same place via the
-        # tokenizing rescan; pin them so the suffix survives that path too.
         r'"C:\Program Files\hermes.exe" gateway restart',
-        "cmd /c hermes.exe gateway restart",
-        'powershell -Command "hermes.exe gateway restart"',
-    ])
-    def test_windows_executable_suffix_is_caught(self, text):
-        assert _contains_gateway_lifecycle_command(text), f"Should match: {text!r}"
-
-    @pytest.mark.parametrize("text", [
-        # `taskkill` / `Stop-Process` are the Windows spellings of pkill.
-        # `\bp?kill\b` cannot reach inside `taskkill` — there is no word
-        # boundary between the two `k`s — so they need naming outright.
         "taskkill /F /IM hermes-gateway.exe",
         "Stop-Process -Name hermes-gateway -Force",
-        "stop-process -name hermes-gateway",
     ])
-    def test_windows_process_kill_forms_are_caught(self, text):
+    def test_interpreter_and_windows_kill_forms_are_blocked(self, text):
         assert _contains_gateway_lifecycle_command(text), f"Should match: {text!r}"
 
     @pytest.mark.parametrize("text", [
-        # The suffix must not widen the match. `start` stays deliberately
-        # benign, an unrelated process is not the gateway, and the word-tail
-        # exclusion still holds once a suffix is attached.
-        "hermes.exe gateway start",
-        "hermes.exe chat",
+        # Other images stay killable (evals/browser_use/orchestrate.py uses the first one).
+        "taskkill /F /IM agent-browser.exe /T",
         "taskkill /F /IM notepad.exe",
         "Stop-Process -Name chrome",
+        "killall node",
+        # The ownership-scoped route the rejection points to: explicit PID / proc id.
+        "taskkill /F /PID 46544",
+        "kill -9 46544",
+        "Stop-Process -Id 46544",
+        # Option VALUES are not targets; a `-f` pattern naming a specific script is not the gateway.
+        "pkill -u alice chrome",
+        "pkill -t pts/1 vim",
+        "pkill -f 'python mt_add_paused.py --go'",
+        "pgrep python",
+        "hermes.exe gateway start",
         "my-hermes.exe gateway restart",
-        "hermesexe gateway restart",
+        "python -m pytest tests/ -k kill",
+        "skill python",
     ])
-    def test_windows_forms_do_not_overmatch(self, text):
+    def test_kill_forms_that_do_not_reach_the_gateway_are_allowed(self, text):
         assert not _contains_gateway_lifecycle_command(text), f"Should NOT match: {text!r}"
 
     @pytest.mark.parametrize("text", [
diff --git a/tests/tools/test_launchctl_guard_diagnostic.py b/tests/tools/test_launchctl_guard_diagnostic.py
index 9aeba7f1a2..fa4a6ee7f7 100644
--- a/tests/tools/test_launchctl_guard_diagnostic.py
+++ b/tests/tools/test_launchctl_guard_diagnostic.py
@@ -29,3 +29,32 @@ def test_bootstrap_rejection_does_not_invent_keepalive(tmp_path, monkeypatch):
     assert "does not inspect" in result["error"]
     assert "KeepAlive settings" in result["error"]
     assert "separate shell outside the gateway" in result["error"]
+
+
+def test_interpreter_kill_rejection_names_the_owned_process_route(tmp_path, monkeypatch):
+    """Scheduled-Task topology (#113667): only ``HERMES_SUPERVISED_CHILD`` marks the launch, and an
+    image-name kill of the interpreter is refused with the ``proc_*`` / explicit-PID route named.
+    Other images and explicit PIDs pass."""
+    import os
+
+    monkeypatch.setenv("_HERMES_GATEWAY", "1")
+    monkeypatch.setenv("HERMES_SUPERVISED_CHILD", "1")
+    for marker in ("INVOCATION_ID", "XPC_SERVICE_NAME", "HERMES_S6_SUPERVISED_CHILD", "HERMES_GATEWAY_EXTERNAL_SUPERVISOR"):
+        monkeypatch.delenv(marker, raising=False)
+    monkeypatch.setattr("gateway.status.get_running_pid", lambda *a, **k: os.getpid())
+
+    def run(command):
+        return gateway_lifecycle_block(
+            command=command, env=None, env_type="local", cwd=str(tmp_path), workdir=None,
+            session_key="diagnostic-test",
+        )
+
+    blocked = json.loads(run("taskkill /F /IM python.exe 2>/dev/null | head -2"))
+    assert blocked["exit_code"] == 1
+    assert "proc_" in blocked["error"] and "explicit PID" in blocked["error"]
+    assert "proc_" in json.loads(run("pkill -9 python3"))["error"]
+    assert run("taskkill /F /IM agent-browser.exe /T") is None
+    assert run("taskkill /F /PID 46544") is None
+    # Absence on the wrong side: a plain foreground `hermes gateway run` carries no launch marker.
+    monkeypatch.delenv("HERMES_SUPERVISED_CHILD")
+    assert run("pkill -9 python3") is None
diff --git a/tools/process_registry.py b/tools/process_registry.py
index 673880e09d..601f7308ae 100644
--- a/tools/process_registry.py
+++ b/tools/process_registry.py
@@ -263,14 +263,17 @@ def _is_supervised_gateway_process() -> bool:
     """Whether this process is the live, supervised Hermes gateway itself.
     Supervisor markers and ``_HERMES_GATEWAY`` are inherited by every descendant (and
     importing ``gateway.run`` sets the latter), so also require ownership of the live
-    gateway PID file — scopes are for the gateway, not terminal children or CLIs."""
+    gateway PID file — scopes are for the gateway, not terminal children or CLIs.
+    Reads the launch marker (``HERMES_SUPERVISED_CHILD`` included), not the restart-route
+    probe: a Windows Scheduled-Task gateway sets only that marker, and the self-kill guards
+    gated here must protect it too (#113667)."""
     if os.environ.get("_HERMES_GATEWAY") != "1":
         return False
     try:
-        from gateway.restart import is_gateway_supervisor_process
+        from gateway.restart import is_supervised_gateway_launch
         from gateway.status import get_running_pid
 
-        return is_gateway_supervisor_process() and get_running_pid(cleanup_stale=False) == os.getpid()
+        return is_supervised_gateway_launch() and get_running_pid(cleanup_stale=False) == os.getpid()
     except Exception as exc:
         logger.debug("Could not verify supervised gateway process identity: %s", exc)
         return False
diff --git a/tools/terminal_tool_guards.py b/tools/terminal_tool_guards.py
index d01861bb16..954a904427 100644
--- a/tools/terminal_tool_guards.py
+++ b/tools/terminal_tool_guards.py
@@ -204,6 +204,7 @@ def gateway_lifecycle_block(
         return None
     from cron.lifecycle_guard import (
         _MAX_REFERENCED_SCRIPT_BYTES,
+        contains_host_interpreter_kill,
         contains_launchctl_submit_command,
         lifecycle_scan_root_within_budget,
         scan_gateway_lifecycle,
@@ -244,6 +245,16 @@ def gateway_lifecycle_block(
             "error",
         )
     if unsafe:
+        # Name the ownership-scoped route for image-name kills: the intent is almost always "stop
+        # MY background job", and re-rolling the same over-broad spelling is what takes the gateway down.
+        if lifecycle_scan_root_within_budget(command) and contains_host_interpreter_kill(command):
+            return _blocked_json(
+                "Blocked: this command kills every process whose image/name matches the Python "
+                "interpreter, which is the process hosting this gateway (and this command). "
+                "Stop only the process you own instead: process(action=\"kill\", session_id=\"proc_…\") "
+                "for a background job Hermes started, or kill/taskkill by its explicit PID.",
+                "error",
+            )
         return _blocked_json(
             "Blocked: command or referenced script cannot restart, stop, or "
             "uninstall the gateway from inside the gateway process. The gateway would "
diff --git a/website/docs/user-guide/security.md b/website/docs/user-guide/security.md
index 766befd519..ba202919b7 100644
--- a/website/docs/user-guide/security.md
+++ b/website/docs/user-guide/security.md
@@ -100,6 +100,18 @@ restarting the gateway from inside its own supervised process. A self-restart ca
 terminate the tool before it finishes and cause a supervisor/auto-resume loop.
 User approval, YOLO mode, and `force=True` do not bypass this guard.
 
+The guard also refuses process killers aimed at the interpreter image the gateway
+runs as — `taskkill /F /IM python.exe`, `taskkill /FI "IMAGENAME eq python.exe"`,
+`Stop-Process -Name python`, `pkill -9 python3`, `killall python`, `pkill -f python`,
+and name-derived kills such as `pgrep python | xargs kill` — because a supervised
+gateway is literally a `python` process and such a command takes it (and the agent's
+own turn) down. Kills scoped to a process the agent owns pass: the `proc_*` id of a
+background job (`process(action="kill", …)`) or an explicit PID
+(`taskkill /F /PID <pid>`, `kill <pid>`). Other image names (`taskkill /F /IM notepad.exe`)
+are unaffected. The guard is active under every generated launcher — systemd unit,
+launchd plist, s6 run script and the Windows Scheduled Task — via the
+`HERMES_SUPERVISED_CHILD` marker they export.
+
 On macOS, executed `launchctl submit` and `launchctl bootstrap` commands are
 restricted **regardless of the job label**. This is a conservative registration
 restriction intended to catch indirect restart helpers with neutral labels, not

From 5d027bbd06b48cab77e983296381a0aa74238540 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 04:09:27 -0700
Subject: [PATCH 034/190] fix(cron): -f patterns must match the gateway
 cmdline, not any "hermes" substring; ledger names agent-issued kills

Review follow-up on #113667:

- _pattern_reaches_host_interpreter: when the `-f` head token is not an
  interpreter image, require the pattern to plausibly reach the gateway
  cmdline (hermes_cli / hermes+gateway tokens, mirroring Branch D). On
  the previous head `pkill -f 'hermes-polis/run.sh'` and
  `pkill -f my_hermes_bot.py` were hard-blocked although both are allowed
  on main and cannot match the gateway; both spellings are now negative
  controls in test_kill_forms_that_do_not_reach_the_gateway.
- lifecycle_ledger: the unclean-exit warning enumerated only OS causes
  (SIGKILL / OOM / VM death); an agent- or descendant-issued kill of the
  host interpreter leaves identical evidence and is now named in the
  cause family. One invariant test.
- test file: encoding="utf-8" on the bare write_text calls the footgun
  scanner flags.
---
 cron/lifecycle_guard.py                       | 15 ++++++++++++++-
 gateway/lifecycle_ledger.py                   |  3 ++-
 tests/gateway/test_lifecycle_ledger.py        | 10 ++++++++++
 tests/hermes_cli/test_gateway_restart_loop.py |  9 ++++++---
 4 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/cron/lifecycle_guard.py b/cron/lifecycle_guard.py
index 7565b02d0f..d687a4a4b4 100644
--- a/cron/lifecycle_guard.py
+++ b/cron/lifecycle_guard.py
@@ -93,6 +93,19 @@ _ERE_WILDCARD_ONLY = re.compile(r"^[.*+?$\s]*$")
 _NAME_KILLERS = frozenset({"pkill", "killall", "taskkill", "stop-process"})
 _NAME_ENUMERATORS = frozenset({"pgrep", "pidof", "get-process"})
 _KILL_VERB_RE = re.compile(r"(?i)\b(?:kill|taskkill|stop-process)\b")
+# A `-f` pattern that does not start with the interpreter reaches the gateway cmdline
+# (`python -m hermes_cli.main gateway run` / `hermes gateway run`) only through its own tokens;
+# an unrelated script that merely contains "hermes" (`hermes-polis/run.sh`, `my_hermes_bot.py`)
+# cannot match it. Same hermes+gateway pairing as Branch D, plus the module path.
+_GATEWAY_CMDLINE_TOKEN_RE = re.compile(r"(?i)hermes_cli|\bhermes\b[^\n]*\bgateway\b|\bgateway\b[^\n]*\bhermes\b")
+# Rejection text for Branch E, shared by every tool surface that runs the guard so the agent is
+# pointed at the ownership-scoped route (proc_* id / explicit PID) rather than the shell.
+HOST_INTERPRETER_KILL_REJECTION = (
+    "Blocked: this command kills every process whose image/name matches the Python "
+    "interpreter, which is the process hosting this gateway (and this command). "
+    "Stop only the process you own instead: process(action=\"kill\", session_id=\"proc_…\") "
+    "for a background job Hermes started, or kill/taskkill by its explicit PID."
+)
 
 
 def _is_interpreter_image(value: str, *, substring: bool = False) -> bool:
@@ -126,7 +139,7 @@ def _pattern_reaches_host_interpreter(pattern: str, *, full_cmdline: bool, exact
         rest = head[match.start():] + " " + rest
         head = head[: match.start()]
     if not _is_interpreter_image(head, substring=not exact):
-        return full_cmdline and "hermes" in core.lower()
+        return full_cmdline and bool(_GATEWAY_CMDLINE_TOKEN_RE.search(core))
     return not rest.strip() or bool(_ERE_WILDCARD_ONLY.match(rest)) or "hermes" in rest.lower()
 
 
diff --git a/gateway/lifecycle_ledger.py b/gateway/lifecycle_ledger.py
index d3e33c204c..e3f30a3030 100644
--- a/gateway/lifecycle_ledger.py
+++ b/gateway/lifecycle_ledger.py
@@ -213,7 +213,8 @@ def _report_unclean_exit(evidence: Dict[str, Any], home: Optional[Path]) -> None
     _append_exit_diag({"ts": _now_iso(), "tag": "gateway.previous_unclean_exit", "pid": os.getpid(), **evidence}, home)
     logger.warning(
         "Previous gateway life (pid=%s, started_at=%s) exited UNCLEANLY (no exit path ran — SIGKILL / OOM / "
-        "VM death). last_heartbeat_at=%s last_mem=%s suspected_oom=%s",
+        "VM death, or a process kill issued by the agent or one of its descendants, e.g. a pkill/taskkill of "
+        "the host interpreter image; see #113667). last_heartbeat_at=%s last_mem=%s suspected_oom=%s",
         evidence.get("prior_pid"), evidence.get("prior_started_at"), evidence.get("last_heartbeat_at"),
         evidence.get("last_heartbeat_mem"), evidence.get("suspected_oom", False),
     )
diff --git a/tests/gateway/test_lifecycle_ledger.py b/tests/gateway/test_lifecycle_ledger.py
index 54127a6928..cdb07b352b 100644
--- a/tests/gateway/test_lifecycle_ledger.py
+++ b/tests/gateway/test_lifecycle_ledger.py
@@ -143,6 +143,16 @@ def test_record_startup_persists_unclean_report_and_reclaims(tmp_path: Path) ->
     assert sentinel["pid"] == os.getpid()
 
 
+def test_unclean_report_names_agent_issued_kill_as_a_cause(tmp_path: Path, caplog) -> None:
+    """The cause family must not read as OS-only: an agent/descendant `pkill` of the host interpreter
+    leaves the identical evidence (no exit path ran) and is the operator's first thing to rule out (#113667)."""
+    _write_sentinel(tmp_path, {"phase": "running", "pid": _DEAD_PID, "start_time": 1000.0})
+    with caplog.at_level("WARNING", logger="gateway.lifecycle_ledger"):
+        assert record_startup(home=tmp_path) is not None
+    message = next(r.getMessage() for r in caplog.records if "exited UNCLEANLY" in r.getMessage())
+    assert "kill issued by the agent" in message and "OOM" in message
+
+
 def test_record_startup_carries_unclean_flags_onto_new_sentinel(
     tmp_path: Path,
 ) -> None:
diff --git a/tests/hermes_cli/test_gateway_restart_loop.py b/tests/hermes_cli/test_gateway_restart_loop.py
index 54c625acb1..ca2e000cf3 100644
--- a/tests/hermes_cli/test_gateway_restart_loop.py
+++ b/tests/hermes_cli/test_gateway_restart_loop.py
@@ -68,6 +68,9 @@ class TestGatewayLifecyclePattern:
         "pkill -u alice chrome",
         "pkill -t pts/1 vim",
         "pkill -f 'python mt_add_paused.py --go'",
+        # Unrelated scripts that merely contain "hermes" cannot match the gateway cmdline.
+        "pkill -f 'hermes-polis/run.sh'",
+        "pkill -f my_hermes_bot.py",
         "pgrep python",
         "hermes.exe gateway start",
         "my-hermes.exe gateway restart",
@@ -941,7 +944,7 @@ class TestLifecycleGuardModule:
             contains_gateway_lifecycle_command_or_referenced_script,
         )
         script = tmp_path / "restart.sh"
-        script.write_text("#!/bin/bash\nhermes gateway restart\n")
+        script.write_text("#!/bin/bash\nhermes gateway restart\n", encoding="utf-8")
         assert (
             contains_gateway_lifecycle_command_or_referenced_script(f". {script}")
             is True
@@ -971,7 +974,7 @@ class TestLifecycleGuardModule:
             contains_gateway_lifecycle_command_or_referenced_script,
         )
         script = tmp_path / "restart.sh"
-        script.write_text("#!/bin/bash\nhermes gateway restart\n")
+        script.write_text("#!/bin/bash\nhermes gateway restart\n", encoding="utf-8")
         assert (
             contains_gateway_lifecycle_command_or_referenced_script(f"source {script}")
             is True
@@ -984,7 +987,7 @@ class TestLifecycleGuardModule:
             contains_gateway_lifecycle_command_or_referenced_script,
         )
         script = tmp_path / "activate.sh"
-        script.write_text("#!/bin/bash\nexport PATH=/usr/bin:$PATH\n")
+        script.write_text("#!/bin/bash\nexport PATH=/usr/bin:$PATH\n", encoding="utf-8")
         assert (
             contains_gateway_lifecycle_command_or_referenced_script(f". {script}")
             is False

From 1f1fa9a87e1fce5e781cf425732df48f39ed64b5 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 04:09:27 -0700
Subject: [PATCH 035/190] fix(tools): execute_code shares the interpreter-kill
 rejection text; collapse redundant supervisor branch

- HOST_INTERPRETER_KILL_REJECTION is one constant in cron/lifecycle_guard;
  terminal_tool_guards and the execute_code lifecycle guard both use it,
  so an image-name kill inside a cell now names the proc_* / explicit-PID
  route instead of the generic "cannot restart or stop the gateway" text.
  One invariant test with the generic path as control.
- gateway/restart.is_supervised_gateway_launch: the callee already maps
  None to os.environ; pass environ straight through.
---
 gateway/restart.py                                   |  2 +-
 .../test_execute_code_lifecycle_guard_deadline.py    | 12 ++++++++++++
 tools/code_execution_tool.py                         |  8 +++++++-
 tools/terminal_tool_guards.py                        |  9 ++-------
 4 files changed, 22 insertions(+), 9 deletions(-)

diff --git a/gateway/restart.py b/gateway/restart.py
index 05dd27d83b..d6aef06653 100644
--- a/gateway/restart.py
+++ b/gateway/restart.py
@@ -101,7 +101,7 @@ def is_supervised_gateway_launch(environ: Mapping[str, str] | None = None) -> bo
     env = os.environ if environ is None else environ
     if env.get("HERMES_SUPERVISED_CHILD"):
         return True
-    return is_gateway_supervisor_process() if environ is None else is_gateway_supervisor_process(environ)
+    return is_gateway_supervisor_process(environ)
 
 
 def is_container_restart_context() -> bool:
diff --git a/tests/tools/test_execute_code_lifecycle_guard_deadline.py b/tests/tools/test_execute_code_lifecycle_guard_deadline.py
index 62b6f67687..085e38cacc 100644
--- a/tests/tools/test_execute_code_lifecycle_guard_deadline.py
+++ b/tests/tools/test_execute_code_lifecycle_guard_deadline.py
@@ -31,3 +31,15 @@ def test_wedged_lifecycle_probe_returns_bounded_error_without_running(monkeypatc
     assert elapsed < 0.5, f"lifecycle probe wedged execute_code for {elapsed:.2f}s"
     assert "did not finish" in result["error"]
     assert ran == [], "a probe with no verdict must not fail open into execution"
+
+
+def test_interpreter_kill_in_execute_code_names_the_owned_process_route(monkeypatch):
+    """Sibling surface of the terminal guard (#113667): an image-name kill inside a cell gets the same
+    proc_* / explicit-PID rejection, not the generic lifecycle text."""
+    import tools.process_registry as process_registry
+
+    monkeypatch.setattr(process_registry, "_is_supervised_gateway_process", lambda: True)
+    result = json.loads(cet.execute_code('import subprocess; subprocess.run(["pkill", "-9", "python3"])'))
+    assert "proc_" in result["error"] and "explicit PID" in result["error"]
+    generic = json.loads(cet.execute_code('import os; os.system("hermes gateway restart")'))
+    assert "proc_" not in generic["error"] and "cannot restart or stop the gateway" in generic["error"]
diff --git a/tools/code_execution_tool.py b/tools/code_execution_tool.py
index f3722349ae..894e7a2110 100644
--- a/tools/code_execution_tool.py
+++ b/tools/code_execution_tool.py
@@ -709,8 +709,14 @@ def execute_code(
             "(process-identity probe wedged); the code was not run. Retry the call."
         )
     if _probe.value:
-        from cron.lifecycle_guard import contains_gateway_lifecycle_command
+        from cron.lifecycle_guard import (
+            HOST_INTERPRETER_KILL_REJECTION,
+            contains_gateway_lifecycle_command,
+            contains_host_interpreter_kill,
+        )
         if contains_gateway_lifecycle_command(code):
+            if contains_host_interpreter_kill(code):
+                return tool_error(HOST_INTERPRETER_KILL_REJECTION)
             return tool_error(
                 "Blocked: cannot restart or stop the gateway from inside the "
                 "gateway process. The gateway would kill this script before "
diff --git a/tools/terminal_tool_guards.py b/tools/terminal_tool_guards.py
index 954a904427..de19c23a1c 100644
--- a/tools/terminal_tool_guards.py
+++ b/tools/terminal_tool_guards.py
@@ -204,6 +204,7 @@ def gateway_lifecycle_block(
         return None
     from cron.lifecycle_guard import (
         _MAX_REFERENCED_SCRIPT_BYTES,
+        HOST_INTERPRETER_KILL_REJECTION,
         contains_host_interpreter_kill,
         contains_launchctl_submit_command,
         lifecycle_scan_root_within_budget,
@@ -248,13 +249,7 @@ def gateway_lifecycle_block(
         # Name the ownership-scoped route for image-name kills: the intent is almost always "stop
         # MY background job", and re-rolling the same over-broad spelling is what takes the gateway down.
         if lifecycle_scan_root_within_budget(command) and contains_host_interpreter_kill(command):
-            return _blocked_json(
-                "Blocked: this command kills every process whose image/name matches the Python "
-                "interpreter, which is the process hosting this gateway (and this command). "
-                "Stop only the process you own instead: process(action=\"kill\", session_id=\"proc_…\") "
-                "for a background job Hermes started, or kill/taskkill by its explicit PID.",
-                "error",
-            )
+            return _blocked_json(HOST_INTERPRETER_KILL_REJECTION, "error")
         return _blocked_json(
             "Blocked: command or referenced script cannot restart, stop, or "
             "uninstall the gateway from inside the gateway process. The gateway would "

From 309b764a1595f4a42329158673aea7b950ad987e Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 08:06:57 -0700
Subject: [PATCH 036/190] fix(tests): systemd-scope tests patch
 is_gateway_supervisor_process with its real signature

is_supervised_gateway_launch now passes environ straight through, so a
zero-arg lambda at the seam raised TypeError, which
_is_supervised_gateway_process swallows into False and the five
TestSystemdCgroupIsolation wrapping tests saw a bare /bin/bash argv.
Production is unchanged (the callee maps None to os.environ); only the
test stubs needed the optional environ parameter, including the
lambda: False control so it keeps failing for the right reason.
---
 tests/tools/test_process_registry.py | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/tests/tools/test_process_registry.py b/tests/tools/test_process_registry.py
index 4b7f7c2c5a..0548586a49 100644
--- a/tests/tools/test_process_registry.py
+++ b/tests/tools/test_process_registry.py
@@ -2196,7 +2196,7 @@ class TestSystemdCgroupIsolation:
         )
         monkeypatch.setattr(
             "gateway.restart.is_gateway_supervisor_process",
-            lambda: True,
+            lambda environ=None: True,
         )
         # _build_systemd_scope_argv calls shutil.which — point it at a stub.
         monkeypatch.setattr("shutil.which", lambda name: "/usr/bin/systemd-run")
@@ -2264,7 +2264,7 @@ class TestSystemdCgroupIsolation:
         )
         monkeypatch.setattr(
             "gateway.restart.is_gateway_supervisor_process",
-            lambda: True,
+            lambda environ=None: True,
         )
 
         with (
@@ -2291,7 +2291,7 @@ class TestSystemdCgroupIsolation:
         )
         monkeypatch.setattr(
             "gateway.restart.is_gateway_supervisor_process",
-            lambda: False,
+            lambda environ=None: False,
         )
 
         with (
@@ -2417,7 +2417,7 @@ class TestSystemdCgroupIsolation:
         )
         monkeypatch.setattr(
             "gateway.restart.is_gateway_supervisor_process",
-            lambda: True,
+            lambda environ=None: True,
         )
         monkeypatch.setattr("shutil.which", lambda name: "/usr/bin/systemd-run")
 
@@ -2452,7 +2452,7 @@ class TestSystemdCgroupIsolation:
         )
         monkeypatch.setattr(
             "gateway.restart.is_gateway_supervisor_process",
-            lambda: True,
+            lambda environ=None: True,
         )
         monkeypatch.setattr("shutil.which", lambda name: "/usr/bin/systemd-run")
 
@@ -2502,7 +2502,7 @@ class TestSystemdCgroupIsolation:
         )
         monkeypatch.setattr(
             "gateway.restart.is_gateway_supervisor_process",
-            lambda: True,
+            lambda environ=None: True,
         )
         monkeypatch.setattr("shutil.which", lambda name: "/usr/bin/systemd-run")
 
@@ -2539,7 +2539,7 @@ class TestSystemdCgroupIsolation:
         )
         monkeypatch.setattr(
             "gateway.restart.is_gateway_supervisor_process",
-            lambda: True,
+            lambda environ=None: True,
         )
         monkeypatch.setattr("shutil.which", lambda name: "/usr/bin/systemd-run")
 
@@ -2898,7 +2898,7 @@ class TestSystemdCgroupIsolation:
         monkeypatch.setattr(pr, "_SYSTEMD_SCOPE_AVAILABLE", None)
         monkeypatch.setattr("tools.process_registry._find_shell", lambda: "/bin/bash")
         monkeypatch.setattr(
-            "gateway.restart.is_gateway_supervisor_process", lambda: True
+            "gateway.restart.is_gateway_supervisor_process", lambda environ=None: True
         )
         # If any branch consults the probe or builds a scope argv on darwin,
         # fail loudly.

From 39d46d944e6eef1ccb99a260a04bf0fe6d1d1a5f Mon Sep 17 00:00:00 2001
From: liuhao1024 <sunsky.lau@gmail.com>
Date: Sun, 7 Jun 2026 07:42:09 +0800
Subject: [PATCH 037/190] fix(config): clear stale model.base_url when
 model.provider changes via config set

When a user runs `hermes config set model.provider <new>` to switch
providers, the old provider's `model.base_url` is left behind in
config.yaml. This causes API calls to go to the wrong endpoint.

The wizard flow (`_update_config_for_provider`) already handles this
correctly by clearing stale base_url on provider switch, but the
`hermes config set` path did not.

Now `set_config_value` detects when `model.provider` is being changed
and removes the stale `model.base_url`, allowing runtime
auto-detection to resolve the correct endpoint for the new provider.

Fixes #40862
---
 hermes_cli/config.py                      | 13 +++++
 tests/hermes_cli/test_set_config_value.py | 65 +++++++++++++++++++++++
 2 files changed, 78 insertions(+)

diff --git a/hermes_cli/config.py b/hermes_cli/config.py
index 854d3cf140..b58ad75870 100644
--- a/hermes_cli/config.py
+++ b/hermes_cli/config.py
@@ -3705,6 +3705,19 @@ def set_config_value(key: str, value: str, force: bool = False):
         _set_nested(user_config, key, value)
     except ValueError as e:
         _exit_invalid(f"✗ {e}")
+
+    # When switching model.provider, clear stale model.base_url so the
+    # runtime auto-detection resolves the correct endpoint for the new
+    # provider.  Without this, ``hermes config set model.provider deepseek``
+    # after a wizard run that set base_url to xAI's endpoint leaves config
+    # in an inconsistent state (provider=deepseek, base_url=https://api.x.ai/v1).
+    # See: https://github.com/NousResearch/hermes-agent/issues/40862
+    if key == "model.provider":
+        model_section = user_config.get("model")
+        if isinstance(model_section, dict) and "base_url" in model_section:
+            removed_url = model_section.pop("base_url")
+            print(f"  Cleared stale model.base_url ({removed_url}) — "
+                  "the new provider's endpoint will be resolved automatically.")
     # api_base -> base_url alias at set-time too (mirrors _normalize_root_model_keys).
     if key.strip().lower() in ("model.api_base", "api_base"):
         # Normalize the api_base → base_url alias at set-time too (issue #8919), so a fresh `hermes config
diff --git a/tests/hermes_cli/test_set_config_value.py b/tests/hermes_cli/test_set_config_value.py
index be35e04ba3..eaa6862d23 100644
--- a/tests/hermes_cli/test_set_config_value.py
+++ b/tests/hermes_cli/test_set_config_value.py
@@ -1100,3 +1100,68 @@ class TestContainerTypeRefusal:
         import yaml as _yaml
         saved = _yaml.safe_load(_read_config(_isolated_hermes_home))
         assert saved["agent"]["disabled_toolsets"] == ["web"]
+
+
+class TestProviderSwitchClearsBaseUrl:
+    """When model.provider changes via config set, stale model.base_url
+    must be cleared so runtime auto-detection resolves the correct endpoint.
+    See: https://github.com/NousResearch/hermes-agent/issues/40862
+    """
+
+    def _write_config(self, tmp_path, body):
+        (tmp_path / "config.yaml").write_text(body)
+
+    def test_switching_provider_clears_base_url(self, _isolated_hermes_home, capsys):
+        """Switching from xai-oauth to deepseek should remove base_url."""
+        self._write_config(_isolated_hermes_home, (
+            "model:\n"
+            "  default: grok-4.3\n"
+            "  provider: xai-oauth\n"
+            "  base_url: https://api.x.ai/v1\n"
+        ))
+
+        set_config_value("model.provider", "deepseek")
+
+        import yaml
+        reloaded = yaml.safe_load(_read_config(_isolated_hermes_home))
+        assert reloaded["model"]["provider"] == "deepseek"
+        assert "base_url" not in reloaded["model"]
+        # User gets a message about the cleared URL
+        captured = capsys.readouterr()
+        assert "Cleared stale model.base_url" in captured.out
+        assert "api.x.ai" in captured.out
+
+    def test_switching_provider_no_base_url_is_noop(self, _isolated_hermes_home, capsys):
+        """If there's no base_url to clear, the switch still works silently."""
+        self._write_config(_isolated_hermes_home, (
+            "model:\n"
+            "  default: gpt-4o\n"
+            "  provider: openai\n"
+        ))
+
+        set_config_value("model.provider", "anthropic")
+
+        import yaml
+        reloaded = yaml.safe_load(_read_config(_isolated_hermes_home))
+        assert reloaded["model"]["provider"] == "anthropic"
+        assert "base_url" not in reloaded["model"]
+        captured = capsys.readouterr()
+        assert "Cleared stale" not in captured.out
+
+    def test_non_provider_key_preserves_base_url(self, _isolated_hermes_home):
+        """Changing model.default should NOT touch base_url."""
+        self._write_config(_isolated_hermes_home, (
+            "model:\n"
+            "  default: grok-4.3\n"
+            "  provider: xai-oauth\n"
+            "  base_url: https://api.x.ai/v1\n"
+        ))
+
+        set_config_value("model.default", "deepseek-v4-pro")
+
+        import yaml
+        reloaded = yaml.safe_load(_read_config(_isolated_hermes_home))
+        assert reloaded["model"]["default"] == "deepseek-v4-pro"
+        # base_url must be preserved — only model.default changed
+        assert reloaded["model"]["base_url"] == "https://api.x.ai/v1"
+        assert reloaded["model"]["provider"] == "xai-oauth"

From 250e12e760e75d8205971c4c9ec7e110a92b65b7 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 00:53:19 -0700
Subject: [PATCH 038/190] fix(config): provider switch via config set drops the
 previous provider's route (#113719)

`hermes config set model.provider X` re-points the `model:` block at a new
provider but left `model.base_url` / `model.api_mode` from the previous
route in place. The runtime honours a persisted api_mode/base_url for
whatever provider the block names, so X's key was posted to the old
endpoint (e.g. https://chatgpt.com/backend-api/codex + codex_responses)
and every request 401'd with `api_key_not_supported` blaming X.

Reshapes the salvaged clearing from #40869 (which popped base_url on every
provider write) into route-aware syncing, mirroring what a persisted
`/model` switch writes (`model_selection_config_updates`):

- `hermes_cli/route_identity.py::provider_owns_route` decides whose endpoint
  a base_url is: the target's registry/plugin host, a `providers:` /
  `custom_providers:` entry resolving to the target, or bare custom/local
  aliases (configured BY base_url) -> owned; another known provider's host
  or a named entry with a different endpoint -> foreign; unknown host -> None.
- `drop_stale_model_route` pops base_url + api_mode when foreign (api_mode
  alone, with no base_url, is old-route wire state and goes too); keeps an
  owned route with its api_mode; keeps an unknown host.
- `set_config_value` runs it only when model.provider actually changes,
  prints what was cleared and why, or warns that an unrecognised base_url
  still applies (the warn-only shape of #113725).
- Same provider re-set, `model.default`, a target that owns the URL
  (openai-codex + chatgpt.com), a custom entry with that URL, and bare
  `custom` are untouched.

Tests trimmed to two invariants (clear matrix / keep matrix) in
tests/hermes_cli/test_set_config_value.py; docs in cli-commands.md.

Co-authored-by: Yagna Vudathu <yagnavudathu@gmail.com>
Co-authored-by: Tim Richardson <tim@growthpath.com.au>
---
 contributors/emails/tim@growthpath.com.au  |  2 +
 contributors/emails/yagnavudathu@gmail.com |  1 +
 hermes_cli/config.py                       | 36 +++++---
 hermes_cli/route_identity.py               | 61 +++++++++++++-
 tests/hermes_cli/test_set_config_value.py  | 98 +++++++++-------------
 website/docs/reference/cli-commands.md     |  7 ++
 6 files changed, 133 insertions(+), 72 deletions(-)
 create mode 100644 contributors/emails/tim@growthpath.com.au

diff --git a/contributors/emails/tim@growthpath.com.au b/contributors/emails/tim@growthpath.com.au
new file mode 100644
index 0000000000..b35f2866e2
--- /dev/null
+++ b/contributors/emails/tim@growthpath.com.au
@@ -0,0 +1,2 @@
+timrichardson
+# PR #47533 co-author
diff --git a/contributors/emails/yagnavudathu@gmail.com b/contributors/emails/yagnavudathu@gmail.com
index 15ead58f93..b335e442ad 100644
--- a/contributors/emails/yagnavudathu@gmail.com
+++ b/contributors/emails/yagnavudathu@gmail.com
@@ -1 +1,2 @@
 whyyagswhy
+# PR #113725 co-author
diff --git a/hermes_cli/config.py b/hermes_cli/config.py
index b58ad75870..ed8808dbcc 100644
--- a/hermes_cli/config.py
+++ b/hermes_cli/config.py
@@ -3701,23 +3701,31 @@ def set_config_value(key: str, value: str, force: bool = False):
         user_config["model"] = {"default": _model_val}
     key = _guard_section_overwrite(key, value, user_config, force)
     value = _refuse_container_type_mismatch(key, value, user_config, force)
+    _old_provider = _model_val.get("provider") if isinstance(_model_val, dict) else None
     try:
         _set_nested(user_config, key, value)
     except ValueError as e:
         _exit_invalid(f"✗ {e}")
-
-    # When switching model.provider, clear stale model.base_url so the
-    # runtime auto-detection resolves the correct endpoint for the new
-    # provider.  Without this, ``hermes config set model.provider deepseek``
-    # after a wizard run that set base_url to xAI's endpoint leaves config
-    # in an inconsistent state (provider=deepseek, base_url=https://api.x.ai/v1).
-    # See: https://github.com/NousResearch/hermes-agent/issues/40862
-    if key == "model.provider":
-        model_section = user_config.get("model")
-        if isinstance(model_section, dict) and "base_url" in model_section:
-            removed_url = model_section.pop("base_url")
-            print(f"  Cleared stale model.base_url ({removed_url}) — "
-                  "the new provider's endpoint will be resolved automatically.")
+    # A provider switch re-points ``model:`` at a new route; ``base_url``/``api_mode`` are route
+    # state of the OLD provider, and the runtime honours them for whatever provider the block now
+    # names — the new provider's key would be posted to the old endpoint (#113719, #40862). Sync
+    # them the way a persisted ``/model`` switch does: the previous route goes unless it is the
+    # new provider's own endpoint.
+    _route_notice = ""
+    _old_provider = str(_old_provider or "").strip() or "the previous provider"
+    if key == "model.provider" and _old_provider.lower() != str(value).strip().lower():
+        from hermes_cli.route_identity import drop_stale_model_route
+        _popped, _unverified = drop_stale_model_route(user_config.get("model"), value, user_config)
+        if _popped:
+            _route_notice = (
+                "  Cleared " + ", ".join(f"model.{k} ({v})" for k, v in _popped.items())
+                + f" — that route belonged to {_old_provider}, not {value}. {value}'s endpoint resolves "
+                "automatically; set model.base_url again if you meant a custom endpoint.")
+        elif _unverified:
+            _route_notice = color(
+                f"⚠ model.base_url ({user_config['model'].get('base_url')}) was set under {_old_provider} and "
+                f"still applies to {value} — requests go there. If it is not {value}'s endpoint: "
+                "`hermes config unset model.base_url` (and model.api_mode).", Colors.YELLOW)
     # api_base -> base_url alias at set-time too (mirrors _normalize_root_model_keys).
     if key.strip().lower() in ("model.api_base", "api_base"):
         # Normalize the api_base → base_url alias at set-time too (issue #8919), so a fresh `hermes config
@@ -3742,6 +3750,8 @@ def set_config_value(key: str, value: str, force: bool = False):
         from agent.redact import mask_secret
         _display_value = mask_secret(value)
     print(f"✓ Set {key} = {_display_value} in {config_path}")
+    if _route_notice:
+        print(_route_notice)
     warn_unpinned_cron_jobs_after_model_config_change(key, value, user_config)
 
     # Post-write unknown-key notice (#34067): value IS saved, but tell the user the runtime may never read
diff --git a/hermes_cli/route_identity.py b/hermes_cli/route_identity.py
index 6ada71c1d0..56d3a2e7b3 100644
--- a/hermes_cli/route_identity.py
+++ b/hermes_cli/route_identity.py
@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, Optional
 from urllib.parse import urlsplit, urlunsplit
 
 
@@ -44,6 +44,65 @@ def normalize_route_base_url(base_url: Any) -> str:
     return normalized
 
 
+def provider_owns_route(provider: Any, base_url: Any, config: Any = None) -> Optional[bool]:
+    """Whether ``model.base_url`` is *provider*'s own endpoint.
+
+    ``True``: the host is the provider's registry/plugin endpoint or the endpoint of a
+    ``providers:``/``custom_providers:`` entry that resolves to *provider*, or *provider* is bare
+    ``custom``/``local`` (the URL *is* the route). ``False``: the host is another known provider's
+    stock endpoint, or *provider* names a user entry with a different endpoint. ``None``: unknown
+    host (a proxy, a LAN server) — nothing here can say whose it is. Offline: the registry lookup
+    never fetches the models.dev catalog.
+    """
+    from hermes_cli.providers import get_provider, normalize_provider, resolve_custom_provider, resolve_user_provider
+    from utils import base_url_hostname
+
+    host = base_url_hostname(str(base_url or ""))
+    if not host:
+        return None
+    raw = str(provider or "").strip().lower()
+    canonical = normalize_provider(raw)
+    if canonical in ("custom", "local"):
+        # Bare custom / local-server aliases are configured BY model.base_url (#14676, #27132);
+        # resolve_custom_provider would also self-heal bare "custom" to the first entry (#17478).
+        return True
+    cfg = config if isinstance(config, dict) else {}
+    user_pdef = resolve_user_provider(raw, cfg.get("providers") or {}) or resolve_custom_provider(
+        raw, cfg.get("custom_providers"))
+    if user_pdef is not None and user_pdef.base_url:
+        return base_url_hostname(user_pdef.base_url) == host
+    pdef = get_provider(canonical, allow_network=False)
+    if pdef is not None and pdef.base_url and base_url_hostname(pdef.base_url) == host:
+        return True
+    if pdef is None and user_pdef is None:
+        return True
+    from agent.model_metadata import _infer_provider_from_url
+    inferred = _infer_provider_from_url(str(base_url))
+    if inferred is None:
+        return None
+    return normalize_provider(inferred) == canonical
+
+
+def drop_stale_model_route(model_cfg: Any, provider: Any, config: Any = None) -> "tuple[dict[str, Any], bool]":
+    """Pop the route keys (``base_url``, ``api_mode``) a previous provider left in ``model:``
+    when the block is re-pointed at *provider* without a fresh route (``hermes config set
+    model.provider``). Mirrors what a persisted ``/model`` switch writes: the route is synced to
+    the target, never carried over. Returns ``(popped {key: old value}, unverified)`` where
+    ``unverified`` is True when a base_url of unknown ownership was kept — the caller should say so.
+    A base_url that belongs to *provider* is kept together with its api_mode; with no base_url the
+    api_mode alone is wire state of the old route and goes."""
+    if not isinstance(model_cfg, dict):
+        return {}, False
+    base_url = str(model_cfg.get("base_url") or "").strip()
+    owned = provider_owns_route(provider, base_url, config) if base_url else False
+    if owned:
+        return {}, False
+    if owned is None:
+        return {}, True
+    popped = {k: model_cfg.pop(k) for k in ("base_url", "api_mode") if model_cfg.get(k) not in (None, "")}
+    return popped, False
+
+
 def should_clear_context_pin(configured_model: Any, active_model: Any, configured_base_url: Any, active_base_url: Any,
                              configured_provider: Any, active_provider: Any) -> bool:
     """True when a configured ``model.context_length`` pin no longer matches its runtime route.
diff --git a/tests/hermes_cli/test_set_config_value.py b/tests/hermes_cli/test_set_config_value.py
index eaa6862d23..84a7e8f244 100644
--- a/tests/hermes_cli/test_set_config_value.py
+++ b/tests/hermes_cli/test_set_config_value.py
@@ -1103,65 +1103,47 @@ class TestContainerTypeRefusal:
 
 
 class TestProviderSwitchClearsBaseUrl:
-    """When model.provider changes via config set, stale model.base_url
-    must be cleared so runtime auto-detection resolves the correct endpoint.
-    See: https://github.com/NousResearch/hermes-agent/issues/40862
-    """
+    """``config set model.provider X`` must not carry the previous provider's route (#113719,
+    #40862): a ``base_url``/``api_mode`` that is not X's own endpoint goes, with a notice, so X's
+    key is never posted to the old endpoint. A route that IS X's stays."""
 
-    def _write_config(self, tmp_path, body):
-        (tmp_path / "config.yaml").write_text(body)
+    ROUTE = {"base_url": "https://chatgpt.com/backend-api/codex", "api_mode": "codex_responses"}
 
-    def test_switching_provider_clears_base_url(self, _isolated_hermes_home, capsys):
-        """Switching from xai-oauth to deepseek should remove base_url."""
-        self._write_config(_isolated_hermes_home, (
-            "model:\n"
-            "  default: grok-4.3\n"
-            "  provider: xai-oauth\n"
-            "  base_url: https://api.x.ai/v1\n"
-        ))
+    def _seed(self, tmp_path, model):
+        (tmp_path / "config.yaml").write_text(yaml.safe_dump({
+            "model": model,
+            "custom_providers": [{"name": "mylab", "base_url": "http://10.0.0.5:8000/v1", "api_key": "k"}]}))
 
-        set_config_value("model.provider", "deepseek")
+    @pytest.mark.parametrize("target, seed_route", [
+        ("anthropic", ROUTE),                    # the reporter's switch: both route keys are stale
+        ("mylab", ROUTE),                        # named custom entry has its own endpoint
+        ("anthropic", {"api_mode": "codex_responses"}),  # wire mode alone is old-route state
+    ])
+    def test_switching_provider_clears_foreign_route(self, _isolated_hermes_home, capsys, target, seed_route):
+        self._seed(_isolated_hermes_home, {"provider": "opencode-go", "default": "gpt-5.3-codex", **seed_route})
+        set_config_value("model.provider", target)
+        model = yaml.safe_load(_read_config(_isolated_hermes_home))["model"]
+        assert model == {"provider": target, "default": "gpt-5.3-codex"}
+        out = capsys.readouterr().out
+        assert "Cleared" in out and "opencode-go" in out
+        for key, value in seed_route.items():
+            assert f"model.{key} ({value})" in out
 
-        import yaml
-        reloaded = yaml.safe_load(_read_config(_isolated_hermes_home))
-        assert reloaded["model"]["provider"] == "deepseek"
-        assert "base_url" not in reloaded["model"]
-        # User gets a message about the cleared URL
-        captured = capsys.readouterr()
-        assert "Cleared stale model.base_url" in captured.out
-        assert "api.x.ai" in captured.out
-
-    def test_switching_provider_no_base_url_is_noop(self, _isolated_hermes_home, capsys):
-        """If there's no base_url to clear, the switch still works silently."""
-        self._write_config(_isolated_hermes_home, (
-            "model:\n"
-            "  default: gpt-4o\n"
-            "  provider: openai\n"
-        ))
-
-        set_config_value("model.provider", "anthropic")
-
-        import yaml
-        reloaded = yaml.safe_load(_read_config(_isolated_hermes_home))
-        assert reloaded["model"]["provider"] == "anthropic"
-        assert "base_url" not in reloaded["model"]
-        captured = capsys.readouterr()
-        assert "Cleared stale" not in captured.out
-
-    def test_non_provider_key_preserves_base_url(self, _isolated_hermes_home):
-        """Changing model.default should NOT touch base_url."""
-        self._write_config(_isolated_hermes_home, (
-            "model:\n"
-            "  default: grok-4.3\n"
-            "  provider: xai-oauth\n"
-            "  base_url: https://api.x.ai/v1\n"
-        ))
-
-        set_config_value("model.default", "deepseek-v4-pro")
-
-        import yaml
-        reloaded = yaml.safe_load(_read_config(_isolated_hermes_home))
-        assert reloaded["model"]["default"] == "deepseek-v4-pro"
-        # base_url must be preserved — only model.default changed
-        assert reloaded["model"]["base_url"] == "https://api.x.ai/v1"
-        assert reloaded["model"]["provider"] == "xai-oauth"
+    @pytest.mark.parametrize("key, target, seed", [
+        ("model.default", "gpt-5", {"provider": "opencode-go", **ROUTE}),          # not a provider switch
+        ("model.provider", "opencode-go", {"provider": "opencode-go", **ROUTE}),   # same provider: no-op
+        ("model.provider", "openai-codex", {"provider": "opencode-go", **ROUTE}),  # route IS the target's
+        ("model.provider", "mylab", {"provider": "openai", "base_url": "http://10.0.0.5:8000/v1"}),
+        ("model.provider", "custom", {"provider": "openai", "base_url": "https://api.openai.com/v1"}),
+        ("model.provider", "anthropic", {"provider": "opencode-go", "base_url": "http://proxy.internal:8080/v1"}),
+    ])
+    def test_route_that_belongs_to_target_is_kept(self, _isolated_hermes_home, capsys, key, target, seed):
+        self._seed(_isolated_hermes_home, {**seed, "default": "m"})
+        set_config_value(key, target)
+        model = yaml.safe_load(_read_config(_isolated_hermes_home))["model"]
+        expected = {**seed, "default": "m", key.split(".", 1)[1]: target}
+        assert model == expected
+        out = capsys.readouterr().out
+        assert "Cleared" not in out
+        # Unknown host: kept, but the user is told the old route still applies (from #113725).
+        assert ("still applies" in out) == ("proxy.internal" in seed["base_url"])
diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.md
index 45f19283fd..5cd0246734 100644
--- a/website/docs/reference/cli-commands.md
+++ b/website/docs/reference/cli-commands.md
@@ -1266,6 +1266,13 @@ Subcommands:
 | `check` | Check for missing or stale config. |
 | `migrate` | Add newly introduced options interactively. |
 
+`config set model.provider <provider>` keeps the `model:` block on one route: a `model.base_url` /
+`model.api_mode` left over from the previous provider is removed (and listed) when it is another
+provider's endpoint — otherwise the new provider's key would be posted to the old endpoint and fail
+with a credential error naming the wrong provider. A URL that is the new provider's own endpoint, a
+named `custom_providers` entry's endpoint, or any URL under `custom`/local aliases stays; an
+unrecognised host (a proxy, a LAN server) stays with a warning that it still applies.
+
 ### Dots inside key names
 
 `hermes config set/get/unset` use `.` as the nesting separator, but many real

From 7530f40383583db3ee08c80d8101885f19fcf519 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 03:53:47 -0700
Subject: [PATCH 039/190] fix(errors): auth refusals from a non-stock route
 name the contacted host

The #113719 report asked that, when the request does fail, the error
names the endpoint that was actually contacted. classify_api_error now
appends "(endpoint: <host>)" to auth-class messages when base_url is set
and is not the provider's own route (provider_owns_route is not True),
so a credential posted to a stale model.base_url reads as a wrong
endpoint rather than a bad key. Stock routes and empty base_url keep
the plain message.
---
 agent/error_classifier.py            | 20 +++++++++++++++++++-
 tests/agent/test_error_classifier.py | 18 ++++++++++++++++++
 2 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/agent/error_classifier.py b/agent/error_classifier.py
index 771631a479..29bb23bee0 100644
--- a/agent/error_classifier.py
+++ b/agent/error_classifier.py
@@ -807,10 +807,28 @@ def classify_api_error(
         anonymous=is_anonymous_request(provider, api_key),
     )
     verdict = next((v for v in (stage(c) for stage in _STAGES) if v is not None), _V_UNKNOWN)
-    base = {"status_code": status_code, "provider": provider, "model": model, "message": _extract_message(error, body)}
+    message = _extract_message(error, body)
+    if verdict["reason"] in (_R.auth, _R.auth_permanent):
+        # An auth refusal from a non-stock route names the host, so a credential posted to the
+        # wrong endpoint (a stale ``model.base_url`` after a provider switch, #113719) reads as
+        # such — not as a bad key.
+        host = _off_route_host(c)
+        if host:
+            message = f"{message} (endpoint: {host})"
+    base = {"status_code": status_code, "provider": provider, "model": model, "message": message}
     return ClassifiedError(**{**base, **verdict})
 
 
+def _off_route_host(c: _Ctx) -> str:
+    """The contacted host when ``base_url`` is set and is not the provider's own endpoint; ``""`` otherwise."""
+    from hermes_cli.route_identity import provider_owns_route
+    from utils import base_url_hostname
+    host = base_url_hostname(c.base_url)
+    if not host or provider_owns_route(c.provider_slug, c.base_url) is True:
+        return ""
+    return host
+
+
 # ── Status code handlers ────────────────────────────────────────────────
 
 def _status_403(c: _Ctx) -> Verdict:
diff --git a/tests/agent/test_error_classifier.py b/tests/agent/test_error_classifier.py
index 963fab64c0..c71cc07f3b 100644
--- a/tests/agent/test_error_classifier.py
+++ b/tests/agent/test_error_classifier.py
@@ -1879,3 +1879,21 @@ class TestNousWelcomeTier:
         result = classify_api_error(MockAPIError("forbidden", status_code=403, body={"message": "forbidden"}), provider="nous", api_key=make_jwt())
         assert result.reason == FailoverReason.auth
         assert "welcome_route" not in result.error_context
+
+
+class TestAuthErrorNamesOffRouteEndpoint:
+    """#113719: an auth refusal from a route that is not the provider's own endpoint names the host."""
+
+    _BODY = {"error": {"code": "api_key_not_supported", "message": "API keys are not supported by this endpoint."}}
+
+    def test_stale_base_url_names_contacted_host(self):
+        e = MockAPIError("Unauthorized", status_code=401, body=self._BODY)
+        result = classify_api_error(e, provider="anthropic", model="claude", base_url="https://chatgpt.com/backend-api/codex")
+        assert result.reason == FailoverReason.auth
+        assert result.message == "API keys are not supported by this endpoint. (endpoint: chatgpt.com)"
+
+    def test_stock_endpoint_and_no_base_url_keep_plain_message(self):
+        e = MockAPIError("Unauthorized", status_code=401, body=self._BODY)
+        for base_url in ("", "https://api.anthropic.com/v1"):
+            result = classify_api_error(e, provider="anthropic", model="claude", base_url=base_url)
+            assert result.message == "API keys are not supported by this endpoint.", base_url

From b7b203cda057ead5032ed602c01e8f7564e0c519 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 02:01:57 -0700
Subject: [PATCH 040/190] fix(skills): built-in name collisions show a note in
 /skills, /help skills and the palette
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A skill whose slug is a core command name or alias (e.g. a skill dir named
`handoff` or `plan`) is deliberately kept out of slash auto-registration —
370ebf2d3 ("guard skill slash commands against core-command and slug
collisions"): the skill map is consulted before built-in handlers in the
gateway dispatch path, so an auto /handoff would shadow the core command.
That guard stays. What users saw until now was only a WARNING in agent.log
repeated every session; the skill sat in `/skills list` as "enabled" with no
hint why `/handoff` ran the built-in instead (#113560).

Now one helper, agent.skill_commands.skill_command_collision_note, is the
single collision predicate: scan_skill_commands() uses it for the skip, and
four surfaces render the note it returns —
  "slash command /<name> unavailable — name taken by built-in; use /skill <name>"

- hermes_cli/skills_hub.py::do_list — the Status cell of `/skills list` /
  `hermes skills list`
- hermes_cli/cli_info_mixin.py::show_help — one dim ⚠ line per colliding
  skill under `/help skills` (also when no skill command is registered)
- tui_gateway/methods_tools.py::_catalog_skills — the commands.catalog RPC
  carries the notice in its existing `warning` field (rendered by the Desktop
  `/commands` output); discovery-failure messages still win over it
- hermes_cli/slash_exec.py::_exec_commands — the messaging-gateway `/commands`
  listing (Telegram/Discord/…) appends one ⚠ line per colliding skill

Fixes #113560
---
 agent/skill_commands.py                       | 26 ++++++--
 hermes_cli/cli_info_mixin.py                  | 17 ++++--
 hermes_cli/skills_hub.py                      |  8 ++-
 hermes_cli/slash_exec.py                      |  5 ++
 .../test_skill_collision_visibility.py        | 59 +++++++++++++++++++
 tui_gateway/methods_tools.py                  | 21 ++++---
 website/docs/reference/slash-commands.md      |  2 +-
 7 files changed, 116 insertions(+), 22 deletions(-)
 create mode 100644 tests/hermes_cli/test_skill_collision_visibility.py

diff --git a/agent/skill_commands.py b/agent/skill_commands.py
index 1ce7098d4d..ec17a02d9a 100644
--- a/agent/skill_commands.py
+++ b/agent/skill_commands.py
@@ -336,7 +336,22 @@ def _scaffold_header(
 _SCAN_SKIP_PARTS = {'.git', '.github', '.hub', '.archive', '.locks'}
 
 
-def _scan_skill_md(skill_md: Path, disabled: set, seen_names: set, commands: Dict[str, Dict[str, Any]], resolve_command) -> None:
+def skill_command_collision_note(name: str) -> Optional[str]:
+    """User-facing note when *name*'s slash slug is a core command (name or alias), else None.
+
+    The single source of the collision predicate: ``scan_skill_commands`` uses it to skip
+    auto-registration (the shadowing guard from 370ebf2d3 — the skill map is consulted before
+    built-in handlers), and the ``/skills`` listing plus the command palette render the note so
+    the skipped skill is explained where the user looks, not only in the log.
+    """
+    from hermes_cli.commands import resolve_command
+    cmd_name = slugify_skill_name(name)
+    if not cmd_name or resolve_command(cmd_name) is None:
+        return None
+    return f"slash command /{cmd_name} unavailable — name taken by built-in; use /skill {name}"
+
+
+def _scan_skill_md(skill_md: Path, disabled: set, seen_names: set, commands: Dict[str, Dict[str, Any]]) -> None:
     """Register one SKILL.md in *commands* (no-op when filtered or colliding)."""
     from tools.skills_tool import _parse_frontmatter, skill_matches_platform, skill_matches_environment
     if any(part in _SCAN_SKIP_PARTS for part in skill_md.parts):
@@ -356,9 +371,9 @@ def _scan_skill_md(skill_md: Path, disabled: set, seen_names: set, commands: Dic
     cmd_name = slugify_skill_name(name)
     if not cmd_name:
         return
-    # A collision with a core command (name or alias, via resolve_command) skips
-    # auto-registration; the skill stays loadable via /skill <name>.
-    if resolve_command(cmd_name) is not None:
+    # A collision with a core command (name or alias) skips auto-registration; the skill stays
+    # loadable via /skill <name>. The same predicate feeds the /skills + palette notes.
+    if skill_command_collision_note(name) is not None:
         logger.warning("Skill %r generates slash command '/%s' which collides with a core Hermes command; "
                        "skipping auto-registration. Use '/skill %s' instead.", name, cmd_name, name)
         return
@@ -393,7 +408,6 @@ def scan_skill_commands() -> Dict[str, Dict[str, Any]]:
         from agent.skill_utils import (
             get_external_skills_dirs, get_project_skills_dirs, iter_project_skill_files, iter_skill_index_files,
         )
-        from hermes_cli.commands import resolve_command
         disabled = _get_disabled_skill_names()
         seen_names: set = set()
         # Precedence: project (through the quarantine chokepoint) > local > external.
@@ -407,7 +421,7 @@ def scan_skill_commands() -> Dict[str, Dict[str, Any]]:
         for _iter in iters:
             for skill_md in _iter:
                 try:
-                    _scan_skill_md(skill_md, disabled, seen_names, commands, resolve_command)
+                    _scan_skill_md(skill_md, disabled, seen_names, commands)
                 except Exception:
                     continue
     except Exception:
diff --git a/hermes_cli/cli_info_mixin.py b/hermes_cli/cli_info_mixin.py
index 76aa226a70..1c55c38b43 100644
--- a/hermes_cli/cli_info_mixin.py
+++ b/hermes_cli/cli_info_mixin.py
@@ -258,12 +258,17 @@ class CLIInfoMixin:
         # /help skills — the full list, kept out of the default view so core commands don't
         # scroll off screen.
         if arg.lower() in ("skills", "skill"):
-            if not skill_commands:
-                _cprint("\n  No skill commands installed.\n")
-                return
-            _cprint(f"\n  ⚡ {_BOLD}Skill Commands{_RST} ({len(skill_commands)} installed):")
-            for cmd, info in sorted(skill_commands.items()):
-                _row(cmd, info['description'], 22)
+            from agent.skill_commands import skill_command_collision_note
+            from tools.skills_tool import _find_all_skills
+            if skill_commands:
+                _cprint(f"\n  ⚡ {_BOLD}Skill Commands{_RST} ({len(skill_commands)} installed):")
+                for cmd, info in sorted(skill_commands.items()):
+                    _row(cmd, info['description'], 22)
+            else:
+                _cprint("\n  No skill commands installed.")
+            # Skills whose name is a built-in command never get a /<name> (agent.skill_commands guard).
+            for note in filter(None, (skill_command_collision_note(s["name"]) for s in _find_all_skills())):
+                _cprint(f"    {_DIM}⚠ {note}{_RST}")
             _cprint("")
             return
 
diff --git a/hermes_cli/skills_hub.py b/hermes_cli/skills_hub.py
index e46e1725b6..9731b57ce1 100644
--- a/hermes_cli/skills_hub.py
+++ b/hermes_cli/skills_hub.py
@@ -783,6 +783,7 @@ def do_list(source_filter: str = "all", enabled_only: bool = False,
     from tools.skills_sync import _read_manifest
     from tools.skills_tool import _find_all_skills
     from agent.skill_utils import get_disabled_skill_names
+    from agent.skill_commands import skill_command_collision_note
     c = console or _console
     ensure_hub_dirs()
     hub_installed = {e["name"]: e for e in HubLockFile().list_installed()}
@@ -809,9 +810,12 @@ def do_list(source_filter: str = "all", enabled_only: bool = False,
         counts[source_type] += 1
         enabled_count += is_enabled
         disabled_count += not is_enabled
+        status = "[bold green]enabled[/]" if is_enabled else "[dim red]disabled[/]"
+        # Name taken by a built-in: the skill loads but has no /<name> (see agent.skill_commands).
+        if note := skill_command_collision_note(name):
+            status += f"\n[yellow]{note}[/]"
         table.add_row(name, skill.get("category", ""), source_display,
-                      _trust_cell(trust, source_display),
-                      "[bold green]enabled[/]" if is_enabled else "[dim red]disabled[/]")
+                      _trust_cell(trust, source_display), status)
 
     c.print(table)
     tail = (f"{enabled_count} enabled shown" if enabled_only
diff --git a/hermes_cli/slash_exec.py b/hermes_cli/slash_exec.py
index c590ba6609..876f355747 100644
--- a/hermes_cli/slash_exec.py
+++ b/hermes_cli/slash_exec.py
@@ -140,6 +140,11 @@ def _exec_commands(ctx: CommandContext) -> CommandReply:
             for cmd in sorted(skill_cmds):
                 desc = skill_cmds[cmd].get("description", "").strip() or t("gateway.commands.default_desc")
                 entries.append(f"`{cmd}` — {desc}")
+        # Skills kept off the menu because a built-in owns the name (agent.skill_commands guard).
+        from agent.skill_commands import skill_command_collision_note
+        from tools.skills_tool import _find_all_skills
+        entries.extend(f"⚠ {note}" for note in filter(None, map(
+            skill_command_collision_note, sorted(s["name"] for s in _find_all_skills()))))
     except Exception:
         pass
 
diff --git a/tests/hermes_cli/test_skill_collision_visibility.py b/tests/hermes_cli/test_skill_collision_visibility.py
new file mode 100644
index 0000000000..0998ef7ed3
--- /dev/null
+++ b/tests/hermes_cli/test_skill_collision_visibility.py
@@ -0,0 +1,59 @@
+"""A skill named like a built-in command is kept out of auto-registration (the 370ebf2d3 guard)
+and every listing surface says so where the user looks: the ``/skills`` table, ``/help skills``
+and the ``commands.catalog`` palette RPC. A non-colliding skill carries no note."""
+from __future__ import annotations
+
+import contextlib
+import io
+
+from rich.console import Console
+
+from hermes_constants import get_hermes_home
+
+NOTE = "slash command /handoff unavailable — name taken by built-in; use /skill handoff"
+
+
+def _write_skill(name: str) -> None:
+    skill_dir = get_hermes_home() / "skills" / name
+    skill_dir.mkdir(parents=True)
+    (skill_dir / "SKILL.md").write_text(f"---\nname: {name}\ndescription: {name} skill.\n---\n# {name}\n", encoding="utf-8")
+
+
+def test_built_in_name_collision_is_visible_on_every_listing_surface(monkeypatch):
+    import cli
+    import tools.skills_tool as skills_tool
+    from hermes_cli.cli_info_mixin import CLIInfoMixin
+    from hermes_cli.skills_hub import do_list
+    from tui_gateway import server
+
+    _write_skill("handoff")  # core CommandDef → dropped by scan_skill_commands
+    _write_skill("tidy-notes")  # control
+    monkeypatch.setattr(skills_tool, "_SKILLS_CACHE", {})
+    monkeypatch.setattr(cli, "_skill_commands", None)
+
+    sink = io.StringIO()
+    do_list(console=Console(file=sink, force_terminal=False, color_system=None, width=200))
+    skills_table = sink.getvalue()
+    assert NOTE in skills_table
+    assert "tidy-notes" in skills_table and skills_table.count("unavailable") == 1
+
+    class _Cli(CLIInfoMixin):
+        config: dict = {}
+
+        def _command_available(self, slash_command):
+            return True
+
+    help_out = io.StringIO()
+    with contextlib.redirect_stdout(help_out):
+        _Cli().show_help("skills")
+    assert NOTE in help_out.getvalue()
+    assert "/tidy-notes" in help_out.getvalue() and "/handoff" not in help_out.getvalue().replace(NOTE, "")
+
+    catalog = server._methods["commands.catalog"](1, {})["result"]
+    assert catalog["warning"] == NOTE
+    assert "/tidy-notes" in catalog["skills"] and "/handoff" not in catalog["skills"]
+
+    from hermes_cli.slash_exec import CommandContext, _exec_commands
+
+    gateway_commands = _exec_commands(CommandContext(args="", options={"page_size": 500})).text
+    assert f"⚠ {NOTE}" in gateway_commands and "`/tidy-notes`" in gateway_commands
diff --git a/tui_gateway/methods_tools.py b/tui_gateway/methods_tools.py
index e65800a7f4..b260bca1e3 100644
--- a/tui_gateway/methods_tools.py
+++ b/tui_gateway/methods_tools.py
@@ -425,21 +425,28 @@ def _catalog_plugin_commands(cat: _Catalog) -> None:
         cat.commands[key] = {"argument_mode": mode, "desktop": None}
 
 
-def _catalog_skills(cat: _Catalog, skills: dict[str, dict]) -> None:
-    """Append skill pairs and fill ``skills`` = ``{key: {usage, origin}}`` (every consumer ranks by them)."""
+def _catalog_skills(cat: _Catalog, skills: dict[str, dict]) -> str:
+    """Append skill pairs and fill ``skills`` = ``{key: {usage, origin}}`` (every consumer ranks by them).
+    Returns the one-line notice for skills whose name is a built-in command (no ``/<name>`` entry;
+    ``agent.skill_commands`` guard), ``""`` when none."""
     usage, origin_of = _skill_usage_lookup()
-    for k, info in sorted(_tools_mod("agent.skill_commands").scan_skill_commands().items()):
+    sc = _tools_mod("agent.skill_commands")
+    for k, info in sorted(sc.scan_skill_commands().items()):
         cat.pairs.append([k, str(info.get("description", "Skill"))])
         name = str(info.get("name") or k.lstrip("/"))
         skills[k] = {"usage": usage(name), "origin": origin_of(name)}
+    names = sorted(s["name"] for s in _tools_mod("tools.skills_tool")._find_all_skills())
+    return "; ".join(filter(None, map(sc.skill_command_collision_note, names)))
 
 
 @_rpc("commands.catalog", 5020)
 def _(rid, params: dict) -> dict:
     """Registry-backed slash metadata, categorized, no aliases. Discovery failures land in ``warning``
-    (skills' message wins, then quick commands', then plugins'). Skill discovery is bound to the calling
-    session's profile and workspace (``_completion_cwd``: its record, else the cwd a new session would be
-    seeded with) so project-local skills register for the repo the session is actually in (#114359)."""
+    (skills' message wins, then quick commands', then plugins'); with no failure it carries the
+    built-in-name collision notice for skills that have no ``/<name>`` (empty when none). Skill
+    discovery is bound to the calling session's profile and workspace (``_completion_cwd``: its record,
+    else the cwd a new session would be seeded with) so project-local skills register for the repo the
+    session is actually in (#114359)."""
     cat = _Catalog()
     _catalog_registry(cat)
     warning = ""
@@ -454,7 +461,7 @@ def _(rid, params: dict) -> dict:
     skills: dict[str, dict] = {}
     try:
         with _session_home_scope(_sessions.get(params.get("session_id", "")), cwd=_completion_cwd(params)):
-            _catalog_skills(cat, skills)
+            warning = _catalog_skills(cat, skills) or warning
     except Exception as e:
         warning = f"skill discovery unavailable: {e}"
     return _ok(rid, {
diff --git a/website/docs/reference/slash-commands.md b/website/docs/reference/slash-commands.md
index eb10b32483..527735c827 100644
--- a/website/docs/reference/slash-commands.md
+++ b/website/docs/reference/slash-commands.md
@@ -11,7 +11,7 @@ Hermes has two slash-command surfaces, both driven by a central `COMMAND_REGISTR
 - **Interactive CLI slash commands** — dispatched by `cli.py`, with autocomplete from the registry
 - **Messaging slash commands** — dispatched by `gateway/run.py`, with help text and platform menus generated from the registry
 
-Installed skills are also exposed as dynamic slash commands on both surfaces. (`/plan` used to be one of these; it is now a built-in command — see the Session table below.)
+Installed skills are also exposed as dynamic slash commands on both surfaces. (`/plan` used to be one of these; it is now a built-in command — see the Session table below.) A skill whose name matches a built-in command (or one of its aliases) never gets its own `/<name>` — the built-in wins and the skill stays loadable via `/skill <name>`; `/skills list`, `/help skills` and the command palette mark such a skill with `slash command /<name> unavailable — name taken by built-in; use /skill <name>`.
 
 ## Permissions and admin/user split
 

From 2a4556449e1bdb85ea4a01dc05a37bf604c42574 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 04:53:06 -0700
Subject: [PATCH 041/190] fix(tui_gateway): commands.catalog keeps a
 discovery-failure warning over the skill collision note

A skill whose name collides with a built-in command produced a collision
note that overwrote a quick_commands / plugin discovery failure already in
`warning`, so a broken config.yaml was silently reported as a mere name
collision. Failures now win; the collision note only fills an otherwise
empty warning. `_catalog_skills` still runs unconditionally so skills keep
listing when a loader failed.
---
 .../test_skill_collision_visibility.py        | 19 +++++++++++++++++++
 tui_gateway/methods_tools.py                  |  7 ++++---
 2 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/tests/hermes_cli/test_skill_collision_visibility.py b/tests/hermes_cli/test_skill_collision_visibility.py
index 0998ef7ed3..24d71b8d99 100644
--- a/tests/hermes_cli/test_skill_collision_visibility.py
+++ b/tests/hermes_cli/test_skill_collision_visibility.py
@@ -57,3 +57,22 @@ def test_built_in_name_collision_is_visible_on_every_listing_surface(monkeypatch
 
     gateway_commands = _exec_commands(CommandContext(args="", options={"page_size": 500})).text
     assert f"⚠ {NOTE}" in gateway_commands and "`/tidy-notes`" in gateway_commands
+
+
+def test_catalog_discovery_failure_warning_outranks_the_collision_note(monkeypatch):
+    """A colliding skill must not hide a real discovery failure: the failure stays in ``warning``."""
+    import tools.skills_tool as skills_tool
+    from tui_gateway import server
+
+    _write_skill("handoff")
+    _write_skill("tidy-notes")  # control: skills still list when a loader failed
+    monkeypatch.setattr(skills_tool, "_SKILLS_CACHE", {})
+
+    def _broken_cfg():
+        raise RuntimeError("config.yaml unreadable")
+
+    monkeypatch.setattr(server, "_load_cfg", _broken_cfg)
+
+    catalog = server._methods["commands.catalog"](1, {})["result"]
+    assert catalog["warning"] == "quick_commands discovery unavailable: config.yaml unreadable"
+    assert "/tidy-notes" in catalog["skills"]
diff --git a/tui_gateway/methods_tools.py b/tui_gateway/methods_tools.py
index b260bca1e3..b2c7405e55 100644
--- a/tui_gateway/methods_tools.py
+++ b/tui_gateway/methods_tools.py
@@ -442,8 +442,8 @@ def _catalog_skills(cat: _Catalog, skills: dict[str, dict]) -> str:
 @_rpc("commands.catalog", 5020)
 def _(rid, params: dict) -> dict:
     """Registry-backed slash metadata, categorized, no aliases. Discovery failures land in ``warning``
-    (skills' message wins, then quick commands', then plugins'); with no failure it carries the
-    built-in-name collision notice for skills that have no ``/<name>`` (empty when none). Skill
+    (skills' message wins, then quick commands', then plugins'); only with no failure does it carry
+    the built-in-name collision notice for skills that have no ``/<name>`` (empty when none). Skill
     discovery is bound to the calling session's profile and workspace (``_completion_cwd``: its record,
     else the cwd a new session would be seeded with) so project-local skills register for the repo the
     session is actually in (#114359)."""
@@ -461,7 +461,8 @@ def _(rid, params: dict) -> dict:
     skills: dict[str, dict] = {}
     try:
         with _session_home_scope(_sessions.get(params.get("session_id", "")), cwd=_completion_cwd(params)):
-            warning = _catalog_skills(cat, skills) or warning
+            collision_note = _catalog_skills(cat, skills)  # always runs: skills must list even when a loader failed
+        warning = warning or collision_note
     except Exception as e:
         warning = f"skill discovery unavailable: {e}"
     return _ok(rid, {

From b26944ce3b47a5883736e09ce901a807a39c4330 Mon Sep 17 00:00:00 2001
From: joaomarcos <joaomarcosdias444@gmail.com>
Date: Thu, 17 Sep 2026 22:08:49 -0300
Subject: [PATCH 042/190] fix(skills): retry ClawHub catalog pages on fetch
 failure

Treat timeout/non-200 catalog pages as a retryable hole instead of
cursor exhaustion so the skills index builder can finish a full walk.

Fixes #114525
---
 tests/tools/test_skills_hub_clawhub.py | 48 ++++++++++++++++++++++++++
 tools/skills_hub_clawhub.py            | 33 ++++++++++++++----
 2 files changed, 75 insertions(+), 6 deletions(-)

diff --git a/tests/tools/test_skills_hub_clawhub.py b/tests/tools/test_skills_hub_clawhub.py
index 82cc6a5991..2d917a8900 100644
--- a/tests/tools/test_skills_hub_clawhub.py
+++ b/tests/tools/test_skills_hub_clawhub.py
@@ -516,6 +516,54 @@ class TestClawHubCatalogWalkBounded(unittest.TestCase):
         self.assertEqual(page_calls["n"], 750)
         self.assertEqual(len(results), 750)
 
+    @patch("tools.skills_hub_clawhub.time.sleep")
+    @patch("tools.skills_hub._write_index_cache")
+    @patch("tools.skills_hub._read_index_cache", return_value=None)
+    def test_unbounded_walk_retries_none_page_then_caches(
+        self, _mock_read_cache, mock_write_cache, mock_sleep
+    ):
+        """A single None page is a fetch hole, not catalog end — resume and cache."""
+        payloads = [
+            {"items": [{"slug": "skill-a", "displayName": "A"}], "nextCursor": "c1"},
+            None,
+            {"items": [{"slug": "skill-b", "displayName": "B"}]},
+        ]
+        calls = {"n": 0}
+
+        def fake_get_json(url, *, timeout=30, **kwargs):
+            idx = calls["n"]
+            calls["n"] += 1
+            return payloads[idx] if idx < len(payloads) else None
+
+        with patch.object(ClawHubSource, "_get_json", side_effect=fake_get_json):
+            results = self.src._load_catalog_index(max_items=0)
+
+        self.assertEqual([m.identifier for m in results], ["skill-a", "skill-b"])
+        mock_write_cache.assert_called_once()
+        mock_sleep.assert_called()
+
+    @patch("tools.skills_hub_clawhub.time.sleep")
+    @patch("tools.skills_hub._write_index_cache")
+    @patch("tools.skills_hub._read_index_cache", return_value=None)
+    def test_unbounded_walk_exhausted_retries_does_not_cache(
+        self, _mock_read_cache, mock_write_cache, mock_sleep
+    ):
+        """Five consecutive None pages after a live cursor must not poison the cache."""
+        calls = {"n": 0}
+
+        def fake_get_json(url, *, timeout=30, **kwargs):
+            idx = calls["n"]
+            calls["n"] += 1
+            if idx == 0:
+                return {"items": [{"slug": "skill-a", "displayName": "A"}], "nextCursor": "c1"}
+            return None
+
+        with patch.object(ClawHubSource, "_get_json", side_effect=fake_get_json):
+            results = self.src._load_catalog_index(max_items=0)
+
+        self.assertEqual([m.identifier for m in results], ["skill-a"])
+        mock_write_cache.assert_not_called()
+        self.assertGreaterEqual(calls["n"], 6)
 
     @patch("tools.skills_hub._write_index_cache")
     @patch("tools.skills_hub._read_index_cache", return_value=None)
diff --git a/tools/skills_hub_clawhub.py b/tools/skills_hub_clawhub.py
index 2d63f5be2e..22b978ef51 100644
--- a/tools/skills_hub_clawhub.py
+++ b/tools/skills_hub_clawhub.py
@@ -298,8 +298,12 @@ class ClawHubSource(GuardedFetchMixin, SkillSource):
         gathered (browse's cold-start fallback renders one page); ``0`` walks
         to exhaustion (offline index builder). Only a COMPLETE walk (cursor
         exhausted or page cap) is written to the shared ``clawhub_catalog_v1``
-        cache — a walk cut by ``max_items`` or the wall-clock budget would
-        poison it with a partial slice.
+        cache — a walk cut by ``max_items``, the wall-clock budget, or a
+        failed page fetch would poison it with a partial slice.
+
+        ``_get_json`` returns ``None`` on timeout/non-200. That is not catalog
+        exhaustion: retry the same cursor instead of treating an empty/non-dict
+        payload as the last page.
         """
         cache_key = "clawhub_catalog_v1"
         cached = _cached_metas(cache_key)
@@ -314,14 +318,31 @@ class ClawHubSource(GuardedFetchMixin, SkillSource):
         # (max_items=0) must walk everything or it trips the deploy health floor.
         deadline = time.monotonic() + self.CATALOG_WALK_BUDGET_SECONDS if max_items > 0 else None
         partial = False
+        fetch_failures = 0
+        max_fetch_failures = 5
         for _ in range(750):
             if deadline is not None and time.monotonic() > deadline:
                 partial = True
                 break
             params: Dict[str, Any] = {"limit": 200, "cursor": cursor} if cursor else {"limit": 200}
             data = self._get_json(f"{self.BASE_URL}/skills", timeout=30, params=params)
-            items = data.get("items", []) if isinstance(data, dict) else []
-            if not isinstance(items, list) or not items:
+            items = data.get("items") if isinstance(data, dict) else None
+            next_cursor = data.get("nextCursor") if isinstance(data, dict) else None
+            page_ok = isinstance(data, dict) and isinstance(items, list)
+            # Empty items that still advertise a cursor are the same class of
+            # hole as None: not a terminal page.
+            retry_same_cursor = (not page_ok) or (
+                page_ok and not items and isinstance(next_cursor, str) and bool(next_cursor)
+            )
+            if retry_same_cursor:
+                fetch_failures += 1
+                if fetch_failures >= max_fetch_failures:
+                    partial = True
+                    break
+                time.sleep(min(2 ** fetch_failures, 8))
+                continue
+            fetch_failures = 0
+            if not items:
                 break
             for item in items:
                 slug = item.get("slug")
@@ -330,8 +351,8 @@ class ClawHubSource(GuardedFetchMixin, SkillSource):
                     meta = self._item_to_meta(item)
                     if meta:
                         results.append(meta)
-            cursor = data.get("nextCursor") if isinstance(data, dict) else None
-            if not isinstance(cursor, str) or not cursor:
+            cursor = next_cursor if isinstance(next_cursor, str) and next_cursor else None
+            if not cursor:
                 break
             if max_items > 0 and len(results) >= max_items:
                 partial = True

From 73f39086f6e0f59e8b70d92d7657b68bc88133a9 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 00:51:06 -0700
Subject: [PATCH 043/190] fix(skills-index): retry only on a failed fetch; give
 the scheduled build time for slow ClawHub pages

Trim the salvaged retry to the case the logs show: `_get_json` returning None
(timeout / non-200) is a hole in the cursor walk, not the end of the catalog.
A dict page with an empty item list stays terminal as before, and the
interactive browse path (12 s budget) no longer sleeps up to 8 s per retry.
Constant `CATALOG_PAGE_RETRIES` replaces the local literal.

Workflow: `skills-index.yml` `timeout-minutes` 50 -> 120. Since Sep 17 ClawHub
serves ~10 s per 200-item page (was ~2.5 s), so the ~400-page walk alone takes
60-70 min; the 06:28 UTC runs on Sep 17 and Sep 18 were cancelled at 50 min with
the clawhub crawl still running, and the 18:19 run stopped at 12,145 skills
(< 20,000 floor) after one failed page. Both halves are needed for the index to
ship again.
---
 .github/workflows/skills-index.yml |  8 +++++---
 tools/skills_hub_clawhub.py        | 31 +++++++++++++-----------------
 2 files changed, 18 insertions(+), 21 deletions(-)

diff --git a/.github/workflows/skills-index.yml b/.github/workflows/skills-index.yml
index dde5b7ab82..6bcbbaaaa1 100644
--- a/.github/workflows/skills-index.yml
+++ b/.github/workflows/skills-index.yml
@@ -20,10 +20,12 @@ jobs:
     # Only run on the upstream repository, not on forks
     if: github.repository == 'NousResearch/hermes-agent'
     runs-on: ubuntu-latest
-    # Critical path (Sep 2026): clawhub walk ~14 min ∥ github taps ~8 min, then skills.sh
+    # Critical path (Sep 2026): clawhub walk ∥ github taps ~8 min, then skills.sh
     # resolve ~6 min, then a bounded 8 min owner enrichment. 15 min cancelled every
-    # scheduled run for two months and left the live index frozen.
-    timeout-minutes: 50
+    # scheduled run for two months and left the live index frozen; on Sep 17 ClawHub
+    # page latency went from ~2.5 s to ~10 s, so the ~400-page walk alone runs 60-70 min
+    # and 50 min cancelled it again (#114525). The cron is 12-hourly; 120 min leaves headroom.
+    timeout-minutes: 120
     environment: trusted-automation
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
diff --git a/tools/skills_hub_clawhub.py b/tools/skills_hub_clawhub.py
index 22b978ef51..70b52b3a2e 100644
--- a/tools/skills_hub_clawhub.py
+++ b/tools/skills_hub_clawhub.py
@@ -67,6 +67,8 @@ class ClawHubSource(GuardedFetchMixin, SkillSource):
     # Wall-clock budget for a full catalog walk: 50k+ skills, sequential
     # (~250 requests each under timeout=30), so unbounded it blocks for minutes.
     CATALOG_WALK_BUDGET_SECONDS = 12
+    # Consecutive failed fetches of one catalog page before the walk gives up as partial.
+    CATALOG_PAGE_RETRIES = 5
     ZIP_DOWNLOAD_MAX_BYTES = 25 * 1024 * 1024
     ZIP_DOWNLOAD_CHUNK_BYTES = 64 * 1024
     _SLUG_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]*$")
@@ -301,9 +303,9 @@ class ClawHubSource(GuardedFetchMixin, SkillSource):
         cache — a walk cut by ``max_items``, the wall-clock budget, or a
         failed page fetch would poison it with a partial slice.
 
-        ``_get_json`` returns ``None`` on timeout/non-200. That is not catalog
-        exhaustion: retry the same cursor instead of treating an empty/non-dict
-        payload as the last page.
+        ``_get_json`` returns ``None`` on timeout/non-200. That is a hole in the
+        walk, not catalog exhaustion: the same cursor is retried a few times
+        before the walk gives up (partial, uncached).
         """
         cache_key = "clawhub_catalog_v1"
         cached = _cached_metas(cache_key)
@@ -319,30 +321,23 @@ class ClawHubSource(GuardedFetchMixin, SkillSource):
         deadline = time.monotonic() + self.CATALOG_WALK_BUDGET_SECONDS if max_items > 0 else None
         partial = False
         fetch_failures = 0
-        max_fetch_failures = 5
         for _ in range(750):
             if deadline is not None and time.monotonic() > deadline:
                 partial = True
                 break
             params: Dict[str, Any] = {"limit": 200, "cursor": cursor} if cursor else {"limit": 200}
             data = self._get_json(f"{self.BASE_URL}/skills", timeout=30, params=params)
-            items = data.get("items") if isinstance(data, dict) else None
-            next_cursor = data.get("nextCursor") if isinstance(data, dict) else None
-            page_ok = isinstance(data, dict) and isinstance(items, list)
-            # Empty items that still advertise a cursor are the same class of
-            # hole as None: not a terminal page.
-            retry_same_cursor = (not page_ok) or (
-                page_ok and not items and isinstance(next_cursor, str) and bool(next_cursor)
-            )
-            if retry_same_cursor:
+            if data is None:
                 fetch_failures += 1
-                if fetch_failures >= max_fetch_failures:
+                if fetch_failures >= self.CATALOG_PAGE_RETRIES:
                     partial = True
                     break
-                time.sleep(min(2 ** fetch_failures, 8))
+                # Interactive browse stays inside its 12 s budget; the index builder backs off.
+                time.sleep(0.5 if deadline is not None else min(2 ** fetch_failures, 8))
                 continue
             fetch_failures = 0
-            if not items:
+            items = data.get("items", []) if isinstance(data, dict) else []
+            if not isinstance(items, list) or not items:
                 break
             for item in items:
                 slug = item.get("slug")
@@ -351,8 +346,8 @@ class ClawHubSource(GuardedFetchMixin, SkillSource):
                     meta = self._item_to_meta(item)
                     if meta:
                         results.append(meta)
-            cursor = next_cursor if isinstance(next_cursor, str) and next_cursor else None
-            if not cursor:
+            cursor = data.get("nextCursor") if isinstance(data, dict) else None
+            if not isinstance(cursor, str) or not cursor:
                 break
             if max_items > 0 and len(results) >= max_items:
                 partial = True

From 43eda09e2d5d073e7650ecd3211cc6e5d74557c0 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 04:33:00 -0700
Subject: [PATCH 044/190] fix(skills): retry a failed skills.sh sitemap shard;
 never cache a partial catalog

A per-skill sitemap shard whose fetch failed (timeout/503 -> None) was read as
an empty shard and the resulting partial catalog was written to the shared
skills_sh_sitemap_v1 cache, so one slow shard silently dropped skills from the
published index for the whole TTL. Same class as the ClawHub page-walk fix in
this PR: retry the shard up to the shared CATALOG_PAGE_RETRIES bound, and if it
stays dark return the partial slice without caching it.

CATALOG_PAGE_RETRIES moves from ClawHubSource to the SkillSource base so both
catalog walks share one bound.
---
 tests/tools/test_skills_hub.py | 25 +++++++++++++++++++++++++
 tools/skills_hub_clawhub.py    |  2 --
 tools/skills_hub_models.py     |  2 ++
 tools/skills_hub_skillssh.py   | 21 ++++++++++++++++-----
 4 files changed, 43 insertions(+), 7 deletions(-)

diff --git a/tests/tools/test_skills_hub.py b/tests/tools/test_skills_hub.py
index bcc2dfc2bd..32e759998f 100644
--- a/tests/tools/test_skills_hub.py
+++ b/tests/tools/test_skills_hub.py
@@ -254,6 +254,31 @@ class TestSkillsShSource:
         assert results[0].path == "vercel-react-best-practices"
         assert results[0].extra["installs"] == 207679
 
+    @patch("tools.skills_hub_skillssh.time.sleep")
+    @patch("tools.skills_hub._write_index_cache")
+    @patch("tools.skills_hub._read_index_cache", return_value=None)
+    def test_sitemap_catalog_retries_failed_shard_and_never_caches_partial(
+        self, _mock_read_cache, mock_write_cache, _mock_sleep,
+    ):
+        """A per-skill sitemap shard that keeps failing is a hole in the catalog, not an
+        empty shard: retry it, and never publish the partial slice to the shared cache."""
+        index = ("<sitemapindex><sitemap><loc>https://www.skills.sh/sitemap-skills-0.xml</loc></sitemap>"
+                 "<sitemap><loc>https://www.skills.sh/sitemap-skills-1.xml</loc></sitemap></sitemapindex>")
+        shard0 = "<urlset><url><loc>https://www.skills.sh/o/r/skill-a</loc></url></urlset>"
+        calls: List[str] = []
+
+        def fake_get_text(url, **kwargs):
+            calls.append(url)
+            if url.endswith("sitemap.xml"):
+                return index
+            return shard0 if url.endswith("sitemap-skills-0.xml") else None
+
+        with patch("tools.skills_hub_skillssh._get_text", side_effect=fake_get_text):
+            results = self._source()._sitemap_catalog(0)
+
+        assert [m.identifier for m in results] == ["skills-sh/o/r/skill-a"]
+        assert calls.count("https://www.skills.sh/sitemap-skills-1.xml") == SkillSource.CATALOG_PAGE_RETRIES
+        mock_write_cache.assert_not_called()
 
     @patch("tools.skills_hub._write_index_cache")
     @patch("tools.skills_hub._read_index_cache", return_value=None)
diff --git a/tools/skills_hub_clawhub.py b/tools/skills_hub_clawhub.py
index 70b52b3a2e..cec319c513 100644
--- a/tools/skills_hub_clawhub.py
+++ b/tools/skills_hub_clawhub.py
@@ -67,8 +67,6 @@ class ClawHubSource(GuardedFetchMixin, SkillSource):
     # Wall-clock budget for a full catalog walk: 50k+ skills, sequential
     # (~250 requests each under timeout=30), so unbounded it blocks for minutes.
     CATALOG_WALK_BUDGET_SECONDS = 12
-    # Consecutive failed fetches of one catalog page before the walk gives up as partial.
-    CATALOG_PAGE_RETRIES = 5
     ZIP_DOWNLOAD_MAX_BYTES = 25 * 1024 * 1024
     ZIP_DOWNLOAD_CHUNK_BYTES = 64 * 1024
     _SLUG_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]*$")
diff --git a/tools/skills_hub_models.py b/tools/skills_hub_models.py
index bcefb0224e..a1c5d8c584 100644
--- a/tools/skills_hub_models.py
+++ b/tools/skills_hub_models.py
@@ -130,6 +130,8 @@ class SkillSource(ABC):
 
     SOURCE_ID: str = ""
     TRUST_LEVEL: str = "community"
+    # Consecutive failed fetches of one catalog page/shard before a walk gives up as partial.
+    CATALOG_PAGE_RETRIES = 5
 
     @abstractmethod
     def search(self, query: str, limit: int = 10) -> List[SkillMeta]:
diff --git a/tools/skills_hub_skillssh.py b/tools/skills_hub_skillssh.py
index 5d7a94a848..a5cd8cd777 100644
--- a/tools/skills_hub_skillssh.py
+++ b/tools/skills_hub_skillssh.py
@@ -3,6 +3,7 @@
 import hashlib
 import logging
 import re
+import time
 from typing import Any, Dict, List, Optional
 
 from tools.skills_hub_github import GitHubAuth, GitHubSource, _split_repo_id
@@ -137,11 +138,20 @@ class SkillsShSource(SkillSource):
         if not skill_sitemap_urls:
             return self._featured_skills(limit)
 
-        # Step 2: collect canonical "owner/repo/skill" IDs from each sitemap.
-        seen, results = set(), []
+        # Step 2: collect canonical "owner/repo/skill" IDs from each sitemap. A shard
+        # ``_get_text`` returns None for is a hole, not an empty shard: retry it, and
+        # if it stays dark return the partial slice without publishing it to the cache.
+        seen, results, partial = set(), [], False
         for sitemap_url in skill_sitemap_urls:
-            xml = _xml(sitemap_url, 30)
-            for loc_match in self._SITEMAP_LOC_RE.finditer(xml or ""):
+            for attempt in range(1, self.CATALOG_PAGE_RETRIES + 1):
+                xml = _xml(sitemap_url, 30)
+                if xml is not None or attempt == self.CATALOG_PAGE_RETRIES:
+                    break
+                time.sleep(min(2 ** attempt, 8))
+            if xml is None:
+                partial = True
+                continue
+            for loc_match in self._SITEMAP_LOC_RE.finditer(xml):
                 m = self._SITEMAP_SKILL_RE.match(loc_match.group(1).strip())
                 if not m:
                     continue
@@ -153,7 +163,8 @@ class SkillsShSource(SkillSource):
                                               path=skill, extra=self._urls_for(canonical, repo)))
         if not results:
             return self._featured_skills(limit)
-        _cache_metas(cache_key, results)
+        if not partial:
+            _cache_metas(cache_key, results)
         return results[:limit] if limit > 0 else results
 
     def _featured_skills(self, limit: int) -> List[SkillMeta]:

From d457e7f039ee2f0b1b655fca9535b4e33f35c05a Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 11:16:39 -0700
Subject: [PATCH 045/190] test(skills): seam the sitemap-shard retry test on
 the hub guarded GET

The shard fetch now routes through hub()._guarded_http_get (#114887), so a patch
on tools.skills_hub_skillssh._get_text intercepted nothing and the test reached
the live sitemap on CI. Patch tools.skills_hub._ssrf_safe_http_get like the
neighbouring guarded-GET test and model the dark shard as a 503.
---
 tests/tools/test_skills_hub.py | 18 ++++++++++++------
 tools/skills_hub_skillssh.py   |  2 +-
 2 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/tests/tools/test_skills_hub.py b/tests/tools/test_skills_hub.py
index 32e759998f..b7631b4d73 100644
--- a/tests/tools/test_skills_hub.py
+++ b/tests/tools/test_skills_hub.py
@@ -258,23 +258,29 @@ class TestSkillsShSource:
     @patch("tools.skills_hub._write_index_cache")
     @patch("tools.skills_hub._read_index_cache", return_value=None)
     def test_sitemap_catalog_retries_failed_shard_and_never_caches_partial(
-        self, _mock_read_cache, mock_write_cache, _mock_sleep,
+        self, _mock_read_cache, mock_write_cache, _mock_sleep, monkeypatch,
     ):
         """A per-skill sitemap shard that keeps failing is a hole in the catalog, not an
         empty shard: retry it, and never publish the partial slice to the shared cache."""
+        monkeypatch.setattr("tools.skills_hub.is_safe_url", lambda _url: True)
+        monkeypatch.setattr("tools.skills_hub.check_website_access", lambda _url: None)
+        monkeypatch.setattr("tools.skills_hub_skillssh._cached_metas", lambda _key: None)
+        monkeypatch.setattr("tools.skills_hub_skillssh._cache_metas", lambda _key, _metas: None)
         index = ("<sitemapindex><sitemap><loc>https://www.skills.sh/sitemap-skills-0.xml</loc></sitemap>"
                  "<sitemap><loc>https://www.skills.sh/sitemap-skills-1.xml</loc></sitemap></sitemapindex>")
         shard0 = "<urlset><url><loc>https://www.skills.sh/o/r/skill-a</loc></url></urlset>"
         calls: List[str] = []
 
-        def fake_get_text(url, **kwargs):
+        def fake_get(url, *, timeout, headers=None):
             calls.append(url)
             if url.endswith("sitemap.xml"):
-                return index
-            return shard0 if url.endswith("sitemap-skills-0.xml") else None
+                return MagicMock(status_code=200, headers={}, text=index)
+            if url.endswith("sitemap-skills-0.xml"):
+                return MagicMock(status_code=200, headers={}, text=shard0)
+            return MagicMock(status_code=503, headers={}, text="")
 
-        with patch("tools.skills_hub_skillssh._get_text", side_effect=fake_get_text):
-            results = self._source()._sitemap_catalog(0)
+        monkeypatch.setattr("tools.skills_hub._ssrf_safe_http_get", fake_get)
+        results = self._source()._sitemap_catalog(0)
 
         assert [m.identifier for m in results] == ["skills-sh/o/r/skill-a"]
         assert calls.count("https://www.skills.sh/sitemap-skills-1.xml") == SkillSource.CATALOG_PAGE_RETRIES
diff --git a/tools/skills_hub_skillssh.py b/tools/skills_hub_skillssh.py
index a5cd8cd777..7a3fe96f3f 100644
--- a/tools/skills_hub_skillssh.py
+++ b/tools/skills_hub_skillssh.py
@@ -139,7 +139,7 @@ class SkillsShSource(SkillSource):
             return self._featured_skills(limit)
 
         # Step 2: collect canonical "owner/repo/skill" IDs from each sitemap. A shard
-        # ``_get_text`` returns None for is a hole, not an empty shard: retry it, and
+        # ``_xml`` returns None for is a hole, not an empty shard: retry it, and
         # if it stays dark return the partial slice without publishing it to the cache.
         seen, results, partial = set(), [], False
         for sitemap_url in skill_sitemap_urls:

From 1979f70429daa375a86a18874adf5a3c23210f50 Mon Sep 17 00:00:00 2001
From: kokhlo <konstantin.khlopkov93@gmail.com>
Date: Fri, 18 Sep 2026 08:44:08 +0300
Subject: [PATCH 046/190] fix(dashboard): refresh the setup record after a
 main-slot model assignment

A serve process whose boot-time free-tier mint failed keeps its bootstrap
record at provider_configured: false for the whole process lifetime, so the
web chat stays gated on "need setup" even after a provider lands on disk via
POST /api/model/set or a picker key save. Re-run the bootstrap inventory on
both write paths so setup.status (and the setup.ready broadcast) follow the
new configuration without a restart.

Fixes #114697
---
 hermes_cli/web_server_config.py              | 17 +++++
 tests/hermes_cli/test_web_server.py          | 39 ++++++++++
 tests/tui_gateway/test_tui_gateway_server.py | 78 ++++++++++++++++++++
 tui_gateway/methods_complete.py              |  5 ++
 4 files changed, 139 insertions(+)

diff --git a/hermes_cli/web_server_config.py b/hermes_cli/web_server_config.py
index a51ed2defd..53fa363e06 100644
--- a/hermes_cli/web_server_config.py
+++ b/hermes_cli/web_server_config.py
@@ -671,6 +671,22 @@ def _prepare_main_assignment(cfg: dict, provider: str, model: str, base_url: str
     return base_url, _validated_main_model_selection(cfg, provider, model, base_url, api_key)
 
 
+def _refresh_setup_readiness() -> None:
+    """Re-run the free-tier bootstrap inventory after a model assignment landed on disk.
+
+    A serve process whose boot-time mint failed keeps its record at
+    ``provider_configured: false`` for the whole process lifetime, so every
+    ``setup.status`` keeps the chat gated long after the user configured a
+    provider elsewhere. The re-inventory never mints when an identity already
+    exists; on success it broadcasts ``setup.ready`` to every connected client.
+    """
+    try:
+        from hermes_cli.free_tier_bootstrap import retry_bootstrap_mint
+        retry_bootstrap_mint(force=True, announce=True)
+    except Exception:
+        _log.debug("setup readiness refresh after model assignment failed", exc_info=True)
+
+
 def _apply_main_assignment_sync(cfg: dict, provider: str, model: str, base_url: str, api_key: str,
                                 prepared: "Optional[tuple[str, ModelSwitchResult]]" = None) -> dict:
     from hermes_cli.config import save_config
@@ -686,6 +702,7 @@ def _apply_main_assignment_sync(cfg: dict, provider: str, model: str, base_url:
     save_config(cfg)
     if new_provider in {"custom", "local"} and base_url:
         _register_custom_endpoint(base_url, api_key, model)
+    _refresh_setup_readiness()
 
     return {
         "ok": True,
diff --git a/tests/hermes_cli/test_web_server.py b/tests/hermes_cli/test_web_server.py
index 3a10de3dc0..1e3ff1fcbd 100644
--- a/tests/hermes_cli/test_web_server.py
+++ b/tests/hermes_cli/test_web_server.py
@@ -1506,6 +1506,45 @@ class TestWebServerEndpoints:
         assert data["model"] == "moonshotai/kimi-k2.6"
 
 
+    def test_model_set_refreshes_a_stale_setup_record(self, monkeypatch):
+        """POST /api/model/set landed a provider on disk; the serve process's
+        boot record must follow, or the web chat stays gated on "need setup"
+        until a restart (setup.status answers from the record)."""
+        from hermes_cli import free_tier_bootstrap as fb
+
+        fb.reset_for_tests()
+        monkeypatch.setattr(
+            "hermes_cli.model_cost_guard.expensive_model_warning",
+            lambda *_args, **_kwargs: None,
+        )
+        from hermes_cli.config import load_config, save_config
+        cfg = load_config()
+        cfg["model"] = {"provider": "openrouter", "default": "openai/gpt-5.5"}
+        save_config(cfg)
+        stale = fb.SetupRecord(
+            provider_configured=False, inference_provider="", free_tier=False,
+            has_identity=False, other_providers=False)
+        with fb._lock:
+            fb._record = stale
+            fb._started = True
+            fb._done.set()
+        refreshed = []
+        monkeypatch.setattr(
+            fb, "retry_bootstrap_mint", lambda **kw: refreshed.append(kw) or stale
+        )
+        try:
+            resp = self.client.post(
+                "/api/model/set",
+                json={"scope": "main", "provider": "openrouter",
+                      "model": "moonshotai/kimi-k2.6"},
+            )
+            assert resp.status_code == 200
+            assert resp.json()["ok"] is True
+            assert refreshed and refreshed[0].get("force") is True
+        finally:
+            fb.reset_for_tests()
+
+
 
 
 
diff --git a/tests/tui_gateway/test_tui_gateway_server.py b/tests/tui_gateway/test_tui_gateway_server.py
index fea556633a..9896bd3509 100644
--- a/tests/tui_gateway/test_tui_gateway_server.py
+++ b/tests/tui_gateway/test_tui_gateway_server.py
@@ -16968,6 +16968,84 @@ def test_model_save_key_uses_credential_lifecycle_and_picker_context(monkeypatch
     )
 
 
+def test_model_save_key_refreshes_a_stale_setup_record(monkeypatch):
+    """A key saved from the gated picker must move the boot record too, or the
+    chat stays "need setup" (setup.status answers from the record) until the
+    serve process restarts."""
+    from hermes_cli import free_tier_bootstrap as fb
+
+    fb.reset_for_tests()
+    stale = fb.SetupRecord(
+        provider_configured=False, inference_provider="", free_tier=False,
+        has_identity=False, other_providers=False)
+    with fb._lock:
+        fb._record = stale
+        fb._started = True
+        fb._done.set()
+    retried = []
+    monkeypatch.setattr(
+        fb, "retry_bootstrap_mint", lambda **kw: retried.append(kw) or stale
+    )
+    monkeypatch.setattr(
+        "hermes_cli.auth.PROVIDER_REGISTRY",
+        {"test-provider": types.SimpleNamespace(
+            name="Test Provider", auth_type="api_key",
+            api_key_env_vars=("TEST_STALE_RECORD_KEY",))})
+    monkeypatch.setattr("hermes_cli.config.is_managed", lambda: False)
+    monkeypatch.setattr(
+        "hermes_cli.credential_lifecycle.save_provider_env_credential", Mock())
+    monkeypatch.setattr(server, "_model_picker_context", Mock(return_value=object()))
+    monkeypatch.setattr(
+        "hermes_cli.inventory.build_models_payload",
+        Mock(return_value={"providers": [{"slug": "test-provider", "models": [], "total_models": 0}]}))
+
+    try:
+        resp = server._methods["model.save_key"](
+            104, {"slug": "test-provider", "api_key": "k-1"})
+
+        assert "result" in resp, resp
+        assert retried and retried[0].get("force") is True
+    finally:
+        fb.reset_for_tests()
+
+
+def test_model_save_key_leaves_a_profile_scoped_record_alone(monkeypatch):
+    """The record belongs to the launch profile; a profile-scoped save must not
+    rewrite it with another home's inventory."""
+    from hermes_cli import free_tier_bootstrap as fb
+
+    fb.reset_for_tests()
+    with fb._lock:
+        fb._record = fb.SetupRecord(
+            provider_configured=False, inference_provider="", free_tier=False,
+            has_identity=False, other_providers=False)
+        fb._started = True
+        fb._done.set()
+    retried = []
+    monkeypatch.setattr(fb, "retry_bootstrap_mint", lambda **kw: retried.append(kw))
+    monkeypatch.setattr(
+        "hermes_cli.auth.PROVIDER_REGISTRY",
+        {"test-provider": types.SimpleNamespace(
+            name="Test Provider", auth_type="api_key",
+            api_key_env_vars=("TEST_PROFILE_SCOPE_KEY",))})
+    monkeypatch.setattr("hermes_cli.config.is_managed", lambda: False)
+    monkeypatch.setattr(
+        "hermes_cli.credential_lifecycle.save_provider_env_credential", Mock())
+    monkeypatch.setattr(server, "_model_picker_context", Mock(return_value=object()))
+    monkeypatch.setattr(
+        "hermes_cli.inventory.build_models_payload",
+        Mock(return_value={"providers": [{"slug": "test-provider", "models": [], "total_models": 0}]}))
+
+    try:
+        resp = server._methods["model.save_key"](
+            105, {"slug": "test-provider", "api_key": "k-2", "profile": "other"})
+
+        assert "result" in resp, resp
+        assert retried == []
+    finally:
+        fb.reset_for_tests()
+
+
 # ---------------------------------------------------------------------------
 # prompt.submit — auto-title
 # ---------------------------------------------------------------------------
diff --git a/tui_gateway/methods_complete.py b/tui_gateway/methods_complete.py
index 63dc24a79f..822b01c8c0 100644
--- a/tui_gateway/methods_complete.py
+++ b/tui_gateway/methods_complete.py
@@ -360,6 +360,11 @@ def _(rid, params: dict) -> dict:
     from hermes_cli.credential_lifecycle import save_provider_env_credential  # also rotates stale config.yaml mirrors
     save_provider_env_credential(env_var, api_key)
     os.environ[env_var] = api_key  # so the refreshed inventory sees it
+    # The record may still say "nothing configured" from a failed boot-time mint; a
+    # fresh key must move setup.status (and the setup.ready listeners) with it.
+    from hermes_cli import free_tier_bootstrap
+    if free_tier_bootstrap.current_record() is not None and not params.get("profile"):
+        free_tier_bootstrap.retry_bootstrap_mint(force=True)
     # Shared inventory builder (lock-step with model.options / dashboard); picker_hints carries `authenticated`.
     from hermes_cli.inventory import build_models_payload
     payload = build_models_payload(_model_picker_context(_session_agent(params)), picker_hints=True, max_models=50)

From 5ae7ec8623d2848add82f7cc5a1767745459efff Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 01:03:30 -0700
Subject: [PATCH 047/190] fix(setup): a provider configured after boot unblocks
 the dashboard chat without a restart
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The serve process's free-tier boot record (`free_tier_bootstrap._record`) is
built once; when the boot inventory found nothing (mint failed or the tier is
off) it says `provider_configured: false` for the process lifetime and
`setup.status` answers from it, so the Ink chat (dashboard /chat, `hermes
--tui`) parks every new session on "Setup Required" no matter what the user
configures afterwards — the Models page, a picker key save, or `hermes setup`
from a shell all land on disk and change nothing in the running process.

Reconcile the record on read instead of re-minting on write: `reconcile_record`
re-runs the cheap inventory (`_inventory_other_providers`, the resolver ladder
with the free-tier rung hidden) when a `False` record's config files
(`config.yaml` / `.env` / `auth.json`) moved since the inventory that built it,
replaces the record's inventory half and broadcasts `setup.ready`. The mint
verdict is kept as is: only the boot bootstrap and its retries mint.
`wait_for_record` (what `setup.status` reads) reconciles, which also covers
writes this process never saw (`/setup`'s `hermes setup` handoff, `hermes model`
in docker exec, a hand edit); the two in-process write paths from #114708
(`/api/model/set`, `model.save_key`) call it for the immediate broadcast.

Dropped from #114708: `retry_bootstrap_mint(force=True)` on the write paths — a
forced portal mint (network, cooldown bypassed) inside an HTTP write; the record
only needed its inventory refreshed. Not taken from #108773: OR-ing the record
with `_has_any_provider_configured()` — that first-run guard counts host-wide
credentials (other host-wide agent-CLI logins) and answers True on a blank machine (verified
live on this host), which would open the gate with nothing configured.

The 4001 hint for a sessionless `config.set model` named "Settings -> Models",
a Desktop-only surface; the Ink chat has no Settings and the dashboard has a
Models page. One string now names /setup, the Models page and Settings ->
Models. The TUI's "Setup Required" panel no longer advertises `/model` as the
in-place fix (sessionless picks are refused by design, 75b1b43ec19).

Co-authored-by: chelsealong <chelsealong@126.com>
---
 hermes_cli/free_tier_bootstrap.py             | 64 +++++++++++++--
 hermes_cli/web_server_config.py               | 20 +----
 .../test_resolve_provider_custom_endpoint.py  | 27 +++++++
 tests/hermes_cli/test_web_server.py           | 43 +++++-----
 tests/tui_gateway/test_tui_gateway_server.py  | 78 -------------------
 tui_gateway/methods_complete.py               | 10 +--
 tui_gateway/methods_config.py                 |  5 +-
 tui_gateway/methods_config_set.py             |  7 +-
 ui-tui/src/content/setup.ts                   |  7 +-
 9 files changed, 124 insertions(+), 137 deletions(-)

diff --git a/hermes_cli/free_tier_bootstrap.py b/hermes_cli/free_tier_bootstrap.py
index 073a56c71c..0274ca9f29 100644
--- a/hermes_cli/free_tier_bootstrap.py
+++ b/hermes_cli/free_tier_bootstrap.py
@@ -16,7 +16,7 @@ from __future__ import annotations
 import logging
 import threading
 import time
-from dataclasses import asdict, dataclass, field
+from dataclasses import asdict, dataclass, field, replace
 from typing import Any, Dict, Optional
 
 logger = logging.getLogger("hermes_cli.auth")
@@ -59,6 +59,10 @@ _lock = threading.Lock()
 _record: Optional[SetupRecord] = None
 _done = threading.Event()
 _started = False
+# ``(mtime_ns, size)`` of the files the inventory reads, taken by the inventory that built the
+# current record; ``reconcile_record`` re-inventories only when they moved.
+_inventory_stamp: Optional[tuple] = None
+_INVENTORY_FILES = ("config.yaml", ".env", "auth.json")
 
 
 def current_record() -> Optional[SetupRecord]:
@@ -68,31 +72,77 @@ def current_record() -> Optional[SetupRecord]:
 
 def wait_for_record(timeout: float = SETUP_READY_WAIT_SECONDS) -> Optional[SetupRecord]:
     """Block up to ``timeout`` seconds for a bootstrap that is IN FLIGHT, then return whatever it
-    produced. Returns None at once when no bootstrap ever started in this process (a bare
-    ``tui_gateway`` under test, an old serve without the boot hook): the caller falls back to its
-    live probe instead of paying the wait for nothing."""
+    produced, reconciled with any provider configured since (:func:`reconcile_record`). Returns
+    None at once when no bootstrap ever started in this process (a bare ``tui_gateway`` under
+    test, an old serve without the boot hook): the caller falls back to its live probe instead of
+    paying the wait for nothing."""
     if not _started:
         return None
     _done.wait(timeout)
-    return _record
+    return reconcile_record()
+
+
+def reconcile_record() -> Optional[SetupRecord]:
+    """Let a provider configured AFTER boot count: a record that says ``provider_configured:
+    false`` is re-inventoried once ``config.yaml`` / ``.env`` / ``auth.json`` moved since the
+    inventory that built it, and replaced (+ ``setup.ready``) when something now carries
+    inference. The mint verdict (identity, failure block) is kept as is: only the boot bootstrap
+    and its retries mint. A record that already says ``True`` is never re-probed, so the answer
+    only moves false -> true here. Every write path that assigns the main model (the Models page,
+    a picker key save) calls this for the immediate broadcast; ``setup.status`` calls it for
+    writes this process never saw (``hermes setup`` / ``hermes model`` from a shell, a hand edit)."""
+    global _record
+    record = _record
+    if record is None or record.provider_configured or _inventory_stamp == _config_stamp():
+        return record
+    if not _inventory_other_providers():
+        return _record
+    refreshed = replace(record, provider_configured=True, other_providers=True,
+                        inference_provider=_resolve_inference(), finished_at=time.time())
+    with _lock:
+        if _record is not record:  # a retry replaced it meanwhile; its inventory is newer
+            return _record
+        _record = refreshed
+    _broadcast(refreshed)
+    return refreshed
 
 
 def reset_for_tests() -> None:
-    global _record, _started
+    global _record, _started, _inventory_stamp
     with _lock:
         _record = None
         _started = False
+        _inventory_stamp = None
         _done.clear()
 
 
+def _config_stamp() -> tuple:
+    from hermes_cli.config import get_hermes_home
+    home = get_hermes_home()
+    stamp = []
+    for name in _INVENTORY_FILES:
+        try:
+            st = (home / name).stat()
+            stamp.append((st.st_mtime_ns, st.st_size))
+        except OSError:
+            stamp.append(None)
+    return tuple(stamp)
+
+
 def _inventory_other_providers() -> bool:
     """Is anything usable configured BESIDES the free tier? Asks the resolver ladder itself (the
     thing that picks the provider for a turn) with the free-tier rung hidden: an explicit key, a
     config pin, a sign-in or a host credential answers; nothing else falls through to
     ``no_provider_configured``. Not ``_has_any_provider_configured``: that first-run guard also
     counts host credentials (gh auth, Claude Code) and a config pin, and it does not hide the
-    free-tier rung."""
+    free-tier rung.
+
+    Stamps the config files BEFORE reading them, so a write that lands during the inventory is
+    seen by the next :func:`reconcile_record`.
+    """
+    global _inventory_stamp
     from hermes_cli.auth import resolve_provider
+    _inventory_stamp = _config_stamp()
     try:
         return resolve_provider("auto", skip_free_tier=True) != "nous"
     except Exception as exc:
diff --git a/hermes_cli/web_server_config.py b/hermes_cli/web_server_config.py
index 53fa363e06..b5fd93f441 100644
--- a/hermes_cli/web_server_config.py
+++ b/hermes_cli/web_server_config.py
@@ -671,25 +671,10 @@ def _prepare_main_assignment(cfg: dict, provider: str, model: str, base_url: str
     return base_url, _validated_main_model_selection(cfg, provider, model, base_url, api_key)
 
 
-def _refresh_setup_readiness() -> None:
-    """Re-run the free-tier bootstrap inventory after a model assignment landed on disk.
-
-    A serve process whose boot-time mint failed keeps its record at
-    ``provider_configured: false`` for the whole process lifetime, so every
-    ``setup.status`` keeps the chat gated long after the user configured a
-    provider elsewhere. The re-inventory never mints when an identity already
-    exists; on success it broadcasts ``setup.ready`` to every connected client.
-    """
-    try:
-        from hermes_cli.free_tier_bootstrap import retry_bootstrap_mint
-        retry_bootstrap_mint(force=True, announce=True)
-    except Exception:
-        _log.debug("setup readiness refresh after model assignment failed", exc_info=True)
-
-
 def _apply_main_assignment_sync(cfg: dict, provider: str, model: str, base_url: str, api_key: str,
                                 prepared: "Optional[tuple[str, ModelSwitchResult]]" = None) -> dict:
     from hermes_cli.config import save_config
+    from hermes_cli.free_tier_bootstrap import reconcile_record
     base_url, result = prepared or _prepare_main_assignment(cfg, provider, model, base_url, api_key)
     provider, model = result.target_provider, result.new_model
     provider_entry = _provider_entry(cfg, provider)
@@ -702,7 +687,8 @@ def _apply_main_assignment_sync(cfg: dict, provider: str, model: str, base_url:
     save_config(cfg)
     if new_provider in {"custom", "local"} and base_url:
         _register_custom_endpoint(base_url, api_key, model)
-    _refresh_setup_readiness()
+    # The serve process's boot record may still say "nothing configured"; the chat gates on it.
+    reconcile_record()
 
     return {
         "ok": True,
diff --git a/tests/hermes_cli/test_resolve_provider_custom_endpoint.py b/tests/hermes_cli/test_resolve_provider_custom_endpoint.py
index d986f4dc95..2c9c03b359 100644
--- a/tests/hermes_cli/test_resolve_provider_custom_endpoint.py
+++ b/tests/hermes_cli/test_resolve_provider_custom_endpoint.py
@@ -89,3 +89,30 @@ def test_auto_provider_with_loopback_base_url_resolves_without_recursing(isolate
     monkeypatch.setattr(runtime_provider, "_resolves_to_custom", unexpected_provider_resolution)
 
     assert resolve_provider("auto") == "custom"
+
+
+def test_a_provider_configured_after_boot_flips_the_stale_setup_record(isolated_home, monkeypatch):
+    """A serve process whose boot inventory found nothing keeps that record for its lifetime;
+    ``setup.status`` reads it (``wait_for_record``), so the dashboard chat stayed on "Setup
+    Required" after the user configured a provider — from the Models page, a picker key, or
+    ``hermes setup`` in another process. A ``False`` record is reconciled with the config files
+    on read: it flips (+ one ``setup.ready``) once something carries inference, and a blank
+    machine stays ``False`` with no broadcast."""
+    from hermes_cli import free_tier_bootstrap as fb
+
+    broadcasts = []
+    monkeypatch.setattr(fb, "_broadcast", broadcasts.append)
+    boot = fb.run_bootstrap(announce=False)
+    assert boot.provider_configured is False
+    assert fb.wait_for_record(timeout=0) is boot and broadcasts == [], "blank machine: nothing to reconcile"
+
+    (isolated_home / "config.yaml").write_text(
+        "model:\n  default: qwen3\n  provider: custom\n  base_url: http://127.0.0.1:8000/v1\n  api_key: dummy\n",
+        encoding="utf-8",
+    )
+    fresh = fb.wait_for_record(timeout=0)
+    assert fresh.provider_configured is True and fresh.other_providers is True
+    assert fresh.inference_provider == "custom"
+    assert fresh.has_identity is boot.has_identity and fresh.failure == boot.failure, "the mint verdict is kept"
+    assert broadcasts == [fresh]
+    assert fb.wait_for_record(timeout=0) is fresh and broadcasts == [fresh], "settled: no re-inventory, no re-announce"
diff --git a/tests/hermes_cli/test_web_server.py b/tests/hermes_cli/test_web_server.py
index 1e3ff1fcbd..148909e587 100644
--- a/tests/hermes_cli/test_web_server.py
+++ b/tests/hermes_cli/test_web_server.py
@@ -1506,41 +1506,34 @@ class TestWebServerEndpoints:
         assert data["model"] == "moonshotai/kimi-k2.6"
 
 
-    def test_model_set_refreshes_a_stale_setup_record(self, monkeypatch):
-        """POST /api/model/set landed a provider on disk; the serve process's
-        boot record must follow, or the web chat stays gated on "need setup"
-        until a restart (setup.status answers from the record)."""
+    def test_model_set_flips_a_stale_setup_record(self, monkeypatch):
+        """POST /api/model/set landed a provider on disk; the serve process's boot record
+        (``provider_configured: false`` since a failed boot-time mint) must follow at once, with
+        the ``setup.ready`` broadcast, or the web chat stays gated on "need setup" until a restart
+        (setup.status answers from the record)."""
         from hermes_cli import free_tier_bootstrap as fb
 
         fb.reset_for_tests()
-        monkeypatch.setattr(
-            "hermes_cli.model_cost_guard.expensive_model_warning",
-            lambda *_args, **_kwargs: None,
-        )
-        from hermes_cli.config import load_config, save_config
-        cfg = load_config()
-        cfg["model"] = {"provider": "openrouter", "default": "openai/gpt-5.5"}
-        save_config(cfg)
-        stale = fb.SetupRecord(
-            provider_configured=False, inference_provider="", free_tier=False,
-            has_identity=False, other_providers=False)
+        monkeypatch.setattr("hermes_cli.model_cost_guard.expensive_model_warning", lambda *_a, **_k: None)
+        monkeypatch.setattr("agent.bedrock_adapter.has_aws_credentials", lambda: False)
+        broadcasts = []
+        monkeypatch.setattr(fb, "_broadcast", broadcasts.append)
         with fb._lock:
-            fb._record = stale
+            fb._record = fb.SetupRecord(provider_configured=False, inference_provider="", free_tier=False,
+                                        has_identity=False, other_providers=False)
             fb._started = True
             fb._done.set()
-        refreshed = []
-        monkeypatch.setattr(
-            fb, "retry_bootstrap_mint", lambda **kw: refreshed.append(kw) or stale
-        )
         try:
             resp = self.client.post(
                 "/api/model/set",
-                json={"scope": "main", "provider": "openrouter",
-                      "model": "moonshotai/kimi-k2.6"},
+                json={"scope": "main", "provider": "custom", "model": "local-model",
+                      "base_url": "http://127.0.0.1:8081/v1", "api_key": "sk-local"},
             )
-            assert resp.status_code == 200
-            assert resp.json()["ok"] is True
-            assert refreshed and refreshed[0].get("force") is True
+            assert resp.status_code == 200 and resp.json()["ok"] is True
+            record = fb.current_record()
+            assert record.provider_configured is True and record.other_providers is True
+            assert record.inference_provider == "custom"
+            assert broadcasts == [record]
         finally:
             fb.reset_for_tests()
 
diff --git a/tests/tui_gateway/test_tui_gateway_server.py b/tests/tui_gateway/test_tui_gateway_server.py
index 9896bd3509..fea556633a 100644
--- a/tests/tui_gateway/test_tui_gateway_server.py
+++ b/tests/tui_gateway/test_tui_gateway_server.py
@@ -16968,84 +16968,6 @@ def test_model_save_key_uses_credential_lifecycle_and_picker_context(monkeypatch
     )
 
 
-def test_model_save_key_refreshes_a_stale_setup_record(monkeypatch):
-    """A key saved from the gated picker must move the boot record too, or the
-    chat stays "need setup" (setup.status answers from the record) until the
-    serve process restarts."""
-    from hermes_cli import free_tier_bootstrap as fb
-
-    fb.reset_for_tests()
-    stale = fb.SetupRecord(
-        provider_configured=False, inference_provider="", free_tier=False,
-        has_identity=False, other_providers=False)
-    with fb._lock:
-        fb._record = stale
-        fb._started = True
-        fb._done.set()
-    retried = []
-    monkeypatch.setattr(
-        fb, "retry_bootstrap_mint", lambda **kw: retried.append(kw) or stale
-    )
-    monkeypatch.setattr(
-        "hermes_cli.auth.PROVIDER_REGISTRY",
-        {"test-provider": types.SimpleNamespace(
-            name="Test Provider", auth_type="api_key",
-            api_key_env_vars=("TEST_STALE_RECORD_KEY",))})
-    monkeypatch.setattr("hermes_cli.config.is_managed", lambda: False)
-    monkeypatch.setattr(
-        "hermes_cli.credential_lifecycle.save_provider_env_credential", Mock())
-    monkeypatch.setattr(server, "_model_picker_context", Mock(return_value=object()))
-    monkeypatch.setattr(
-        "hermes_cli.inventory.build_models_payload",
-        Mock(return_value={"providers": [{"slug": "test-provider", "models": [], "total_models": 0}]}))
-
-    try:
-        resp = server._methods["model.save_key"](
-            104, {"slug": "test-provider", "api_key": "k-1"})
-
-        assert "result" in resp, resp
-        assert retried and retried[0].get("force") is True
-    finally:
-        fb.reset_for_tests()
-
-
-def test_model_save_key_leaves_a_profile_scoped_record_alone(monkeypatch):
-    """The record belongs to the launch profile; a profile-scoped save must not
-    rewrite it with another home's inventory."""
-    from hermes_cli import free_tier_bootstrap as fb
-
-    fb.reset_for_tests()
-    with fb._lock:
-        fb._record = fb.SetupRecord(
-            provider_configured=False, inference_provider="", free_tier=False,
-            has_identity=False, other_providers=False)
-        fb._started = True
-        fb._done.set()
-    retried = []
-    monkeypatch.setattr(fb, "retry_bootstrap_mint", lambda **kw: retried.append(kw))
-    monkeypatch.setattr(
-        "hermes_cli.auth.PROVIDER_REGISTRY",
-        {"test-provider": types.SimpleNamespace(
-            name="Test Provider", auth_type="api_key",
-            api_key_env_vars=("TEST_PROFILE_SCOPE_KEY",))})
-    monkeypatch.setattr("hermes_cli.config.is_managed", lambda: False)
-    monkeypatch.setattr(
-        "hermes_cli.credential_lifecycle.save_provider_env_credential", Mock())
-    monkeypatch.setattr(server, "_model_picker_context", Mock(return_value=object()))
-    monkeypatch.setattr(
-        "hermes_cli.inventory.build_models_payload",
-        Mock(return_value={"providers": [{"slug": "test-provider", "models": [], "total_models": 0}]}))
-
-    try:
-        resp = server._methods["model.save_key"](
-            105, {"slug": "test-provider", "api_key": "k-2", "profile": "other"})
-
-        assert "result" in resp, resp
-        assert retried == []
-    finally:
-        fb.reset_for_tests()
-
-
 # ---------------------------------------------------------------------------
 # prompt.submit — auto-title
 # ---------------------------------------------------------------------------
diff --git a/tui_gateway/methods_complete.py b/tui_gateway/methods_complete.py
index 822b01c8c0..a917d69844 100644
--- a/tui_gateway/methods_complete.py
+++ b/tui_gateway/methods_complete.py
@@ -360,11 +360,11 @@ def _(rid, params: dict) -> dict:
     from hermes_cli.credential_lifecycle import save_provider_env_credential  # also rotates stale config.yaml mirrors
     save_provider_env_credential(env_var, api_key)
     os.environ[env_var] = api_key  # so the refreshed inventory sees it
-    # The record may still say "nothing configured" from a failed boot-time mint; a
-    # fresh key must move setup.status (and the setup.ready listeners) with it.
-    from hermes_cli import free_tier_bootstrap
-    if free_tier_bootstrap.current_record() is not None and not params.get("profile"):
-        free_tier_bootstrap.retry_bootstrap_mint(force=True)
+    # The launch profile's boot record may still say "nothing configured"; the gated picker's
+    # own chat waits on setup.status, so the fresh key must move the record (+ setup.ready).
+    if not params.get("profile"):
+        from hermes_cli.free_tier_bootstrap import reconcile_record
+        reconcile_record()
     # Shared inventory builder (lock-step with model.options / dashboard); picker_hints carries `authenticated`.
     from hermes_cli.inventory import build_models_payload
     payload = build_models_payload(_model_picker_context(_session_agent(params)), picker_hints=True, max_models=50)
diff --git a/tui_gateway/methods_config.py b/tui_gateway/methods_config.py
index c0ed508659..5dd1df090a 100644
--- a/tui_gateway/methods_config.py
+++ b/tui_gateway/methods_config.py
@@ -271,7 +271,10 @@ def _(rid, params: dict) -> dict:
 
     For the launch profile the answer is the boot bootstrap's record (``free_tier_bootstrap``):
     the call blocks up to ``SETUP_READY_WAIT_SECONDS`` for it, so a client's first poll lands after
-    the free-tier identity exists (or has been refused) rather than racing the mint. If the record
+    the free-tier identity exists (or has been refused) rather than racing the mint. A record that
+    says ``False`` is reconciled with the config files first (``reconcile_record``): a provider
+    added after boot — the Models page, a picker key, ``hermes setup`` from a shell — flips it
+    without a restart. If the record
     is still missing after the wait, or a named profile is asked about, today's live probe answers.
     The record's fields ride along additively (``ready``, ``free_tier``, ``other_providers``)."""
     try:
diff --git a/tui_gateway/methods_config_set.py b/tui_gateway/methods_config_set.py
index 4e89aa0806..583112df83 100644
--- a/tui_gateway/methods_config_set.py
+++ b/tui_gateway/methods_config_set.py
@@ -147,8 +147,11 @@ def _set_model(rid, params, key, value, session):
         if parse_model_switch_args(str(value)).is_once:
             result = _apply_model_switch("", {"agent": None}, value, confirm_expensive_model=confirmed)
         else:
-            return _err(rid, 4001, "config.set model requires a live session; "
-                        "use Settings -> Models to change the profile default")
+            # One string for every client: the Ink TUI (dashboard /chat, `hermes --tui`) has no
+            # Settings; the dashboard has a Models page; only the Desktop has Settings -> Models.
+            return _err(rid, 4001, "config.set model requires a live session; to change the "
+                        "profile default run /setup, or use the Models page (dashboard) / "
+                        "Settings -> Models (Desktop)")
     return _kv(rid, key, result["value"], warning=result["warning"],
                confirm_required=result.get("confirm_required", False),
                confirm_message=result.get("confirm_message", ""), scope=result.get("scope", "session"))
diff --git a/ui-tui/src/content/setup.ts b/ui-tui/src/content/setup.ts
index 49dd9aa247..24a25284f3 100644
--- a/ui-tui/src/content/setup.ts
+++ b/ui-tui/src/content/setup.ts
@@ -8,10 +8,13 @@ export const buildSetupRequiredSections = (): PanelSection[] => [
   },
   {
     rows: [
-      ['/model', 'configure provider + model in-place'],
-      ['/setup', 'run full first-time setup wizard in-place'],
+      ['/setup', 'run the first-time setup wizard in-place (adds a provider)'],
+      ['/model', 'pick a model (needs a session — add a provider first)'],
       ['Ctrl+C', 'exit and run `hermes setup` manually']
     ],
     title: 'Actions'
+  },
+  {
+    text: 'In the dashboard the Models page sets the profile default; on Desktop it is Settings -> Models.'
   }
 ]

From b9629c298ef554d2669018240f978b8a0f8c53d5 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 04:24:47 -0700
Subject: [PATCH 048/190] fix(setup): reconcile_record() only reconciles the
 launch profile's record

A dashboard write scoped to another profile (POST /api/model/set ?profile=B
runs inside _profile_scope(B)) reached reconcile_record() unconditionally, so
_config_stamp()/_inventory_other_providers() resolved B's home and B's provider
flipped the LAUNCH profile's record to provider_configured=True with a
setup.ready broadcast. Bail out when get_hermes_home() is not the process
home; the negative case is added to the surface test, and the model.save_key
hook is now pinned by its own test.
---
 hermes_cli/free_tier_bootstrap.py             |  9 +++--
 .../test_resolve_provider_custom_endpoint.py  | 12 +++++++
 tests/tui_gateway/test_tui_gateway_server.py  | 34 +++++++++++++++++++
 3 files changed, 53 insertions(+), 2 deletions(-)

diff --git a/hermes_cli/free_tier_bootstrap.py b/hermes_cli/free_tier_bootstrap.py
index 0274ca9f29..5ccdba1ca8 100644
--- a/hermes_cli/free_tier_bootstrap.py
+++ b/hermes_cli/free_tier_bootstrap.py
@@ -90,10 +90,15 @@ def reconcile_record() -> Optional[SetupRecord]:
     and its retries mint. A record that already says ``True`` is never re-probed, so the answer
     only moves false -> true here. Every write path that assigns the main model (the Models page,
     a picker key save) calls this for the immediate broadcast; ``setup.status`` calls it for
-    writes this process never saw (``hermes setup`` / ``hermes model`` from a shell, a hand edit)."""
+    writes this process never saw (``hermes setup`` / ``hermes model`` from a shell, a hand edit).
+    The record is the LAUNCH profile's: a call scoped to another profile's home (a dashboard
+    write with ``?profile=B``) leaves it alone, or B's providers would open the launch gate."""
     global _record
     record = _record
-    if record is None or record.provider_configured or _inventory_stamp == _config_stamp():
+    if record is None or record.provider_configured:
+        return record
+    from hermes_constants import get_process_hermes_home, hermes_home_key
+    if hermes_home_key() != hermes_home_key(get_process_hermes_home()) or _inventory_stamp == _config_stamp():
         return record
     if not _inventory_other_providers():
         return _record
diff --git a/tests/hermes_cli/test_resolve_provider_custom_endpoint.py b/tests/hermes_cli/test_resolve_provider_custom_endpoint.py
index 2c9c03b359..7b228ad618 100644
--- a/tests/hermes_cli/test_resolve_provider_custom_endpoint.py
+++ b/tests/hermes_cli/test_resolve_provider_custom_endpoint.py
@@ -106,6 +106,18 @@ def test_a_provider_configured_after_boot_flips_the_stale_setup_record(isolated_
     assert boot.provider_configured is False
     assert fb.wait_for_record(timeout=0) is boot and broadcasts == [], "blank machine: nothing to reconcile"
 
+    # The record is the launch profile's: a write scoped to another profile (the dashboard's
+    # ``?profile=b``) must not let THAT profile's provider open the launch gate.
+    from hermes_constants import reset_hermes_home_override, set_hermes_home_override
+    profile_b = isolated_home / "profiles" / "b"
+    profile_b.mkdir(parents=True)
+    (profile_b / "config.yaml").write_text("model:\n  default: qwen3\n  provider: custom\n  base_url: http://127.0.0.1:8000/v1\n  api_key: dummy\n", encoding="utf-8")
+    token = set_hermes_home_override(str(profile_b))
+    try:
+        assert fb.reconcile_record() is boot and broadcasts == [], "another profile's provider is not ours"
+    finally:
+        reset_hermes_home_override(token)
+
     (isolated_home / "config.yaml").write_text(
         "model:\n  default: qwen3\n  provider: custom\n  base_url: http://127.0.0.1:8000/v1\n  api_key: dummy\n",
         encoding="utf-8",
diff --git a/tests/tui_gateway/test_tui_gateway_server.py b/tests/tui_gateway/test_tui_gateway_server.py
index fea556633a..42d2de3c2b 100644
--- a/tests/tui_gateway/test_tui_gateway_server.py
+++ b/tests/tui_gateway/test_tui_gateway_server.py
@@ -16968,6 +16968,40 @@ def test_model_save_key_uses_credential_lifecycle_and_picker_context(monkeypatch
     )
 
 
+def test_model_save_key_reconciles_the_launch_profiles_stale_setup_record(monkeypatch):
+    """The gated picker's own chat waits on ``setup.status``, which answers from the boot record:
+    a key saved for the launch profile must flip a ``False`` record (+ ``setup.ready``) at once;
+    a key saved for another profile (``profile`` param) must leave the launch record alone."""
+    from hermes_cli import free_tier_bootstrap as fb
+
+    monkeypatch.setattr("hermes_cli.auth.PROVIDER_REGISTRY", {"test-provider": types.SimpleNamespace(
+        name="Test Provider", auth_type="api_key", api_key_env_vars=("TEST_PROVIDER_API_KEY",))})
+    monkeypatch.setattr("hermes_cli.config.is_managed", lambda: False)
+    monkeypatch.setattr("hermes_cli.credential_lifecycle.save_provider_env_credential", Mock())
+    monkeypatch.setattr("hermes_cli.inventory.build_models_payload", Mock(return_value={"providers": []}))
+    monkeypatch.setenv("TEST_PROVIDER_API_KEY", "previous-value")  # save_key exports the new key
+    monkeypatch.setattr(fb, "_inventory_other_providers", lambda: True)
+    monkeypatch.setattr(fb, "_resolve_inference", lambda: "test-provider")
+    broadcasts = []
+    monkeypatch.setattr(fb, "_broadcast", broadcasts.append)
+    fb.reset_for_tests()
+    stale = fb.SetupRecord(provider_configured=False, inference_provider="", free_tier=False,
+                           has_identity=False, other_providers=False)
+    with fb._lock:
+        fb._record, fb._started = stale, True
+        fb._done.set()
+    try:
+        params = {"slug": "test-provider", "api_key": "k-" + "1"}
+        assert "result" in server._methods["model.save_key"](104, {**params, "profile": "other"})
+        assert fb.current_record() is stale and broadcasts == [], "another profile's key is not ours"
+        assert "result" in server._methods["model.save_key"](105, params)
+        record = fb.current_record()
+        assert record.provider_configured is True and record.inference_provider == "test-provider"
+        assert broadcasts == [record]
+    finally:
+        fb.reset_for_tests()
+
+
 # ---------------------------------------------------------------------------
 # prompt.submit — auto-title
 # ---------------------------------------------------------------------------

From 7a468192491a23cdc4818db873ae70c568454703 Mon Sep 17 00:00:00 2001
From: David Metcalfe <80915+DavidMetcalfe@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:02:44 +0530
Subject: [PATCH 049/190] fix(desktop): stop the sidebar drag sensor from
 swallowing Space in text inputs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The session and project row shells spread the FULL dnd-kit handle
({...attributes, ...listeners}) and then forwarded onPointerDown again by
hand. The spread put dnd-kit's keyboard activator (and role/tabIndex) on the
whole row, so Space/Enter on any focused control inside it — the ⋯ menu
button that opens Rename — started a keyboard drag, and an armed
KeyboardSensor then consumed the next Space at window level: the rename
dialog's input dropped the keystroke (#83617).

Drop the spread. The explicit onPointerDown already forwards the pointer
activator, and the grabber keeps the full handle so keyboard reorder stays
accessible.

Salvaged from #83618 (minimal slice of the shell/grabber split).
---
 .../desktop/src/app/chat/sidebar/projects/overview-row.tsx | 4 ++--
 apps/desktop/src/app/chat/sidebar/session-row.tsx          | 7 ++++++-
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/apps/desktop/src/app/chat/sidebar/projects/overview-row.tsx b/apps/desktop/src/app/chat/sidebar/projects/overview-row.tsx
index 3e8c5f4e9b..a8f736c158 100644
--- a/apps/desktop/src/app/chat/sidebar/projects/overview-row.tsx
+++ b/apps/desktop/src/app/chat/sidebar/projects/overview-row.tsx
@@ -225,8 +225,8 @@ export function ProjectOverviewRow({
       // The label is grab surface too, not just the lead's grabber — same
       // listeners, minus the controls that keep their own gestures. A project
       // row has no rival drag (its title navigates on CLICK), so the sortable
-      // owns the press outright.
-      {...dragHandleProps}
+      // owns the press outright. Pointer activator only — the keyboard
+      // activator stays on the grabber (#83617).
       onPointerDown={event => {
         if ((event.target as HTMLElement).closest('[data-reorder-handle], [data-row-actions]')) {
           return
diff --git a/apps/desktop/src/app/chat/sidebar/session-row.tsx b/apps/desktop/src/app/chat/sidebar/session-row.tsx
index 7ef1a09d14..9f9b4abc2f 100644
--- a/apps/desktop/src/app/chat/sidebar/session-row.tsx
+++ b/apps/desktop/src/app/chat/sidebar/session-row.tsx
@@ -377,7 +377,12 @@ function SidebarSessionRowImpl({
         // target (the session drop denies: side chrome hosts no main tile);
         // over the tree only the session drop does (no sortable row there).
         // Whichever one the release lands on is the one that commits.
-        {...dragHandleProps}
+        //
+        // Only the POINTER activator reaches the shell. The full handle
+        // (role/tabIndex + dnd-kit's keyboard activator) lives on the grabber:
+        // spread here it made every focused row control a keyboard drag
+        // activator, and an armed KeyboardSensor eats Space/Enter window-wide
+        // (#83617: the rename dialog swallowed spaces).
         onPointerDown={event => {
           // The grabber already carries these same listeners, and the ⋯
           // cluster keeps its own gestures.

From 5d59a43593e7349b0dd480d8648361ca9d036817 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:07:10 +0530
Subject: [PATCH 050/190] test(desktop): pin that Space on a row control never
 arms a sidebar reorder drag
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Renders the real SidebarSessionRow inside ReorderableList with the sidebar's
own sensor set. Space on the focused ⋯ button must pass through (not
defaultPrevented, no aria-pressed grabber); the grabber itself still starts a
keyboard reorder. Red on origin/main (the shell spread the keyboard
activator), green with the fix. Regression for #83617.
---
 .../src/app/chat/sidebar/session-row.test.tsx | 67 +++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/apps/desktop/src/app/chat/sidebar/session-row.test.tsx b/apps/desktop/src/app/chat/sidebar/session-row.test.tsx
index 932a8070c9..2fe55edeb0 100644
--- a/apps/desktop/src/app/chat/sidebar/session-row.test.tsx
+++ b/apps/desktop/src/app/chat/sidebar/session-row.test.tsx
@@ -1,3 +1,5 @@
+import { KeyboardSensor, PointerSensor, useSensor, useSensors } from '@dnd-kit/core'
+import { sortableKeyboardCoordinates } from '@dnd-kit/sortable'
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { atom } from 'nanostores'
 import type * as React from 'react'
@@ -13,6 +15,7 @@ import { clearAllSessionStates, publishSessionState } from '@/store/session-stat
 import type * as SessionStatesStore from '@/store/session-states'
 import type * as WindowsStore from '@/store/windows'
 
+import { ReorderableList, useSortableBindings } from './reorderable-list'
 import { SidebarSessionRow } from './session-row'
 
 afterEach(cleanup)
@@ -439,3 +442,67 @@ describe('Inbox-style session card', () => {
     expect(screen.getByText('133 messages')).toBeTruthy()
   })
 })
+
+// Regression for #83617: the row shell once spread the FULL dnd-kit handle, so
+// Space on a focused control inside the row (the ⋯ button that opens Rename)
+// reached the KeyboardSensor's activator — a drag armed, and the sensor then
+// ate the next Space at window level (the rename input dropped the keystroke).
+describe('SidebarSessionRow inside the sortable list', () => {
+  function SortableRow({ session }: { session: SessionInfo }) {
+    const { dragHandleProps, dragging, ref, reorderable, style } = useSortableBindings(session.id)
+
+    return (
+      <SidebarSessionRow
+        dragging={dragging}
+        dragHandleProps={dragHandleProps}
+        isPinned={false}
+        isSelected={false}
+        onArchive={noop}
+        onDelete={noop}
+        onPin={noop}
+        onResume={noop}
+        onToggleUnread={noop}
+        ref={ref}
+        reorderable={reorderable}
+        session={session}
+        style={style}
+        unread={false}
+      />
+    )
+  }
+
+  function Host({ session }: { session: SessionInfo }) {
+    // The sidebar's own sensor set (index.tsx dndSensors).
+    const sensors = useSensors(
+      useSensor(PointerSensor, { activationConstraint: { distance: 6 } }),
+      useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates })
+    )
+
+    return (
+      <ReorderableList ids={[session.id]} onReorder={noop} sensors={sensors}>
+        <SortableRow session={session} />
+      </ReorderableList>
+    )
+  }
+
+  const space = { code: 'Space', key: ' ' }
+
+  it('lets Space through to a focused row control instead of arming a keyboard drag', () => {
+    const { container } = render(<Host session={makeSession({ title: 'Renamable' })} />)
+    const kebab = screen.getByRole('button', { name: 'Session actions' })
+    kebab.focus()
+
+    // Not defaultPrevented: dnd-kit's activator never saw it.
+    expect(fireEvent.keyDown(kebab, space)).toBe(true)
+    expect(container.querySelector('[aria-pressed="true"]')).toBeNull()
+  })
+
+  it('still starts a keyboard reorder from the grabber', () => {
+    const { container } = render(<Host session={makeSession({ title: 'Renamable' })} />)
+    const grabber = container.querySelector<HTMLElement>('[data-reorder-handle]')!
+
+    grabber.focus()
+    fireEvent.keyDown(grabber, space)
+    expect(grabber.getAttribute('aria-pressed')).toBe('true')
+  })
+})

From 15a256293d1484b79594aad0ad488ba377779601 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:46:23 +0530
Subject: [PATCH 051/190] fix(desktop): gateway/profile group headers take the
 pointer activator only
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Same defect class as the session and project rows: the group header spread
the full dnd-kit handle, so Space on its ⋯ button (which opens a rename
dialog) armed a keyboard reorder and the sensor ate the next Space in the
dialog input. Keep the explicit onPointerDown forwarder — a press on the
label still starts the reorder, which the header test now proves through the
pointer path — and move the keyboard reorder assertion onto the grabber,
where the keyboard activator lives.
---
 .../chat/sidebar/gateway-groups-drag.test.tsx | 49 ++++++++++++++-----
 .../src/app/chat/sidebar/gateway-groups.tsx   |  6 ++-
 .../src/app/chat/sidebar/session-row.test.tsx |  3 +-
 3 files changed, 43 insertions(+), 15 deletions(-)

diff --git a/apps/desktop/src/app/chat/sidebar/gateway-groups-drag.test.tsx b/apps/desktop/src/app/chat/sidebar/gateway-groups-drag.test.tsx
index 68dc2e85e7..bfaaf4dfbf 100644
--- a/apps/desktop/src/app/chat/sidebar/gateway-groups-drag.test.tsx
+++ b/apps/desktop/src/app/chat/sidebar/gateway-groups-drag.test.tsx
@@ -16,9 +16,11 @@ import { ChatSidebar } from './index'
 
 // Gateway/profile groups reorder by drag as well as by the ⋯ menu's Move
 // up/down. The grab handle only reveals itself on hover, so the visible
-// affordance is the header itself: a press on the label must arm the dnd
-// sortable (the lead handle already did). Proven red on the version where only
-// the handle carried the listeners.
+// affordance is the header itself: a POINTER press on the label must arm the
+// dnd sortable (the lead handle already did). Only the pointer activator lives
+// on the header, though — the keyboard activator stays on the grabber, or
+// Space on the ⋯ button would arm a reorder and swallow the next Space in the
+// rename dialog (#83617).
 
 const noop = () => {}
 
@@ -48,7 +50,7 @@ afterEach(() => {
   $gatewayGroupOrder.set([])
 })
 
-it('reorders gateway sections by dragging the header label, not only the grab handle', async () => {
+const arrange = () => {
   mount()
   act(() => {
     $connectionsRegistry.set({
@@ -75,22 +77,45 @@ it('reorders gateway sections by dragging the header label, not only the grab ha
   const device = screen.getByText('This device').closest('[data-gateway-section]') as HTMLElement
   expect(sectionIds()).toEqual([JSON.stringify(['gateway', 'remote-1']), JSON.stringify(['gateway', 'local'])])
 
-  // dnd-kit's KeyboardSensor: Space on the focused sortable arms the drag,
-  // ArrowUp moves it over the previous item, Space drops. Drives the same
-  // listeners the pointer path binds, without needing layout in jsdom.
-  // The fold link, not the row (which dnd-kit also names as a sortable button).
+  return { device, sectionIds }
+}
+
+it('arms the reorder from a pointer press on the header label', async () => {
+  const { device } = arrange()
+  // Pointer path: a press on the fold label plus a move past the 6px
+  // activation distance arms the sortable (jsdom has no layout, so the drop
+  // itself cannot resolve a target here — arming is the assertion).
   const label = within(device).getByRole('button', { expanded: true, name: 'This device' })
-  label.focus()
   await act(async () => {
-    fireEvent.keyDown(label, { code: 'Space', key: ' ' })
+    fireEvent.pointerDown(label, { button: 0, clientX: 10, clientY: 10, isPrimary: true, pointerId: 1 })
+    fireEvent.pointerMove(document, { clientX: 10, clientY: 30, pointerId: 1 })
+    await Promise.resolve()
+  })
+  expect(device.querySelector('[data-glass-opaque]')).not.toBeNull()
+  await act(async () => {
+    fireEvent.pointerUp(document, { clientX: 10, clientY: 30, pointerId: 1 })
+    await Promise.resolve()
+  })
+  expect(device.querySelector('[data-glass-opaque]')).toBeNull()
+})
+
+it('reorders gateway sections from the grabber by keyboard', async () => {
+  const { device, sectionIds } = arrange()
+  // Keyboard path: Space on the focused grabber arms the drag, ArrowUp moves it
+  // over the previous item, Space drops. Drives the same listeners without
+  // needing layout in jsdom.
+  const grabber = device.querySelector<HTMLElement>('[data-reorder-handle]')!
+  grabber.focus()
+  await act(async () => {
+    fireEvent.keyDown(grabber, { code: 'Space', key: ' ' })
     await Promise.resolve()
   })
   await act(async () => {
-    fireEvent.keyDown(label, { code: 'ArrowUp', key: 'ArrowUp' })
+    fireEvent.keyDown(grabber, { code: 'ArrowUp', key: 'ArrowUp' })
     await Promise.resolve()
   })
   await act(async () => {
-    fireEvent.keyDown(label, { code: 'Space', key: ' ' })
+    fireEvent.keyDown(grabber, { code: 'Space', key: ' ' })
     await Promise.resolve()
   })
 
diff --git a/apps/desktop/src/app/chat/sidebar/gateway-groups.tsx b/apps/desktop/src/app/chat/sidebar/gateway-groups.tsx
index 331d43ef67..592e983a62 100644
--- a/apps/desktop/src/app/chat/sidebar/gateway-groups.tsx
+++ b/apps/desktop/src/app/chat/sidebar/gateway-groups.tsx
@@ -192,8 +192,10 @@ function GatewayProfileGroup({
         // glyph only reveals its grabber on hover, so a press anywhere on the
         // row must start the reorder too. The ⋯/caret cluster and the handle
         // keep their own gestures; a sub-threshold press on the label is still
-        // the click that folds the group.
-        {...sortable.dragHandleProps}
+        // the click that folds the group. Pointer activator only (forwarded
+        // below): the keyboard activator stays on the grabber, or Space on the
+        // ⋯ button would arm a reorder and swallow the next Space in the
+        // rename dialog (#83617).
         actions={
           <div className="flex items-center">
             {group.profile && (
diff --git a/apps/desktop/src/app/chat/sidebar/session-row.test.tsx b/apps/desktop/src/app/chat/sidebar/session-row.test.tsx
index 2fe55edeb0..db1a23af9a 100644
--- a/apps/desktop/src/app/chat/sidebar/session-row.test.tsx
+++ b/apps/desktop/src/app/chat/sidebar/session-row.test.tsx
@@ -492,7 +492,8 @@ describe('SidebarSessionRow inside the sortable list', () => {
     const kebab = screen.getByRole('button', { name: 'Session actions' })
     kebab.focus()
 
-    // Not defaultPrevented: dnd-kit's activator never saw it.
+    // Not defaultPrevented (the ⋯ menu is stubbed in this file, so only
+    // dnd-kit could have claimed the key) and no grabber reports a drag.
     expect(fireEvent.keyDown(kebab, space)).toBe(true)
     expect(container.querySelector('[aria-pressed="true"]')).toBeNull()
   })

From 61134dbcde940c9346908c404ed63363af867ffc Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 01:01:36 +0530
Subject: [PATCH 052/190] refactor(desktop): state the shell/grabber handle
 split once, at useSortableBindings

The mechanism is a property of the dnd-kit handle, not of any one row; the
three shells now point at the one explanation instead of repeating it.
---
 .../src/app/chat/sidebar/gateway-groups-drag.test.tsx  |  4 +---
 apps/desktop/src/app/chat/sidebar/gateway-groups.tsx   |  4 +---
 .../src/app/chat/sidebar/projects/overview-row.tsx     | 10 +++++-----
 apps/desktop/src/app/chat/sidebar/reorderable-list.tsx |  6 ++++++
 apps/desktop/src/app/chat/sidebar/session-row.tsx      | 10 +++-------
 5 files changed, 16 insertions(+), 18 deletions(-)

diff --git a/apps/desktop/src/app/chat/sidebar/gateway-groups-drag.test.tsx b/apps/desktop/src/app/chat/sidebar/gateway-groups-drag.test.tsx
index bfaaf4dfbf..a652c69991 100644
--- a/apps/desktop/src/app/chat/sidebar/gateway-groups-drag.test.tsx
+++ b/apps/desktop/src/app/chat/sidebar/gateway-groups-drag.test.tsx
@@ -18,9 +18,7 @@ import { ChatSidebar } from './index'
 // up/down. The grab handle only reveals itself on hover, so the visible
 // affordance is the header itself: a POINTER press on the label must arm the
 // dnd sortable (the lead handle already did). Only the pointer activator lives
-// on the header, though — the keyboard activator stays on the grabber, or
-// Space on the ⋯ button would arm a reorder and swallow the next Space in the
-// rename dialog (#83617).
+// on the header; the keyboard activator stays on the grabber (#83617).
 
 const noop = () => {}
 
diff --git a/apps/desktop/src/app/chat/sidebar/gateway-groups.tsx b/apps/desktop/src/app/chat/sidebar/gateway-groups.tsx
index 592e983a62..c108523841 100644
--- a/apps/desktop/src/app/chat/sidebar/gateway-groups.tsx
+++ b/apps/desktop/src/app/chat/sidebar/gateway-groups.tsx
@@ -193,9 +193,7 @@ function GatewayProfileGroup({
         // row must start the reorder too. The ⋯/caret cluster and the handle
         // keep their own gestures; a sub-threshold press on the label is still
         // the click that folds the group. Pointer activator only (forwarded
-        // below): the keyboard activator stays on the grabber, or Space on the
-        // ⋯ button would arm a reorder and swallow the next Space in the
-        // rename dialog (#83617).
+        // below); the full handle stays on the grabber (see useSortableBindings).
         actions={
           <div className="flex items-center">
             {group.profile && (
diff --git a/apps/desktop/src/app/chat/sidebar/projects/overview-row.tsx b/apps/desktop/src/app/chat/sidebar/projects/overview-row.tsx
index a8f736c158..ba4a6197f5 100644
--- a/apps/desktop/src/app/chat/sidebar/projects/overview-row.tsx
+++ b/apps/desktop/src/app/chat/sidebar/projects/overview-row.tsx
@@ -222,11 +222,11 @@ export function ProjectOverviewRow({
       data-glass-opaque={dragging ? '' : undefined}
       label={project.isAuto ? <Tip label={s.projects.autoDiscovered}>{labelLink}</Tip> : labelLink}
       lead={lead}
-      // The label is grab surface too, not just the lead's grabber — same
-      // listeners, minus the controls that keep their own gestures. A project
-      // row has no rival drag (its title navigates on CLICK), so the sortable
-      // owns the press outright. Pointer activator only — the keyboard
-      // activator stays on the grabber (#83617).
+      // The label is grab surface too, not just the lead's grabber — the
+      // pointer activator only (the full handle stays on the grabber, see
+      // useSortableBindings), minus the controls that keep their own gestures.
+      // A project row has no rival drag (its title navigates on CLICK), so the
+      // sortable owns the press outright.
       onPointerDown={event => {
         if ((event.target as HTMLElement).closest('[data-reorder-handle], [data-row-actions]')) {
           return
diff --git a/apps/desktop/src/app/chat/sidebar/reorderable-list.tsx b/apps/desktop/src/app/chat/sidebar/reorderable-list.tsx
index 62d1ed1cda..29c25ca783 100644
--- a/apps/desktop/src/app/chat/sidebar/reorderable-list.tsx
+++ b/apps/desktop/src/app/chat/sidebar/reorderable-list.tsx
@@ -63,6 +63,12 @@ export function ReorderableList({
 
 export function useSortableBindings(id: string) {
   const { attributes, isDragging, listeners, setNodeRef, transform, transition } = useSortable({ id })
+  // The FULL handle (role/tabIndex + dnd-kit's keyboard and pointer
+  // activators) belongs on the grabber only. Row shells forward just
+  // `onPointerDown` from it: a keyboard activator on a container makes every
+  // focused descendant control (the ⋯ menu button) arm a drag on Space, and
+  // an armed KeyboardSensor then eats Space/Enter window-wide — the rename
+  // dialog swallowed spaces (#83617).
   const dragHandleProps: React.HTMLAttributes<HTMLElement> = { ...attributes, ...listeners }
 
   return {
diff --git a/apps/desktop/src/app/chat/sidebar/session-row.tsx b/apps/desktop/src/app/chat/sidebar/session-row.tsx
index 9f9b4abc2f..f627833ca6 100644
--- a/apps/desktop/src/app/chat/sidebar/session-row.tsx
+++ b/apps/desktop/src/app/chat/sidebar/session-row.tsx
@@ -376,13 +376,9 @@ function SidebarSessionRowImpl({
         // steal the other's gesture. Over the sidebar only the reorder has a
         // target (the session drop denies: side chrome hosts no main tile);
         // over the tree only the session drop does (no sortable row there).
-        // Whichever one the release lands on is the one that commits.
-        //
-        // Only the POINTER activator reaches the shell. The full handle
-        // (role/tabIndex + dnd-kit's keyboard activator) lives on the grabber:
-        // spread here it made every focused row control a keyboard drag
-        // activator, and an armed KeyboardSensor eats Space/Enter window-wide
-        // (#83617: the rename dialog swallowed spaces).
+        // Whichever one the release lands on is the one that commits. Pointer
+        // activator only; the full handle stays on the grabber (see
+        // useSortableBindings).
         onPointerDown={event => {
           // The grabber already carries these same listeners, and the ⋯
           // cluster keeps its own gestures.

From 8a2186ffec83fb756de2d1ffc278a408ba22aca0 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Fri, 18 Sep 2026 23:28:46 +0530
Subject: [PATCH 053/190] chore: map c0debyeric contributor email for the
 #107472 salvage

---
 contributors/emails/github@eric-n.com | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 contributors/emails/github@eric-n.com

diff --git a/contributors/emails/github@eric-n.com b/contributors/emails/github@eric-n.com
new file mode 100644
index 0000000000..db19ffdc2b
--- /dev/null
+++ b/contributors/emails/github@eric-n.com
@@ -0,0 +1,2 @@
+c0debyeric
+# PR #107472 salvage (bedrock: key streamed blocks by contentBlockIndex; #108200)

From 8b28df7b1fb1ff5d29558ea901f4c7df47c86e5d Mon Sep 17 00:00:00 2001
From: EricN <github@eric-n.com>
Date: Thu, 10 Sep 2026 11:48:37 -0400
Subject: [PATCH 054/190] fix(bedrock): key streamed content blocks by
 contentBlockIndex, not arrival count
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Claude 5 on Bedrock (global.anthropic.claude-opus-5 observed) killed every
tool-continuation turn that followed an assistant reply containing BOTH text
and a tool call:

  ValidationException: This model does not support assistant message prefill.
  The conversation must end with a user message.

The payload did end with a user turn. The rejected shape was the assistant
turn before it, replayed from the bedrock_content_blocks sidecar as

  assistant[text, text, toolUse, text x16, cachePoint]

i.e. the model's text shredded into one block per streamed delta, with the
toolUse spliced into the middle and one fragment missing.

Cause: stream_converse_with_callbacks() only read contentBlockIndex on
contentBlockStart. Bedrock emits NO contentBlockStart for text blocks (only
for toolUse), so current_block_index stayed None and every text delta was
keyed by len(stream_blocks) — a fresh slot per delta. When the toolUse block
then started at its real index it overwrote one text fragment and sorted into
the middle of the text on replay. Claude 5 rejects text trailing a tool_use in
the last assistant turn as prefill; text-only or toolUse-only replies were
unaffected, which is why the failure looked intermittent. The joined
`content` string was correct, so the transcript looked fine while the wire
payload was not.

Fix: read contentBlockIndex off every contentBlockStart/Delta/Stop and key
stream_blocks by it, so all deltas of a block merge into one entry and blocks
keep Bedrock's order. Events without an index (test doubles, proxies) fall
back to arrival order: a start opens a new slot, a delta/stop continues the
current one.

Verified against Bedrock: replaying the dumped failing request reproduces the
400; the same request with the assistant text ahead of the toolUse (merged or
still fragmented) is accepted; dropping only the cachePoint still fails, so
caching is not involved. The added tests use the captured live event sequence
and fail on main.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 agent/bedrock_adapter.py            | 38 ++++++++++++++-------
 tests/agent/test_bedrock_adapter.py | 52 +++++++++++++++++++++++++++++
 2 files changed, 78 insertions(+), 12 deletions(-)

diff --git a/agent/bedrock_adapter.py b/agent/bedrock_adapter.py
index 485626a31a..1ad259b231 100644
--- a/agent/bedrock_adapter.py
+++ b/agent/bedrock_adapter.py
@@ -813,7 +813,13 @@ def stream_converse_with_callbacks(
     """boto3 ``converse_stream()`` response + callbacks → the ``normalize_converse_response()`` shape.
     ``on_text_delta`` only fires while no toolUse block has been seen (as on the Anthropic/chat_completions
     paths); ``on_interrupt_check`` True stops streaming; ``on_event`` fires for EVERY event before branching
-    and its exceptions are swallowed so a watchdog hook can never abort the stream."""
+    and its exceptions are swallowed so a watchdog hook can never abort the stream.
+
+    Blocks are keyed by the ``contentBlockIndex`` Bedrock stamps on every contentBlockStart/Delta/Stop.
+    Text blocks get NO contentBlockStart on the wire (only toolUse does), so the index has to be read off
+    the deltas themselves: keying text by a running counter shreds one text block into one block per delta,
+    lets the later toolUse start overwrite one fragment and sort into the middle of the text, and that
+    ``[text, toolUse, text...]`` replay is rejected by Claude as assistant prefill on the next turn."""
     parts = _ResponseParts()
     stream_blocks: Dict[int, Dict[str, Any]] = {}
     current_block_index: Optional[int] = None
@@ -823,9 +829,15 @@ def stream_converse_with_callbacks(
     stop_reason = "end_turn"
     usage_data: Dict[str, int] = {}
 
-    def current_block(default: Dict[str, Any]) -> Dict[str, Any]:
-        idx = current_block_index if current_block_index is not None else len(stream_blocks)
-        return stream_blocks.setdefault(idx, default)
+    def block_index(payload: Dict[str, Any], *, new_block: bool = False) -> int:
+        """Index of the block a contentBlock* event addresses. Without ``contentBlockIndex`` (test doubles,
+        proxies) a start opens a fresh slot and a delta/stop continues the current one."""
+        nonlocal current_block_index
+        idx = payload.get("contentBlockIndex")
+        if not isinstance(idx, int) or isinstance(idx, bool):
+            idx = len(stream_blocks) if new_block or current_block_index is None else current_block_index
+        current_block_index = idx
+        return idx
 
     def flush_text() -> None:
         if current_text_buffer:
@@ -840,20 +852,22 @@ def stream_converse_with_callbacks(
             break
         if "contentBlockStart" in event:
             start_event = event["contentBlockStart"]
-            current_block_index = start_event.get("contentBlockIndex", len(stream_blocks))
+            idx = block_index(start_event, new_block=True)
             start = start_event.get("start", {})
             if "toolUse" in start:
                 has_tool_use = True
                 flush_text()
                 current_tool = {"toolUseId": start["toolUse"].get("toolUseId", ""), "name": start["toolUse"].get("name", ""), "input_json": ""}
-                stream_blocks[current_block_index] = _tool_use_block(current_tool["toolUseId"], current_tool["name"], {})
+                stream_blocks[idx] = _tool_use_block(current_tool["toolUseId"], current_tool["name"], {})
                 if on_tool_start:
                     on_tool_start(current_tool["name"])
         elif "contentBlockDelta" in event:
-            delta = event["contentBlockDelta"].get("delta", {})
+            delta_event = event["contentBlockDelta"]
+            idx = block_index(delta_event)
+            delta = delta_event.get("delta", {})
             if "text" in delta:
                 text = delta["text"]
-                block = current_block({"text": ""})
+                block = stream_blocks.setdefault(idx, {"text": ""})
                 block["text"] = block.get("text", "") + text
                 current_text_buffer.append(text)
                 if on_text_delta and not has_tool_use:
@@ -863,14 +877,15 @@ def stream_converse_with_callbacks(
             elif "reasoningContent" in delta:
                 reasoning = delta["reasoningContent"]
                 if isinstance(reasoning, dict) and (reasoning.get("text", "") or _encode_redacted(reasoning.get("redactedContent"))):
-                    block = current_block({"reasoningContent": {}}).setdefault("reasoningContent", {})
+                    block = stream_blocks.setdefault(idx, {"reasoningContent": {}}).setdefault("reasoningContent", {})
                     parts.absorb_reasoning(reasoning, block, on_reasoning_delta)
         elif "contentBlockStop" in event:
+            idx = block_index(event["contentBlockStop"])
             if current_tool is not None:
                 input_dict = _parse_tool_args(current_tool["input_json"])  # "" → {} via the JSON-error path
                 parts.tool_calls.append(_tool_call_ns(current_tool["toolUseId"], current_tool["name"], input_dict))
-                if current_block_index is not None and current_block_index in stream_blocks:
-                    stream_blocks[current_block_index]["toolUse"]["input"] = input_dict
+                if "toolUse" in stream_blocks.get(idx, {}):
+                    stream_blocks[idx]["toolUse"]["input"] = input_dict
                 current_tool = None
             else:
                 flush_text()
@@ -882,7 +897,6 @@ def stream_converse_with_callbacks(
     flush_text()
     return parts.build([stream_blocks[i] for i in sorted(stream_blocks)], usage_data, stop_reason, "")
 
-
 # --- High-level API: call Bedrock Converse ---
 
 def build_converse_kwargs(
diff --git a/tests/agent/test_bedrock_adapter.py b/tests/agent/test_bedrock_adapter.py
index a48f9ae82d..aa080412a6 100644
--- a/tests/agent/test_bedrock_adapter.py
+++ b/tests/agent/test_bedrock_adapter.py
@@ -486,6 +486,58 @@ class TestNormalizeConverseStreamEvents:
         assert tc[0].function.name == "read_file"
         assert json.loads(tc[0].function.arguments) == {"path": "/tmp/f"}
 
+    # Real ConverseStream wire shape (captured from global.anthropic.claude-opus-5): a text block gets NO
+    # contentBlockStart, only deltas stamped contentBlockIndex=0; the toolUse block then starts at index 1.
+    _LIVE_TEXT_THEN_TOOL_EVENTS = [
+        {"messageStart": {"role": "assistant"}},
+        {"contentBlockDelta": {"contentBlockIndex": 0, "delta": {"text": "I"}}},
+        {"contentBlockDelta": {"contentBlockIndex": 0, "delta": {"text": "'ll echo "}}},
+        {"contentBlockDelta": {"contentBlockIndex": 0, "delta": {"text": "banana"}}},
+        {"contentBlockDelta": {"contentBlockIndex": 0, "delta": {"text": " now."}}},
+        {"contentBlockStop": {"contentBlockIndex": 0}},
+        {"contentBlockStart": {"contentBlockIndex": 1, "start": {"toolUse": {"toolUseId": "tooluse_1", "name": "echo"}}}},
+        {"contentBlockDelta": {"contentBlockIndex": 1, "delta": {"toolUse": {"input": ""}}}},
+        {"contentBlockDelta": {"contentBlockIndex": 1, "delta": {"toolUse": {"input": '{"s": "banana"}'}}}},
+        {"contentBlockStop": {"contentBlockIndex": 1}},
+        {"messageStop": {"stopReason": "tool_use"}},
+        {"metadata": {"usage": {"inputTokens": 10, "outputTokens": 8}}},
+    ]
+
+    def test_text_deltas_without_content_block_start_stay_one_block_ahead_of_tool_use(self):
+        """Regression: keying text deltas by a running counter instead of their contentBlockIndex shredded
+        the text into one block per delta and let the toolUse start (index 1) overwrite the second fragment
+        and sort into the middle — a ``[text, toolUse, text...]`` sidecar Claude 5 on Bedrock rejects on
+        replay as "does not support assistant message prefill"."""
+        from agent.bedrock_adapter import convert_messages_to_converse, normalize_converse_stream_events
+        result = normalize_converse_stream_events({"stream": list(self._LIVE_TEXT_THEN_TOOL_EVENTS)})
+        msg = result.choices[0].message
+        assert msg.content == "I'll echo banana now."
+        assert msg.bedrock_content_blocks == [
+            {"text": "I'll echo banana now."},
+            {"toolUse": {"toolUseId": "tooluse_1", "name": "echo", "input": {"s": "banana"}}},
+        ]
+        assert [tc.function.name for tc in msg.tool_calls] == ["echo"]
+        # The sidecar is authoritative on replay: the next turn must go out as text THEN toolUse, nothing after.
+        _, converse = convert_messages_to_converse([
+            {"role": "user", "content": "echo banana"},
+            {"role": "assistant", "content": msg.content, "bedrock_content_blocks": msg.bedrock_content_blocks,
+             "tool_calls": [{"id": "tooluse_1", "type": "function", "function": {"name": "echo", "arguments": '{"s": "banana"}'}}]},
+            {"role": "tool", "tool_call_id": "tooluse_1", "content": "banana"},
+        ])
+        assert [list(b)[0] for b in converse[1]["content"]] == ["text", "toolUse"]
+        assert converse[1]["content"][0]["text"] == "I'll echo banana now."
+
+    def test_events_without_content_block_index_fall_back_to_arrival_order(self):
+        """Proxies/test doubles may omit contentBlockIndex: deltas continue the current block, a start opens a
+        new one, so text still lands before the toolUse instead of being overwritten by it."""
+        from agent.bedrock_adapter import normalize_converse_stream_events
+        events = [{k: {kk: vv for kk, vv in v.items() if kk != "contentBlockIndex"} for k, v in e.items()}
+                  for e in self._LIVE_TEXT_THEN_TOOL_EVENTS]
+        msg = normalize_converse_stream_events({"stream": events}).choices[0].message
+        assert msg.content == "I'll echo banana now."
+        assert [list(b)[0] for b in msg.bedrock_content_blocks] == ["text", "toolUse"]
+        assert msg.bedrock_content_blocks[1]["toolUse"]["input"] == {"s": "banana"}
+
 
 # ---------------------------------------------------------------------------
 # build_converse_kwargs

From 5d4a206c92e42fcc4cf0d79cb5b7cde61486d427 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:13:46 +0530
Subject: [PATCH 055/190] fix(bedrock): index-less text after a tool stop opens
 its own block
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

In the arrival-order fallback (events without contentBlockIndex) a text delta
following contentBlockStop still continued the closed tool's slot and bolted a
stray `text` key onto the toolUse dict — the same mixed block the indexed path
just stopped producing, and one `_replay_ordered_blocks` drops the toolUse from.
Clear the current index at every stop so the next index-less delta starts fresh;
the no-index regression now covers text on both sides of the tool.

Also collapses the dead bool guard (boto3 indices are ints) and trims the
docstring to the one-line WHY.
---
 agent/bedrock_adapter.py            | 11 +++++------
 tests/agent/test_bedrock_adapter.py |  9 ++++++---
 2 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/agent/bedrock_adapter.py b/agent/bedrock_adapter.py
index 1ad259b231..3fdf5a92cd 100644
--- a/agent/bedrock_adapter.py
+++ b/agent/bedrock_adapter.py
@@ -815,11 +815,8 @@ def stream_converse_with_callbacks(
     paths); ``on_interrupt_check`` True stops streaming; ``on_event`` fires for EVERY event before branching
     and its exceptions are swallowed so a watchdog hook can never abort the stream.
 
-    Blocks are keyed by the ``contentBlockIndex`` Bedrock stamps on every contentBlockStart/Delta/Stop.
-    Text blocks get NO contentBlockStart on the wire (only toolUse does), so the index has to be read off
-    the deltas themselves: keying text by a running counter shreds one text block into one block per delta,
-    lets the later toolUse start overwrite one fragment and sort into the middle of the text, and that
-    ``[text, toolUse, text...]`` replay is rejected by Claude as assistant prefill on the next turn."""
+    Blocks are keyed by the ``contentBlockIndex`` Bedrock stamps on every contentBlockStart/Delta/Stop:
+    text blocks get NO contentBlockStart, so a counter keyed on starts shredded them (#108200)."""
     parts = _ResponseParts()
     stream_blocks: Dict[int, Dict[str, Any]] = {}
     current_block_index: Optional[int] = None
@@ -834,7 +831,7 @@ def stream_converse_with_callbacks(
         proxies) a start opens a fresh slot and a delta/stop continues the current one."""
         nonlocal current_block_index
         idx = payload.get("contentBlockIndex")
-        if not isinstance(idx, int) or isinstance(idx, bool):
+        if not isinstance(idx, int):
             idx = len(stream_blocks) if new_block or current_block_index is None else current_block_index
         current_block_index = idx
         return idx
@@ -881,6 +878,7 @@ def stream_converse_with_callbacks(
                     parts.absorb_reasoning(reasoning, block, on_reasoning_delta)
         elif "contentBlockStop" in event:
             idx = block_index(event["contentBlockStop"])
+            current_block_index = None  # a following index-less delta opens a fresh slot, not this one
             if current_tool is not None:
                 input_dict = _parse_tool_args(current_tool["input_json"])  # "" → {} via the JSON-error path
                 parts.tool_calls.append(_tool_call_ns(current_tool["toolUseId"], current_tool["name"], input_dict))
@@ -897,6 +895,7 @@ def stream_converse_with_callbacks(
     flush_text()
     return parts.build([stream_blocks[i] for i in sorted(stream_blocks)], usage_data, stop_reason, "")
 
+
 # --- High-level API: call Bedrock Converse ---
 
 def build_converse_kwargs(
diff --git a/tests/agent/test_bedrock_adapter.py b/tests/agent/test_bedrock_adapter.py
index aa080412a6..dfc0481cce 100644
--- a/tests/agent/test_bedrock_adapter.py
+++ b/tests/agent/test_bedrock_adapter.py
@@ -532,10 +532,13 @@ class TestNormalizeConverseStreamEvents:
         new one, so text still lands before the toolUse instead of being overwritten by it."""
         from agent.bedrock_adapter import normalize_converse_stream_events
         events = [{k: {kk: vv for kk, vv in v.items() if kk != "contentBlockIndex"} for k, v in e.items()}
-                  for e in self._LIVE_TEXT_THEN_TOOL_EVENTS]
+                  for e in self._LIVE_TEXT_THEN_TOOL_EVENTS[:-2]]
+        # Text after the tool's stop must open its own slot, not land on the closed tool block.
+        events += [{"contentBlockDelta": {"delta": {"text": "done"}}}, {"contentBlockStop": {}},
+                   {"messageStop": {"stopReason": "tool_use"}}]
         msg = normalize_converse_stream_events({"stream": events}).choices[0].message
-        assert msg.content == "I'll echo banana now."
-        assert [list(b)[0] for b in msg.bedrock_content_blocks] == ["text", "toolUse"]
+        assert msg.content == "I'll echo banana now.\ndone"
+        assert [list(b) for b in msg.bedrock_content_blocks] == [["text"], ["toolUse"], ["text"]]
         assert msg.bedrock_content_blocks[1]["toolUse"]["input"] == {"s": "banana"}
 
 

From e5af917aaad130d2f3c01529e026ca2bfb70fb56 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:36:52 +0530
Subject: [PATCH 056/190] refactor(bedrock): block_index resolves, callers own
 the current-index state
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The helper wrote current_block_index for every event and the stop branch
immediately undid it; make it a pure resolver and assign in the start/delta
branches only. The test's replay tail re-covered ordering the sidecar
assertion already pins — dropped.
---
 agent/bedrock_adapter.py            | 12 +++++-------
 tests/agent/test_bedrock_adapter.py | 11 +----------
 2 files changed, 6 insertions(+), 17 deletions(-)

diff --git a/agent/bedrock_adapter.py b/agent/bedrock_adapter.py
index 3fdf5a92cd..a23b3ec164 100644
--- a/agent/bedrock_adapter.py
+++ b/agent/bedrock_adapter.py
@@ -829,12 +829,10 @@ def stream_converse_with_callbacks(
     def block_index(payload: Dict[str, Any], *, new_block: bool = False) -> int:
         """Index of the block a contentBlock* event addresses. Without ``contentBlockIndex`` (test doubles,
         proxies) a start opens a fresh slot and a delta/stop continues the current one."""
-        nonlocal current_block_index
         idx = payload.get("contentBlockIndex")
-        if not isinstance(idx, int):
-            idx = len(stream_blocks) if new_block or current_block_index is None else current_block_index
-        current_block_index = idx
-        return idx
+        if isinstance(idx, int):
+            return idx
+        return len(stream_blocks) if new_block or current_block_index is None else current_block_index
 
     def flush_text() -> None:
         if current_text_buffer:
@@ -849,7 +847,7 @@ def stream_converse_with_callbacks(
             break
         if "contentBlockStart" in event:
             start_event = event["contentBlockStart"]
-            idx = block_index(start_event, new_block=True)
+            idx = current_block_index = block_index(start_event, new_block=True)
             start = start_event.get("start", {})
             if "toolUse" in start:
                 has_tool_use = True
@@ -860,7 +858,7 @@ def stream_converse_with_callbacks(
                     on_tool_start(current_tool["name"])
         elif "contentBlockDelta" in event:
             delta_event = event["contentBlockDelta"]
-            idx = block_index(delta_event)
+            idx = current_block_index = block_index(delta_event)
             delta = delta_event.get("delta", {})
             if "text" in delta:
                 text = delta["text"]
diff --git a/tests/agent/test_bedrock_adapter.py b/tests/agent/test_bedrock_adapter.py
index dfc0481cce..636f75a612 100644
--- a/tests/agent/test_bedrock_adapter.py
+++ b/tests/agent/test_bedrock_adapter.py
@@ -508,7 +508,7 @@ class TestNormalizeConverseStreamEvents:
         the text into one block per delta and let the toolUse start (index 1) overwrite the second fragment
         and sort into the middle — a ``[text, toolUse, text...]`` sidecar Claude 5 on Bedrock rejects on
         replay as "does not support assistant message prefill"."""
-        from agent.bedrock_adapter import convert_messages_to_converse, normalize_converse_stream_events
+        from agent.bedrock_adapter import normalize_converse_stream_events
         result = normalize_converse_stream_events({"stream": list(self._LIVE_TEXT_THEN_TOOL_EVENTS)})
         msg = result.choices[0].message
         assert msg.content == "I'll echo banana now."
@@ -517,15 +517,6 @@ class TestNormalizeConverseStreamEvents:
             {"toolUse": {"toolUseId": "tooluse_1", "name": "echo", "input": {"s": "banana"}}},
         ]
         assert [tc.function.name for tc in msg.tool_calls] == ["echo"]
-        # The sidecar is authoritative on replay: the next turn must go out as text THEN toolUse, nothing after.
-        _, converse = convert_messages_to_converse([
-            {"role": "user", "content": "echo banana"},
-            {"role": "assistant", "content": msg.content, "bedrock_content_blocks": msg.bedrock_content_blocks,
-             "tool_calls": [{"id": "tooluse_1", "type": "function", "function": {"name": "echo", "arguments": '{"s": "banana"}'}}]},
-            {"role": "tool", "tool_call_id": "tooluse_1", "content": "banana"},
-        ])
-        assert [list(b)[0] for b in converse[1]["content"]] == ["text", "toolUse"]
-        assert converse[1]["content"][0]["text"] == "I'll echo banana now."
 
     def test_events_without_content_block_index_fall_back_to_arrival_order(self):
         """Proxies/test doubles may omit contentBlockIndex: deltas continue the current block, a start opens a

From 6952af5843f527233bacf1e2ac69314127d47310 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Fri, 18 Sep 2026 23:43:15 +0530
Subject: [PATCH 057/190] chore: map worlldz contributor email (salvage #87810)

---
 .../emails/101180447+cryptoworlldz@users.noreply.github.com     | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 contributors/emails/101180447+cryptoworlldz@users.noreply.github.com

diff --git a/contributors/emails/101180447+cryptoworlldz@users.noreply.github.com b/contributors/emails/101180447+cryptoworlldz@users.noreply.github.com
new file mode 100644
index 0000000000..7e7907031d
--- /dev/null
+++ b/contributors/emails/101180447+cryptoworlldz@users.noreply.github.com
@@ -0,0 +1,2 @@
+worlldz
+# PR #87810 salvage

From 65babb3bcb36ed04952d3aae0df289c54e3ecc39 Mon Sep 17 00:00:00 2001
From: worlldz <101180447+cryptoworlldz@users.noreply.github.com>
Date: Sun, 16 Aug 2026 19:25:40 +0300
Subject: [PATCH 058/190] fix(desktop): keep streaming turn out of history
 budget

(cherry picked from commit eb127502196dcd546a082f86827ea6eca995aa79)
---
 .../assistant-ui/thread/list.test.ts          | 15 ++++++++++++
 .../components/assistant-ui/thread/list.tsx   | 23 ++++++++++++++++---
 2 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/apps/desktop/src/components/assistant-ui/thread/list.test.ts b/apps/desktop/src/components/assistant-ui/thread/list.test.ts
index 7979a6e583..a3b1146900 100644
--- a/apps/desktop/src/components/assistant-ui/thread/list.test.ts
+++ b/apps/desktop/src/components/assistant-ui/thread/list.test.ts
@@ -264,6 +264,21 @@ describe('firstVisibleGroupIndex', () => {
 
     expect(firstVisibleGroupIndex(groups, 600, 8)).toBe(0)
   })
+
+  it('keeps the cut stable while the unbudgeted streaming tail grows', () => {
+    const history = [group('old', 50), group('mid', 30), group('recent', 30)]
+    const initial = [...history, group('streaming', 1)]
+    const grown = [...history, group('streaming', 5_000)]
+
+    expect(firstVisibleGroupIndex(initial, 60, 0, 1)).toBe(1)
+    expect(firstVisibleGroupIndex(grown, 60, 0, 1)).toBe(1)
+  })
+
+  it('charges a completed tail to the budget as before', () => {
+    const groups = [group('old', 50), group('recent', 30), group('completed', 5_000)]
+
+    expect(firstVisibleGroupIndex(groups, 60)).toBe(2)
+  })
 })
 
 describe('liveTailStart', () => {
diff --git a/apps/desktop/src/components/assistant-ui/thread/list.tsx b/apps/desktop/src/components/assistant-ui/thread/list.tsx
index 889fbda2e1..252e7cb9e5 100644
--- a/apps/desktop/src/components/assistant-ui/thread/list.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/list.tsx
@@ -281,11 +281,20 @@ export function buildGroups(signature: string): MessageGroup[] {
 // Walk turns newest-first, summing their render weights until the budget is met;
 // everything before the first kept turn is hidden. `minVisible` turns are kept
 // regardless of weight. Returns the index of that first visible group.
-export function firstVisibleGroupIndex(groups: readonly MessageGroup[], budget: number, minVisible = 0): number {
+export function firstVisibleGroupIndex(
+  groups: readonly MessageGroup[],
+  budget: number,
+  minVisible = 0,
+  unbudgetedTail = 0
+): number {
   let firstVisible = groups.length
+  const budgetedEnd = Math.max(0, groups.length - unbudgetedTail)
 
   for (let i = groups.length - 1, weight = 0; i >= 0; i--) {
-    weight += groups[i].weight
+    if (i < budgetedEnd) {
+      weight += groups[i].weight
+    }
+
     firstVisible = i
 
     if (weight >= budget) {
@@ -444,6 +453,8 @@ const ThreadMessageListInner: FC<ThreadMessageListProps> = ({
     s.thread.messages.map(message => messagePaintWeight(message.content)).join(',')
   )
 
+  const threadRunning = useAuiState(s => s.thread.isRunning)
+
   const { t } = useI18n()
   // Row structure is memoized on the STRUCTURAL signature only, so streaming
   // part-appends can't churn group identity (that would defeat the rows memo
@@ -586,7 +597,13 @@ const ThreadMessageListInner: FC<ThreadMessageListProps> = ({
   const hiddenCount = firstVisibleGroupIndex(
     weightedGroups,
     renderBudget,
-    renderBudget >= paneBudget ? MIN_VISIBLE_GROUPS : 0
+    renderBudget >= paneBudget ? MIN_VISIBLE_GROUPS : 0,
+    // The active turn has to stay mounted regardless of size. Charging its
+    // growing weight to the history budget made this cut advance mid-stream:
+    // old rows unmounted, scrollHeight shrank, and the browser clamp looked
+    // like a user scroll-up to use-stick-to-bottom. Budget the history around
+    // the live turn instead, so token flushes cannot move the cut boundary.
+    threadRunning ? 1 : 0
   )
 
   // Memoized for IDENTITY, not to save the slice: `rows` below keys off this

From c1af9c64942858d952a066cf0f7213dd74d980f9 Mon Sep 17 00:00:00 2001
From: Victor Nogueira <victornogu80@gmail.com>
Date: Thu, 27 Aug 2026 15:32:28 +0800
Subject: [PATCH 059/190] fix(desktop): keep newest turn outside history budget

(cherry picked from commit de08125d046c56463c42df9365f41d0e83c895fe)
---
 .../components/assistant-ui/thread/list.test.ts   | 15 ++++++++++++---
 .../src/components/assistant-ui/thread/list.tsx   | 13 +++++--------
 2 files changed, 17 insertions(+), 11 deletions(-)

diff --git a/apps/desktop/src/components/assistant-ui/thread/list.test.ts b/apps/desktop/src/components/assistant-ui/thread/list.test.ts
index a3b1146900..d95764126f 100644
--- a/apps/desktop/src/components/assistant-ui/thread/list.test.ts
+++ b/apps/desktop/src/components/assistant-ui/thread/list.test.ts
@@ -274,10 +274,19 @@ describe('firstVisibleGroupIndex', () => {
     expect(firstVisibleGroupIndex(grown, 60, 0, 1)).toBe(1)
   })
 
-  it('charges a completed tail to the budget as before', () => {
-    const groups = [group('old', 50), group('recent', 30), group('completed', 5_000)]
+  it('keeps the cut stable when the tail completes', () => {
+    // With the newest group always unbudgeted, a heavy tail that finishes
+    // streaming does not advance the cut — the completion transition cannot
+    // change firstVisibleGroupIndex.
+    const groups = [group('old', 50), group('recent', 30), group('tail', 5_000)]
 
-    expect(firstVisibleGroupIndex(groups, 60)).toBe(2)
+    expect(firstVisibleGroupIndex(groups, 60, 0, 1)).toBe(0)
+  })
+
+  it('exempts exactly one newest group while older history stays budgeted', () => {
+    const groups = [group('a', 200), group('b', 50), group('c', 50), group('d', 50), group('e', 10_000)]
+
+    expect(firstVisibleGroupIndex(groups, 60, 0, 1)).toBe(2)
   })
 })
 
diff --git a/apps/desktop/src/components/assistant-ui/thread/list.tsx b/apps/desktop/src/components/assistant-ui/thread/list.tsx
index 252e7cb9e5..7ebee10452 100644
--- a/apps/desktop/src/components/assistant-ui/thread/list.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/list.tsx
@@ -453,8 +453,6 @@ const ThreadMessageListInner: FC<ThreadMessageListProps> = ({
     s.thread.messages.map(message => messagePaintWeight(message.content)).join(',')
   )
 
-  const threadRunning = useAuiState(s => s.thread.isRunning)
-
   const { t } = useI18n()
   // Row structure is memoized on the STRUCTURAL signature only, so streaming
   // part-appends can't churn group identity (that would defeat the rows memo
@@ -598,12 +596,11 @@ const ThreadMessageListInner: FC<ThreadMessageListProps> = ({
     weightedGroups,
     renderBudget,
     renderBudget >= paneBudget ? MIN_VISIBLE_GROUPS : 0,
-    // The active turn has to stay mounted regardless of size. Charging its
-    // growing weight to the history budget made this cut advance mid-stream:
-    // old rows unmounted, scrollHeight shrank, and the browser clamp looked
-    // like a user scroll-up to use-stick-to-bottom. Budget the history around
-    // the live turn instead, so token flushes cannot move the cut boundary.
-    threadRunning ? 1 : 0
+    // The newest turn is always exempt from the history render budget so its
+    // growing — then completed — weight never advances the cut boundary. A
+    // moving cut unmounts older rows, shrinks scrollHeight, and the browser
+    // clamp looks like a user scroll-up to use-stick-to-bottom.
+    1
   )
 
   // Memoized for IDENTITY, not to save the slice: `rows` below keys off this

From 5c4b87a37170722eb0e519968fd34c6e2ca919af Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Fri, 18 Sep 2026 23:54:03 +0530
Subject: [PATCH 060/190] test(desktop): trim the unbudgeted-tail coverage to
 two invariants
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The completion-time case is the same contract as 'exactly one newest group
is exempt' — a heavy tail never charges the budget whether it is still
streaming or done — so one test pinning the growth and one pinning the
single-group exemption cover it.
---
 .../src/components/assistant-ui/thread/list.test.ts      | 9 ---------
 1 file changed, 9 deletions(-)

diff --git a/apps/desktop/src/components/assistant-ui/thread/list.test.ts b/apps/desktop/src/components/assistant-ui/thread/list.test.ts
index d95764126f..4966d07eb6 100644
--- a/apps/desktop/src/components/assistant-ui/thread/list.test.ts
+++ b/apps/desktop/src/components/assistant-ui/thread/list.test.ts
@@ -274,15 +274,6 @@ describe('firstVisibleGroupIndex', () => {
     expect(firstVisibleGroupIndex(grown, 60, 0, 1)).toBe(1)
   })
 
-  it('keeps the cut stable when the tail completes', () => {
-    // With the newest group always unbudgeted, a heavy tail that finishes
-    // streaming does not advance the cut — the completion transition cannot
-    // change firstVisibleGroupIndex.
-    const groups = [group('old', 50), group('recent', 30), group('tail', 5_000)]
-
-    expect(firstVisibleGroupIndex(groups, 60, 0, 1)).toBe(0)
-  })
-
   it('exempts exactly one newest group while older history stays budgeted', () => {
     const groups = [group('a', 200), group('b', 50), group('c', 50), group('d', 50), group('e', 10_000)]
 

From bdcda7e37e970f1e2501bf584c01b99191de333e Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:34:47 +0530
Subject: [PATCH 061/190] fix(desktop): exempt the newest turn from the budget
 on a real page only

Review of the salvage: exempting the newest turn during the first-paint
budget made the walk always continue into the previous turn, so a heavy
previous turn landed in the synchronous first-paint commit that
FIRST_PAINT_BUDGET exists to keep small. Gate the exemption the way the turn
floor already is (renderBudget >= paneBudget); the rAF backfill reaches a
real page a frame later and the cut is stable from then on. Also start the
walk at the budgeted end instead of testing every index, and document the
parameter on the function.
---
 .../components/assistant-ui/thread/list.tsx   | 37 ++++++++++---------
 1 file changed, 20 insertions(+), 17 deletions(-)

diff --git a/apps/desktop/src/components/assistant-ui/thread/list.tsx b/apps/desktop/src/components/assistant-ui/thread/list.tsx
index 7ebee10452..6df0182e0d 100644
--- a/apps/desktop/src/components/assistant-ui/thread/list.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/list.tsx
@@ -280,21 +280,20 @@ export function buildGroups(signature: string): MessageGroup[] {
 
 // Walk turns newest-first, summing their render weights until the budget is met;
 // everything before the first kept turn is hidden. `minVisible` turns are kept
-// regardless of weight. Returns the index of that first visible group.
+// regardless of weight; the newest `unbudgetedTail` turns are kept AND left out
+// of the sum, so a turn whose weight is still changing cannot move the cut.
+// Returns the index of that first visible group.
 export function firstVisibleGroupIndex(
   groups: readonly MessageGroup[],
   budget: number,
   minVisible = 0,
   unbudgetedTail = 0
 ): number {
-  let firstVisible = groups.length
   const budgetedEnd = Math.max(0, groups.length - unbudgetedTail)
+  let firstVisible = budgetedEnd
 
-  for (let i = groups.length - 1, weight = 0; i >= 0; i--) {
-    if (i < budgetedEnd) {
-      weight += groups[i].weight
-    }
-
+  for (let i = budgetedEnd - 1, weight = 0; i >= 0; i--) {
+    weight += groups[i].weight
     firstVisible = i
 
     if (weight >= budget) {
@@ -588,19 +587,23 @@ const ThreadMessageListInner: FC<ThreadMessageListProps> = ({
     }))
   }, [groups, weightSignature])
 
-  // The turn floor applies to a real page only. During the first-paint budget
-  // the point is a small synchronous commit; forcing 8 turns into it would put
-  // back exactly the freeze FIRST_PAINT_BUDGET exists to avoid, and the rAF
-  // backfill a frame later fills them in anyway.
+  // The turn floor and the newest-turn exemption apply to a real page only.
+  // During the first-paint budget the point is a small synchronous commit;
+  // forcing 8 turns into it — or a whole extra turn behind an unbudgeted
+  // newest one — would put back exactly the freeze FIRST_PAINT_BUDGET exists
+  // to avoid, and the rAF backfill a frame later fills them in anyway.
+  //
+  // On a real page the newest turn is exempt from the history budget so its
+  // growing — then completed — weight never advances the cut boundary. A
+  // moving cut unmounts older rows, shrinks scrollHeight, and the browser
+  // clamp looks like a user scroll-up to use-stick-to-bottom.
+  const fullPage = renderBudget >= paneBudget
+
   const hiddenCount = firstVisibleGroupIndex(
     weightedGroups,
     renderBudget,
-    renderBudget >= paneBudget ? MIN_VISIBLE_GROUPS : 0,
-    // The newest turn is always exempt from the history render budget so its
-    // growing — then completed — weight never advances the cut boundary. A
-    // moving cut unmounts older rows, shrinks scrollHeight, and the browser
-    // clamp looks like a user scroll-up to use-stick-to-bottom.
-    1
+    fullPage ? MIN_VISIBLE_GROUPS : 0,
+    fullPage ? 1 : 0
   )
 
   // Memoized for IDENTITY, not to save the slice: `rows` below keys off this

From b46f2448f752f57c1060f65489f481804515610d Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:56:40 +0530
Subject: [PATCH 062/190] refactor(desktop): the newest-turn exemption is a
 boolean, not a count

Nothing ever passed a tail length other than 0 or 1, and a bare `1` at the
call site needed the comment to decode. `exemptNewest` reads at the call
site without it; the doc comment now also says the exempt turn counts toward
`minVisible`.
---
 .../assistant-ui/thread/list.test.ts           |  6 +++---
 .../components/assistant-ui/thread/list.tsx    | 18 +++++++-----------
 2 files changed, 10 insertions(+), 14 deletions(-)

diff --git a/apps/desktop/src/components/assistant-ui/thread/list.test.ts b/apps/desktop/src/components/assistant-ui/thread/list.test.ts
index 4966d07eb6..3b277cd1a4 100644
--- a/apps/desktop/src/components/assistant-ui/thread/list.test.ts
+++ b/apps/desktop/src/components/assistant-ui/thread/list.test.ts
@@ -270,14 +270,14 @@ describe('firstVisibleGroupIndex', () => {
     const initial = [...history, group('streaming', 1)]
     const grown = [...history, group('streaming', 5_000)]
 
-    expect(firstVisibleGroupIndex(initial, 60, 0, 1)).toBe(1)
-    expect(firstVisibleGroupIndex(grown, 60, 0, 1)).toBe(1)
+    expect(firstVisibleGroupIndex(initial, 60, 0, true)).toBe(1)
+    expect(firstVisibleGroupIndex(grown, 60, 0, true)).toBe(1)
   })
 
   it('exempts exactly one newest group while older history stays budgeted', () => {
     const groups = [group('a', 200), group('b', 50), group('c', 50), group('d', 50), group('e', 10_000)]
 
-    expect(firstVisibleGroupIndex(groups, 60, 0, 1)).toBe(2)
+    expect(firstVisibleGroupIndex(groups, 60, 0, true)).toBe(2)
   })
 })
 
diff --git a/apps/desktop/src/components/assistant-ui/thread/list.tsx b/apps/desktop/src/components/assistant-ui/thread/list.tsx
index 6df0182e0d..cef4731232 100644
--- a/apps/desktop/src/components/assistant-ui/thread/list.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/list.tsx
@@ -280,16 +280,17 @@ export function buildGroups(signature: string): MessageGroup[] {
 
 // Walk turns newest-first, summing their render weights until the budget is met;
 // everything before the first kept turn is hidden. `minVisible` turns are kept
-// regardless of weight; the newest `unbudgetedTail` turns are kept AND left out
-// of the sum, so a turn whose weight is still changing cannot move the cut.
-// Returns the index of that first visible group.
+// regardless of weight (the exempt newest turn counts as one of them). With
+// `exemptNewest` the newest turn is kept AND left out of the sum, so a turn
+// whose weight is still changing cannot move the cut. Returns the index of that
+// first visible group.
 export function firstVisibleGroupIndex(
   groups: readonly MessageGroup[],
   budget: number,
   minVisible = 0,
-  unbudgetedTail = 0
+  exemptNewest = false
 ): number {
-  const budgetedEnd = Math.max(0, groups.length - unbudgetedTail)
+  const budgetedEnd = exemptNewest ? Math.max(0, groups.length - 1) : groups.length
   let firstVisible = budgetedEnd
 
   for (let i = budgetedEnd - 1, weight = 0; i >= 0; i--) {
@@ -599,12 +600,7 @@ const ThreadMessageListInner: FC<ThreadMessageListProps> = ({
   // clamp looks like a user scroll-up to use-stick-to-bottom.
   const fullPage = renderBudget >= paneBudget
 
-  const hiddenCount = firstVisibleGroupIndex(
-    weightedGroups,
-    renderBudget,
-    fullPage ? MIN_VISIBLE_GROUPS : 0,
-    fullPage ? 1 : 0
-  )
+  const hiddenCount = firstVisibleGroupIndex(weightedGroups, renderBudget, fullPage ? MIN_VISIBLE_GROUPS : 0, fullPage)
 
   // Memoized for IDENTITY, not to save the slice: `rows` below keys off this
   // array, and an inline slice handed it a fresh array every render — so the

From 3176c2ef68f627c4b593aeaae9f1439858d80343 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:20:22 +0530
Subject: [PATCH 063/190] chore: map kiwiwyl contributor email (salvage #81490)

---
 contributors/emails/hgwangyongli@gmail.com | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 contributors/emails/hgwangyongli@gmail.com

diff --git a/contributors/emails/hgwangyongli@gmail.com b/contributors/emails/hgwangyongli@gmail.com
new file mode 100644
index 0000000000..d02818010e
--- /dev/null
+++ b/contributors/emails/hgwangyongli@gmail.com
@@ -0,0 +1,2 @@
+kiwiwyl
+# PR #81490 salvage

From e16fd43ca4a957baaec97658ee64526253257882 Mon Sep 17 00:00:00 2001
From: Yongli <hgwangyongli@gmail.com>
Date: Sat, 19 Sep 2026 00:22:01 +0530
Subject: [PATCH 064/190] fix(desktop): count pinned rows toward sidebar window
 truncation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The recents window is a LIMIT-cap page by recency plus a back-fill of pins
the page missed. Both truncation flags — the batched /sidebar route and the
legacy per-slice derivation in the app — discounted every pinned row, on the
theory that pins only ever arrive past the LIMIT. Pins inside the window
occupy real slots, so with two pinned rows among the twenty newest the count
came to 18 < 20, `profiles_truncated` read false, and the sidebar never
mounted "Load more": every older session was unreachable (#81484).

Count every row. A list shorter than the cap has nothing past the page for
the back-fill to add, so pins cannot fake a full page there; at worst a list
of exactly cap rows costs one click that resolves to an empty page.

Salvaged from #81490.
---
 apps/desktop/src/api/sessions.ts   |  8 ++++----
 hermes_cli/web_routers/profiles.py | 10 ++++++----
 2 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/apps/desktop/src/api/sessions.ts b/apps/desktop/src/api/sessions.ts
index c1c090045d..ec32d7a7d5 100644
--- a/apps/desktop/src/api/sessions.ts
+++ b/apps/desktop/src/api/sessions.ts
@@ -171,16 +171,16 @@ export interface SidebarSessionSlice {
 
 /** Which profiles filled their per-profile window in a returned page. The
  *  legacy per-slice endpoint doesn't report this, so derive it from the rows:
- *  a profile at (or over) the cap still has more on disk. Pinned rows are
- *  discounted — they're back-filled past the LIMIT, so counting them fakes a
- *  full page and leaves a "Load more" that can never resolve. */
+ *  a profile at (or over) the cap still has more on disk. Pinned rows count
+ *  like any other: they occupy LIMIT slots, so discounting them hid the
+ *  load-more row whenever a pin sat inside the window (#81484). */
 function profilesTruncatedFrom(sessions: SessionInfo[], cap: number): Record<string, boolean> {
   const counts = new Map<string, number>()
 
   for (const session of sessions) {
     const key = session.profile || 'default'
 
-    counts.set(key, (counts.get(key) ?? 0) + (session.pinned ? 0 : 1))
+    counts.set(key, (counts.get(key) ?? 0) + 1)
   }
 
   return Object.fromEntries([...counts].map(([name, count]) => [name, count >= cap]))
diff --git a/hermes_cli/web_routers/profiles.py b/hermes_cli/web_routers/profiles.py
index caf831fa52..c6c81da06f 100644
--- a/hermes_cli/web_routers/profiles.py
+++ b/hermes_cli/web_routers/profiles.py
@@ -515,10 +515,12 @@ def get_profiles_sessions_sidebar(
             if slices is None:
                 continue
         # A full window means more rows remain on disk — all "load more" needs, at no cost
-        # beyond the rows already read. Discount pinned back-fills: they arrive past the
-        # LIMIT and would fake a full page on a short list.
-        unpinned_count = sum(1 for s in slices["recents"] if not s.get("pinned"))
-        recents_truncated[name] = unpinned_count >= cap["recents"]
+        # beyond the rows already read. Pinned rows count: they occupy LIMIT slots like any
+        # other recent row, so discounting them under-reported a full page whenever a pin
+        # sat inside the window and stranded older sessions behind a "Load more" that
+        # never appeared (#81484). A short list has no rows past the page for the pin
+        # back-fill to add, so counting pins cannot fake a full page there.
+        recents_truncated[name] = len(slices["recents"]) >= cap["recents"]
         profile_totals[name] = slices["usage"]
         for key in slice_scope:
             rows[key].extend(_tag_rows(slices[key], name, now))

From 31ca48512be20592e1f3eff2b3782dbfc9f8f29a Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:31:19 +0530
Subject: [PATCH 065/190] test(sidebar): pins inside the recency window still
 report more sessions on disk

One test per truncation flag: the batched /api/profiles/sessions/sidebar
route (real state.db, two pinned among the newest rows, cap 4) and the
desktop's legacy per-slice derivation (3 pinned + 17 unpinned against a cap
of 20). Both red on origin/main, green with the fix. Regression for #81484.
---
 apps/desktop/src/hermes.test.ts               | 35 ++++++++++++++++++
 .../hermes_cli/test_profiles_sidebar_scope.py | 36 +++++++++++++++++++
 2 files changed, 71 insertions(+)

diff --git a/apps/desktop/src/hermes.test.ts b/apps/desktop/src/hermes.test.ts
index 30c70e8e12..e1c801b1fb 100644
--- a/apps/desktop/src/hermes.test.ts
+++ b/apps/desktop/src/hermes.test.ts
@@ -245,6 +245,41 @@ describe('Hermes REST helpers', () => {
     expect(result.messaging.sessions).toEqual([])
   })
 
+  it('counts pinned rows toward a full legacy page so older sessions stay reachable', async () => {
+    // #81484: pins inside the window take LIMIT slots. 3 pinned + 17 unpinned
+    // against a cap of 20 IS a full page; discounting the pins read 17 < 20
+    // and the load-more row never mounted.
+    const row = (id: string, pinned: boolean) => ({ id, title: id, profile: 'default', pinned })
+
+    const recents = [
+      ...Array.from({ length: 3 }, (_, i) => row(`pinned-${i}`, true)),
+      ...Array.from({ length: 17 }, (_, i) => row(`recent-${i}`, false))
+    ]
+
+    api.mockImplementation(({ path }: { path: string }) => {
+      if (path.startsWith('/api/profiles/sessions/sidebar')) {
+        return Promise.reject(new Error('404: {"detail":"No such API endpoint: /api/profiles/sessions/sidebar"}'))
+      }
+
+      if (path.includes('source=cron') || path.includes('exclude_sources=')) {
+        return Promise.resolve({ ...emptySessionsResponse, sessions: [], total: 0 })
+      }
+
+      return Promise.resolve({ ...emptySessionsResponse, sessions: recents, total: recents.length })
+    })
+
+    const result = await listSidebarSessions({
+      recentsProfile: 'default',
+      recentsLimit: 20,
+      recentsExclude: [],
+      cronLimit: 50,
+      messagingLimit: 100,
+      messagingExclude: []
+    })
+
+    expect(result.recents.profiles_truncated).toEqual({ default: true })
+  })
+
   it('falls back to the per-slice endpoint when the batched route 404s on an older backend', async () => {
     const row = (id: string) => ({ id, title: id, profile: 'default' })
 
diff --git a/tests/hermes_cli/test_profiles_sidebar_scope.py b/tests/hermes_cli/test_profiles_sidebar_scope.py
index 5b5f4f6aab..4bf1b95a53 100644
--- a/tests/hermes_cli/test_profiles_sidebar_scope.py
+++ b/tests/hermes_cli/test_profiles_sidebar_scope.py
@@ -256,3 +256,39 @@ class TestCrossProfileProjectTree:
         # The healthy profile's tree still lands; only the broken one drops out.
         assert "Healthy" in [project["label"] for project in payload["projects"]]
         assert [project["sessionCount"] for project in payload["projects"] if project["isNoProject"]] == [1]
+
+
+class TestSidebarTruncation:
+
+    def test_pinned_rows_inside_the_window_still_report_more_on_disk(self, client, profiles_on_disk):
+        # Regression for #81484: the window is a LIMIT page by recency, so a
+        # pin among the newest rows takes a slot. Discounting pins reported 18
+        # < 20 and the sidebar never offered "Load more" for the older rows.
+        from hermes_state import SessionDB
+
+        home = profiles_on_disk["default"]
+        params = {"recents_profile": "default", "recents_limit": 4}
+
+        def truncated():
+            payload = client.get("/api/profiles/sessions/sidebar", params=params).json()
+            return len(payload["recents"]["sessions"]), payload["recents"]["profiles_truncated"]
+
+        for index in range(3):
+            _seed_session(home, f"s-{index}", source="desktop")
+        db = SessionDB(db_path=home / "state.db")
+        try:
+            assert db.set_session_pinned("s-2", True)
+        finally:
+            db.close()
+        # Short list: the pin is already on the page, nothing to back-fill, no "more".
+        assert truncated() == (3, {"default": False})
+
+        for index in range(3, 6):
+            _seed_session(home, f"s-{index}", source="desktop")
+        db = SessionDB(db_path=home / "state.db")
+        try:
+            assert db.set_session_pinned("s-5", True)
+        finally:
+            db.close()
+        # Six on disk, two pins among the newest four: a full window, more below it.
+        assert truncated() == (4, {"default": True})

From 4c28768ef734c57fec87d2c366d5b54bfa53e7cb Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 01:08:20 +0530
Subject: [PATCH 066/190] refactor(sidebar): trim the truncation comment to the
 invariant; fold the pin helper in the test

---
 hermes_cli/web_routers/profiles.py            |  8 +++-----
 .../hermes_cli/test_profiles_sidebar_scope.py | 19 +++++++++----------
 2 files changed, 12 insertions(+), 15 deletions(-)

diff --git a/hermes_cli/web_routers/profiles.py b/hermes_cli/web_routers/profiles.py
index c6c81da06f..6cb69dce16 100644
--- a/hermes_cli/web_routers/profiles.py
+++ b/hermes_cli/web_routers/profiles.py
@@ -515,11 +515,9 @@ def get_profiles_sessions_sidebar(
             if slices is None:
                 continue
         # A full window means more rows remain on disk — all "load more" needs, at no cost
-        # beyond the rows already read. Pinned rows count: they occupy LIMIT slots like any
-        # other recent row, so discounting them under-reported a full page whenever a pin
-        # sat inside the window and stranded older sessions behind a "Load more" that
-        # never appeared (#81484). A short list has no rows past the page for the pin
-        # back-fill to add, so counting pins cannot fake a full page there.
+        # beyond the rows already read. Pinned rows count: they occupy LIMIT slots, and a
+        # short list has nothing past the page for the pin back-fill to add, so pins cannot
+        # fake a full page (#81484).
         recents_truncated[name] = len(slices["recents"]) >= cap["recents"]
         profile_totals[name] = slices["usage"]
         for key in slice_scope:
diff --git a/tests/hermes_cli/test_profiles_sidebar_scope.py b/tests/hermes_cli/test_profiles_sidebar_scope.py
index 4bf1b95a53..9aa518c47b 100644
--- a/tests/hermes_cli/test_profiles_sidebar_scope.py
+++ b/tests/hermes_cli/test_profiles_sidebar_scope.py
@@ -273,22 +273,21 @@ class TestSidebarTruncation:
             payload = client.get("/api/profiles/sessions/sidebar", params=params).json()
             return len(payload["recents"]["sessions"]), payload["recents"]["profiles_truncated"]
 
+        def pin(session_id):
+            db = SessionDB(db_path=home / "state.db")
+            try:
+                assert db.set_session_pinned(session_id, True)
+            finally:
+                db.close()
+
         for index in range(3):
             _seed_session(home, f"s-{index}", source="desktop")
-        db = SessionDB(db_path=home / "state.db")
-        try:
-            assert db.set_session_pinned("s-2", True)
-        finally:
-            db.close()
+        pin("s-2")
         # Short list: the pin is already on the page, nothing to back-fill, no "more".
         assert truncated() == (3, {"default": False})
 
         for index in range(3, 6):
             _seed_session(home, f"s-{index}", source="desktop")
-        db = SessionDB(db_path=home / "state.db")
-        try:
-            assert db.set_session_pinned("s-5", True)
-        finally:
-            db.close()
+        pin("s-5")
         # Six on disk, two pins among the newest four: a full window, more below it.
         assert truncated() == (4, {"default": True})

From 5a55979e16edc64d8d9a6d65ac74390b88acb93c Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 01:25:32 +0530
Subject: [PATCH 067/190] refactor(sidebar): seed pinned rows through
 _seed_session; mirror the truncation invariant in the TS comment

---
 apps/desktop/src/api/sessions.ts              |  5 ++--
 .../hermes_cli/test_profiles_sidebar_scope.py | 25 ++++++-------------
 2 files changed, 11 insertions(+), 19 deletions(-)

diff --git a/apps/desktop/src/api/sessions.ts b/apps/desktop/src/api/sessions.ts
index ec32d7a7d5..81c938caf4 100644
--- a/apps/desktop/src/api/sessions.ts
+++ b/apps/desktop/src/api/sessions.ts
@@ -172,8 +172,9 @@ export interface SidebarSessionSlice {
 /** Which profiles filled their per-profile window in a returned page. The
  *  legacy per-slice endpoint doesn't report this, so derive it from the rows:
  *  a profile at (or over) the cap still has more on disk. Pinned rows count
- *  like any other: they occupy LIMIT slots, so discounting them hid the
- *  load-more row whenever a pin sat inside the window (#81484). */
+ *  like any other: they occupy LIMIT slots, and a short list has nothing past
+ *  the page for the pin back-fill to add, so pins cannot fake a full page
+ *  (#81484). */
 function profilesTruncatedFrom(sessions: SessionInfo[], cap: number): Record<string, boolean> {
   const counts = new Map<string, number>()
 
diff --git a/tests/hermes_cli/test_profiles_sidebar_scope.py b/tests/hermes_cli/test_profiles_sidebar_scope.py
index 9aa518c47b..d2cd699e5b 100644
--- a/tests/hermes_cli/test_profiles_sidebar_scope.py
+++ b/tests/hermes_cli/test_profiles_sidebar_scope.py
@@ -62,7 +62,7 @@ def client(monkeypatch, profiles_on_disk):
     return c
 
 
-def _seed_session(home, session_id, *, source, cwd=None, tokens=None, cost=None):
+def _seed_session(home, session_id, *, source, cwd=None, tokens=None, cost=None, pinned=False):
     """One session with a message, so it clears the sidebar's min_messages=1.
 
     ``cwd`` is what attaches it to a project — without one it lands in Home.
@@ -77,6 +77,8 @@ def _seed_session(home, session_id, *, source, cwd=None, tokens=None, cost=None)
     try:
         db.create_session(session_id, source=source, cwd=str(cwd) if cwd else None)
         db.append_message(session_id=session_id, role="user", content="hi")
+        if pinned:
+            assert db.set_session_pinned(session_id, True)
     finally:
         db.close()
 
@@ -264,30 +266,19 @@ class TestSidebarTruncation:
         # Regression for #81484: the window is a LIMIT page by recency, so a
         # pin among the newest rows takes a slot. Discounting pins reported 18
         # < 20 and the sidebar never offered "Load more" for the older rows.
-        from hermes_state import SessionDB
-
         home = profiles_on_disk["default"]
         params = {"recents_profile": "default", "recents_limit": 4}
 
-        def truncated():
+        def window():
             payload = client.get("/api/profiles/sessions/sidebar", params=params).json()
             return len(payload["recents"]["sessions"]), payload["recents"]["profiles_truncated"]
 
-        def pin(session_id):
-            db = SessionDB(db_path=home / "state.db")
-            try:
-                assert db.set_session_pinned(session_id, True)
-            finally:
-                db.close()
-
         for index in range(3):
-            _seed_session(home, f"s-{index}", source="desktop")
-        pin("s-2")
+            _seed_session(home, f"s-{index}", source="desktop", pinned=index == 2)
         # Short list: the pin is already on the page, nothing to back-fill, no "more".
-        assert truncated() == (3, {"default": False})
+        assert window() == (3, {"default": False})
 
         for index in range(3, 6):
-            _seed_session(home, f"s-{index}", source="desktop")
-        pin("s-5")
+            _seed_session(home, f"s-{index}", source="desktop", pinned=index == 5)
         # Six on disk, two pins among the newest four: a full window, more below it.
-        assert truncated() == (4, {"default": True})
+        assert window() == (4, {"default": True})

From 8e8fd7415cea781865180736b23742e89053bd9f Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Fri, 18 Sep 2026 23:38:16 +0530
Subject: [PATCH 068/190] chore: map contributor email for @dasgltd (#91655
 salvage)

---
 contributors/emails/daniel@dasg.ltd | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 contributors/emails/daniel@dasg.ltd

diff --git a/contributors/emails/daniel@dasg.ltd b/contributors/emails/daniel@dasg.ltd
new file mode 100644
index 0000000000..a2753ea868
--- /dev/null
+++ b/contributors/emails/daniel@dasg.ltd
@@ -0,0 +1,2 @@
+dasgltd
+# PR #91655 salvage

From c961e5bb6917643ec7ee59e591b974657d44b34f Mon Sep 17 00:00:00 2001
From: Daniel Silva <daniel@dasg.ltd>
Date: Sat, 19 Sep 2026 00:06:42 +0530
Subject: [PATCH 069/190] fix(gateway): retry any rejected final send with a
 backoff, not only flood refusals

A final reply the platform rejected with anything other than flood control
(a 5xx, a transient parse error, an unclassified failure) sat in the ledger
as `failed` until the next gateway restart, because the runtime sweep only
claimed `send_path_degraded` and flood rows and no timer was armed for it
(#91653). The deadline-driven redelivery worker main already runs for flood
rows now covers every failed row: `retry_not_before` keeps the platform's
wait for flood rows, retries allowlisted reconnect errors at once, backs
any other rejection off by attempts (30 s, 2 min, 10 min) so an outage is
not hammered, and returns None for a whole-chat death (blocked bot, deleted
chat) so a dead target is never resent. `pending_flood_retries` becomes
`pending_retries`; the adapter arms the timer on every rejection.

`release_runtime_claim`'s attempts decrement is untouched: it refunds an
attempt a claim never spent, which the backoff relies on unchanged.

design via #91655 by @dasgltd

Co-authored-by: Daniel Silva <daniel@dasg.ltd>
---
 gateway/delivery_ledger.py            | 65 +++++++++++++++++----------
 gateway/platforms/base.py             | 10 ++---
 gateway/run_startup.py                | 14 +++---
 tests/gateway/test_delivery_ledger.py | 26 ++++++++++-
 4 files changed, 79 insertions(+), 36 deletions(-)

diff --git a/gateway/delivery_ledger.py b/gateway/delivery_ledger.py
index ae37d3662c..e406ef7470 100644
--- a/gateway/delivery_ledger.py
+++ b/gateway/delivery_ledger.py
@@ -21,6 +21,7 @@ import threading
 import time
 from typing import Any, Dict, List, Optional
 
+from gateway.dead_targets import classify_dead_error
 from hermes_cli.sqlite_util import add_column_if_missing
 from hermes_constants import get_hermes_home
 
@@ -48,9 +49,13 @@ RECONNECTED_MARKER = ("♻️ Recovered reply — the messaging platform reconne
 FLOOD_MARKER = ("♻️ Recovered reply — the messaging platform's rate limit refused the original, so part of "
                 "it may already have arrived above:\n\n")
 
-# Runtime replay is fail-closed: only errors whose send contract proves they are transient reconnect
-# failures. Permanent rejects (blocked bot, bad auth, missing chat) must not be retried on reconnect.
+# Errors whose send contract proves the platform never saw the request: retried as soon as the adapter
+# is back, no backoff. Every other rejection is retried too (#91653: a 5xx or a transient parse error
+# used to strand the reply in ``failed`` until the next restart), but only after a backoff that grows
+# with the attempts already spent, so a platform-side outage is not hammered by the redelivery timer.
+# A whole-chat death (blocked bot, deleted group, deactivated user) is never retried: the target is gone.
 _RUNTIME_RETRYABLE_ERRORS = frozenset({"send_path_degraded"})
+_RETRY_BACKOFF_SECONDS = (30.0, 120.0, 600.0)
 
 # A final send the platform refused with flood control is the other transient case: a 429 means the
 # refused request was never accepted, and the platform said how long to wait. Adapters fail such sends
@@ -122,20 +127,33 @@ def flood_retry_delay(seconds: Any) -> float:
     return min(max(wait, 0.0), FLOOD_RETRY_CAP_SECONDS) + FLOOD_RETRY_SLACK_SECONDS
 
 
+def _failed_stamp(updated_at: Any) -> float:
+    try:
+        return float(updated_at or 0.0)
+    except (TypeError, ValueError):
+        return 0.0
+
+
 def flood_not_before(updated_at: Any, last_error: Any) -> float:
     """Earliest moment a flood-refused row may be resent: the refusal's timestamp (``mark_failed`` sets
     ``updated_at``) plus the platform's wait. Enforced by the sweeps so neither an early timer nor a
     reconnect sweep spends a redelivery attempt inside the penalty window."""
-    try:
-        stamp = float(updated_at or 0.0)
-    except (TypeError, ValueError):
-        stamp = 0.0
-    return stamp + flood_wait_seconds(last_error)
+    return _failed_stamp(updated_at) + flood_wait_seconds(last_error)
 
 
-def _runtime_retryable(last_error: Any) -> bool:
+def retry_not_before(updated_at: Any, last_error: Any, attempts: Any) -> Optional[float]:
+    """Earliest moment a failed row may be resent, or ``None`` for a row that must never be: a flood
+    refusal keeps the platform's own wait, an allowlisted reconnect error is due at once, a whole-chat
+    death is final, and any other rejection backs off by the attempts already spent."""
+    if is_flood_error(last_error):
+        return flood_not_before(updated_at, last_error)
     text = str(last_error or "").strip().lower()
-    return text in _RUNTIME_RETRYABLE_ERRORS or is_flood_error(text)
+    if text in _RUNTIME_RETRYABLE_ERRORS:
+        return _failed_stamp(updated_at)
+    if classify_dead_error(text):
+        return None
+    backoff = _RETRY_BACKOFF_SECONDS[min(int(attempts or 0), len(_RETRY_BACKOFF_SECONDS) - 1)]
+    return _failed_stamp(updated_at) + backoff
 
 
 def _db_path():
@@ -386,15 +404,15 @@ def sweep_recoverable(now: Optional[float] = None, *, deliverable_platforms: Opt
 
 def sweep_failed_for_runtime(platform: str, now: Optional[float] = None, *,
                              profile: Optional[str] = None) -> List[Dict[str, Any]]:
-    """Claim this process's reconnect-retryable failed rows for one adapter.
+    """Claim this process's failed rows that are due for another send, for one adapter.
 
     ``profile`` scopes multiplexed gateways to the bot identity that owned the failed send (``None`` =
     primary/default adapter); unowned rows and rows owned by another process are left for the
     startup/dead-owner sweep. Startup recovery ignores rows owned by a live gateway, so a response
     rejected with ``send_path_degraded`` would stay stranded when only the adapter reconnects; this closes
-    that gap without weakening ownership: only rows stamped to this exact process instance, only
-    allowlisted transient errors, same attempts/staleness bounds, every update guarded by the prior owner
-    stamp and ``failed`` state. Claimed rows always carry a marker (the failed send's ack is not safe to
+    that gap without weakening ownership: only rows stamped to this exact process instance, only rows
+    past their ``retry_not_before`` deadline, same attempts/staleness bounds, every update guarded by the
+    prior owner stamp and ``failed`` state. Claimed rows always carry a marker (the failed send's ack is not safe to
     infer): the reconnect one, or the rate-limit one for a flood-refused row."""
     now, (pid, started) = now if now is not None else time.time(), _owner_stamp()
     if started is None:  # PID alone cannot distinguish this process from a stale row left after PID
@@ -411,8 +429,9 @@ def sweep_failed_for_runtime(platform: str, now: Optional[float] = None, *,
         for (oid, session_key, row_platform, chat_id, thread_id, content, attempts, created_at,
              owner_pid, owner_started_at, last_error, adapter_profile, updated_at) in rows:
             # Exact process-start matching prevents PID reuse from stealing work.
+            due = retry_not_before(updated_at, last_error, attempts)
             if (adapter_profile != expected_profile or owner_pid != pid or owner_started_at != started
-                    or not _runtime_retryable(last_error)):
+                    or due is None):
                 continue
             owner_guard = (now, oid, owner_pid, owner_started_at)
             if attempts >= MAX_ATTEMPTS or (now - created_at) > STALE_AFTER_SECONDS:  # exhausted -> abandoned
@@ -422,8 +441,8 @@ def sweep_failed_for_runtime(platform: str, now: Optional[float] = None, *,
                        WHERE obligation_id=? AND state='failed'
                          AND owner_pid IS ? AND owner_started_at IS ?""", owner_guard)
                 continue
-            if is_flood_error(last_error) and now < flood_not_before(updated_at, last_error):
-                continue  # the platform's wait has not passed; the flood timer comes back for it
+            if now < due:
+                continue  # the platform's wait or the backoff has not passed; the timer comes back for it
             # The claim clears the stale error: this is a fresh attempt, and if it is interrupted the next
             # boot must see 'attempting' with no proof of non-delivery, hence the marker.
             cursor = conn.execute(
@@ -441,11 +460,11 @@ def sweep_failed_for_runtime(platform: str, now: Optional[float] = None, *,
     return claimed
 
 
-def pending_flood_retries(now: Optional[float] = None) -> List[Dict[str, Any]]:
-    """This process's flood-refused rows that still await redelivery, one entry per adapter identity
-    with the earliest deadline (``not_before``). The runner arms one redelivery timer per entry, so a
-    row adopted at boot, skipped because its wait had not passed, or refused again is never stranded.
-    Rows past the attempts cap or stale cutoff are left for the sweeps to abandon."""
+def pending_retries(now: Optional[float] = None) -> List[Dict[str, Any]]:
+    """This process's failed rows that still await redelivery, one entry per adapter identity with the
+    earliest deadline (``not_before``). The runner arms one redelivery timer per entry, so a row adopted
+    at boot, skipped because its wait had not passed, or rejected again is never stranded. Rows past the
+    attempts cap or stale cutoff are left for the sweeps to abandon."""
     now, (pid, started) = now if now is not None else time.time(), _owner_stamp()
     if started is None:
         return []
@@ -456,9 +475,9 @@ def pending_flood_retries(now: Optional[float] = None) -> List[Dict[str, Any]]:
                WHERE state='failed' AND owner_pid IS ? AND owner_started_at IS ?""", (pid, started)).fetchall()
     earliest: Dict[tuple, float] = {}
     for platform, adapter_profile, updated_at, last_error, attempts, created_at in rows:
-        if not is_flood_error(last_error) or attempts >= MAX_ATTEMPTS or (now - created_at) > STALE_AFTER_SECONDS:
+        due = retry_not_before(updated_at, last_error, attempts)
+        if due is None or attempts >= MAX_ATTEMPTS or (now - created_at) > STALE_AFTER_SECONDS:
             continue
-        due = flood_not_before(updated_at, last_error)
         key = (platform, adapter_profile or "default")
         if key not in earliest or due < earliest[key]:
             earliest[key] = due
diff --git a/gateway/platforms/base.py b/gateway/platforms/base.py
index 00cb65741f..a2d833275f 100644
--- a/gateway/platforms/base.py
+++ b/gateway/platforms/base.py
@@ -4004,11 +4004,11 @@ class BasePlatformAdapter(ABC):
         delivery_adapter: "BasePlatformAdapter") -> None:
         """Mark the ledger row delivered/failed (best-effort). On ``send_path_degraded`` with a
         replacement adapter live, trigger another redelivery sweep (the watcher's may have run
-        before this failure landed; atomic claiming keeps it idempotent). On a flood-control refusal
-        arm the runner's timed redelivery, so the reply goes out once the penalty has passed instead
-        of waiting for the next restart."""
+        before this failure landed; atomic claiming keeps it idempotent). On any other rejection arm
+        the runner's timed redelivery, so the reply goes out once the flood penalty or the retry
+        backoff has passed instead of waiting for the next restart (#91653)."""
         try:
-            from gateway.delivery_ledger import is_flood_error, mark_delivered, mark_failed
+            from gateway.delivery_ledger import mark_delivered, mark_failed
             if getattr(result, "success", False):
                 await asyncio.to_thread(mark_delivered, obligation_id)
                 return
@@ -4021,7 +4021,7 @@ class BasePlatformAdapter(ABC):
                 if live is not delivery_adapter and callable(redeliver):
                     await redeliver(event.source.platform,
                                     profile=getattr(delivery_adapter, "_owner_profile", None))
-            elif is_flood_error(error):
+            else:
                 schedule = getattr(self.gateway_runner, "_schedule_flood_redelivery", None)
                 if callable(schedule):
                     schedule(event.source.platform,
diff --git a/gateway/run_startup.py b/gateway/run_startup.py
index cb7e045690..ca06c85794 100644
--- a/gateway/run_startup.py
+++ b/gateway/run_startup.py
@@ -337,7 +337,7 @@ class GatewayStartupMixin:
 
     def _schedule_flood_redelivery(self, platform, *, profile: Optional[str] = None) -> None:
         """Wake one deadline-driven ledger worker per bot identity, never sleep in a send."""
-        from gateway.delivery_ledger import flood_retry_delay, pending_flood_retries
+        from gateway.delivery_ledger import flood_retry_delay, pending_retries
         target = platform if isinstance(platform, Platform) else Platform(str(platform))
         key = (target.value, profile or "default")
         pending = getattr(self, "_flood_redelivery_tasks", None)
@@ -356,7 +356,7 @@ class GatewayStartupMixin:
             try:
                 while getattr(self, "_running", False):
                     wake.clear()
-                    waiting = await asyncio.to_thread(pending_flood_retries)
+                    waiting = await asyncio.to_thread(pending_retries)
                     deadlines = [r["not_before"] for r in waiting
                                  if (r["platform"], r["profile"]) == key]
                     if not deadlines:
@@ -383,9 +383,9 @@ class GatewayStartupMixin:
             self._track_task_in(background, task)
 
     async def _arm_flood_timers_for_waiting_rows(self) -> None:
-        """Recover adopted, newly refused and unsent released rows without blocking the loop."""
-        from gateway.delivery_ledger import pending_flood_retries
-        for row in await asyncio.to_thread(pending_flood_retries):
+        """Recover adopted, newly refused/rejected and unsent released rows without blocking the loop."""
+        from gateway.delivery_ledger import pending_retries
+        for row in await asyncio.to_thread(pending_retries):
             self._schedule_flood_redelivery(row["platform"], profile=row["profile"])
 
     async def _redeliver_claimed_obligations(self, claimed: list) -> int:
@@ -429,8 +429,8 @@ class GatewayStartupMixin:
                     await asyncio.to_thread(
                         mark_failed, row["obligation_id"], str(getattr(result, "error", "") or "send failed")
                     )
-        # Whatever is still waiting on a flood penalty (adopted at boot, skipped as not yet due, refused
-        # again just now) gets a timer, so no flood-refused reply waits for the next restart.
+        # Whatever is still waiting on a flood penalty or a retry backoff (adopted at boot, skipped as not
+        # yet due, refused again just now) gets a timer, so no rejected reply waits for the next restart.
         with _log_suppressed(logging.DEBUG, "arming flood redelivery timers failed", exc_info=True):
             await self._arm_flood_timers_for_waiting_rows()
         return redelivered
diff --git a/tests/gateway/test_delivery_ledger.py b/tests/gateway/test_delivery_ledger.py
index 28fb20e1cc..1925b65a29 100644
--- a/tests/gateway/test_delivery_ledger.py
+++ b/tests/gateway/test_delivery_ledger.py
@@ -179,10 +179,34 @@ class TestRuntimeFailedSweep:
         _record(platform="telegram")
         dl.mark_failed("ob-1", "Forbidden: bot was blocked by the user")
 
-        assert dl.sweep_failed_for_runtime("telegram") == []
+        assert dl.sweep_failed_for_runtime("telegram", now=time.time() + 10_000) == []
         assert _row("ob-1")["state"] == "failed"
         assert _row("ob-1")["attempts"] == 0
 
+    def test_other_rejection_is_claimed_only_after_its_backoff(self):
+        _record(platform="telegram")
+        dl.mark_failed("ob-1", "503 Service Unavailable")
+        with dl._connect() as conn:
+            conn.execute("UPDATE delivery_obligations SET attempts=1, updated_at=1000.0 WHERE obligation_id='ob-1'")
+
+        assert dl.sweep_failed_for_runtime("telegram", now=1000.0 + 60) == []
+        assert dl.pending_retries(now=1000.0 + 60) == [
+            {"platform": "telegram", "profile": "default", "not_before": 1000.0 + 120}]
+        claimed = dl.sweep_failed_for_runtime("telegram", now=1000.0 + 121)
+        assert [row["obligation_id"] for row in claimed] == ["ob-1"]
+        assert claimed[0]["needs_marker"] is True
+        assert _row("ob-1")["state"] == "attempting"
+
+    def test_other_rejection_at_attempt_cap_is_abandoned_not_claimed(self):
+        _record(platform="telegram")
+        dl.mark_failed("ob-1", "503 Service Unavailable")
+        with dl._connect() as conn:
+            conn.execute("UPDATE delivery_obligations SET attempts=?, updated_at=1000.0 WHERE obligation_id='ob-1'",
+                         (dl.MAX_ATTEMPTS,))
+
+        assert dl.sweep_failed_for_runtime("telegram", now=1000.0 + 10_000) == []
+        assert _row("ob-1")["state"] == "abandoned"
+
     def test_claim_is_platform_scoped_and_not_reclaimed_while_attempting(self):
         _record(platform="telegram")
         dl.mark_failed("ob-1", "send_path_degraded")

From ea49593edacac7fb697656bd3c236e634852c1fa Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:07:16 +0530
Subject: [PATCH 070/190] docs(gateway): say rejected final sends are retried
 with a backoff

The messaging guide described automatic redelivery only for flood-control
refusals; since the ledger now retries any rejection with a backoff, one
bullet says so and names the exception (a permanently unreachable chat).
---
 website/docs/user-guide/messaging/index.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/website/docs/user-guide/messaging/index.md b/website/docs/user-guide/messaging/index.md
index 9a06c58388..339c9b3f77 100644
--- a/website/docs/user-guide/messaging/index.md
+++ b/website/docs/user-guide/messaging/index.md
@@ -296,6 +296,9 @@ Semantics are honest at-least-once:
   attempt or re-running the agent. Retries retain the original bot profile, chat
   and thread. A rate-limit recovery prefix warns that earlier chunks may already
   have arrived; the ledger cannot infer partial delivery from message length.
+- Any other rejected final send (a platform 5xx, an unclassified error) is retried the same
+  way after a growing backoff (30 s, 2 min, 10 min); a permanently unreachable chat (blocked
+  bot, deleted group) is not retried.
 - Redelivery is bounded: 3 attempts, 24-hour freshness, then the row is
   abandoned. Delivered rows are pruned after 7 days.
 

From 807435ac1ec116c13452301b235f3b62a4144fcc Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:32:19 +0530
Subject: [PATCH 071/190] fix(gateway): the redelivery timer never spends a
 row's last attempt
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review on #91655 (@ehz0ah): a fixed 30/120/600 s schedule against an outage
that lasts hours burns the whole MAX_ATTEMPTS budget in ~12 minutes and the
row becomes `abandoned` — worse than before, when it at least stayed `failed`
and was recovered at the next restart.

`retry_not_before` now returns None once a row has spent MAX_ATTEMPTS - 1
attempts on an unclassified rejection, so the in-process timer stops arming
for it and the runtime sweep leaves it `failed` for the boot sweep, whose
adapter reconnect is a real recovery signal. Flood refusals and allowlisted
reconnect errors keep their existing budget handling.
---
 gateway/delivery_ledger.py            | 15 ++++++++++-----
 tests/gateway/test_delivery_ledger.py | 10 +++++++---
 2 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/gateway/delivery_ledger.py b/gateway/delivery_ledger.py
index e406ef7470..3aeec9d6a3 100644
--- a/gateway/delivery_ledger.py
+++ b/gateway/delivery_ledger.py
@@ -142,9 +142,12 @@ def flood_not_before(updated_at: Any, last_error: Any) -> float:
 
 
 def retry_not_before(updated_at: Any, last_error: Any, attempts: Any) -> Optional[float]:
-    """Earliest moment a failed row may be resent, or ``None`` for a row that must never be: a flood
-    refusal keeps the platform's own wait, an allowlisted reconnect error is due at once, a whole-chat
-    death is final, and any other rejection backs off by the attempts already spent."""
+    """Earliest moment a failed row may be resent, or ``None`` for a row the runtime must leave alone:
+    a flood refusal keeps the platform's own wait, an allowlisted reconnect error is due at once, a
+    whole-chat death is final, and any other rejection backs off by the attempts already spent — but
+    never spends the LAST budgeted attempt. An unclassified outage can outlast any timer, and a row
+    the timer abandoned would be lost for good; leaving one attempt keeps it recoverable by the boot
+    sweep after a restart, which is a real recovery signal."""
     if is_flood_error(last_error):
         return flood_not_before(updated_at, last_error)
     text = str(last_error or "").strip().lower()
@@ -152,8 +155,10 @@ def retry_not_before(updated_at: Any, last_error: Any, attempts: Any) -> Optiona
         return _failed_stamp(updated_at)
     if classify_dead_error(text):
         return None
-    backoff = _RETRY_BACKOFF_SECONDS[min(int(attempts or 0), len(_RETRY_BACKOFF_SECONDS) - 1)]
-    return _failed_stamp(updated_at) + backoff
+    spent = int(attempts or 0)
+    if spent >= MAX_ATTEMPTS - 1:
+        return None
+    return _failed_stamp(updated_at) + _RETRY_BACKOFF_SECONDS[min(spent, len(_RETRY_BACKOFF_SECONDS) - 1)]
 
 
 def _db_path():
diff --git a/tests/gateway/test_delivery_ledger.py b/tests/gateway/test_delivery_ledger.py
index 1925b65a29..cabb47f970 100644
--- a/tests/gateway/test_delivery_ledger.py
+++ b/tests/gateway/test_delivery_ledger.py
@@ -197,15 +197,19 @@ class TestRuntimeFailedSweep:
         assert claimed[0]["needs_marker"] is True
         assert _row("ob-1")["state"] == "attempting"
 
-    def test_other_rejection_at_attempt_cap_is_abandoned_not_claimed(self):
+    def test_other_rejection_keeps_the_last_attempt_for_a_restart(self):
+        """The in-process timer never spends the final budgeted attempt: an outage can outlast any
+        backoff, and a row the timer abandoned would be lost for good (review on #91655)."""
         _record(platform="telegram")
         dl.mark_failed("ob-1", "503 Service Unavailable")
         with dl._connect() as conn:
             conn.execute("UPDATE delivery_obligations SET attempts=?, updated_at=1000.0 WHERE obligation_id='ob-1'",
-                         (dl.MAX_ATTEMPTS,))
+                         (dl.MAX_ATTEMPTS - 1,))
 
         assert dl.sweep_failed_for_runtime("telegram", now=1000.0 + 10_000) == []
-        assert _row("ob-1")["state"] == "abandoned"
+        assert dl.pending_retries(now=1000.0 + 10_000) == []
+        assert _row("ob-1")["state"] == "failed"
+        assert _row("ob-1")["attempts"] == dl.MAX_ATTEMPTS - 1
 
     def test_claim_is_platform_scoped_and_not_reclaimed_while_attempting(self):
         _record(platform="telegram")

From 07a1d55d33738b9e7b9baf0b93d45d5ea2fb2d31 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:57:46 +0530
Subject: [PATCH 072/190] fix(gateway): reconnect-only rows stay off the
 redelivery timer

Gate review on the stack:

- A runtime claim released because the adapter was gone comes back as `failed`
  with `send_path_degraded`, a fresh `updated_at` and its attempt refunded.
  `pending_retries` listed it as due immediately, so the redelivery worker would
  claim and release it every ~2 s for as long as the adapter stayed absent, never
  bounded by the attempts cap. Such rows are reconnect-driven: `pending_retries`
  skips them and only the reconnect sweep re-claims them.
- With the last attempt reserved for the boot sweep only two in-process retries can
  happen, so the 600 s backoff tier was unreachable and the docs promised a
  "30 s, 2 min, 10 min" schedule the code never ran. Two tiers, asserted against
  MAX_ATTEMPTS, and the docs say what happens.
- `_finish_ledger_delivery` no longer wakes the timer for a dead chat (blocked bot,
  deleted group): the ledger would never retry it, so the wake was a wasted task and
  a full pending-rows scan per dead send.
- The runtime sweep classifies a row's error only after the ownership filter, so
  rows this process can never claim skip the classifier under the ledger lock.
---
 gateway/delivery_ledger.py                 | 15 +++++++++++----
 gateway/platforms/base.py                  |  3 ++-
 tests/gateway/test_delivery_ledger.py      |  9 +++++++++
 website/docs/user-guide/messaging/index.md |  5 +++--
 4 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/gateway/delivery_ledger.py b/gateway/delivery_ledger.py
index 3aeec9d6a3..0bda393f3d 100644
--- a/gateway/delivery_ledger.py
+++ b/gateway/delivery_ledger.py
@@ -55,7 +55,9 @@ FLOOD_MARKER = ("♻️ Recovered reply — the messaging platform's rate limit
 # with the attempts already spent, so a platform-side outage is not hammered by the redelivery timer.
 # A whole-chat death (blocked bot, deleted group, deactivated user) is never retried: the target is gone.
 _RUNTIME_RETRYABLE_ERRORS = frozenset({"send_path_degraded"})
-_RETRY_BACKOFF_SECONDS = (30.0, 120.0, 600.0)
+# One tier per in-process retry; the last budgeted attempt is left to the boot sweep (retry_not_before).
+_RETRY_BACKOFF_SECONDS = (30.0, 120.0)
+assert len(_RETRY_BACKOFF_SECONDS) == MAX_ATTEMPTS - 1
 
 # A final send the platform refused with flood control is the other transient case: a 429 means the
 # refused request was never accepted, and the platform said how long to wait. Adapters fail such sends
@@ -158,7 +160,7 @@ def retry_not_before(updated_at: Any, last_error: Any, attempts: Any) -> Optiona
     spent = int(attempts or 0)
     if spent >= MAX_ATTEMPTS - 1:
         return None
-    return _failed_stamp(updated_at) + _RETRY_BACKOFF_SECONDS[min(spent, len(_RETRY_BACKOFF_SECONDS) - 1)]
+    return _failed_stamp(updated_at) + _RETRY_BACKOFF_SECONDS[spent]
 
 
 def _db_path():
@@ -434,9 +436,10 @@ def sweep_failed_for_runtime(platform: str, now: Optional[float] = None, *,
         for (oid, session_key, row_platform, chat_id, thread_id, content, attempts, created_at,
              owner_pid, owner_started_at, last_error, adapter_profile, updated_at) in rows:
             # Exact process-start matching prevents PID reuse from stealing work.
+            if adapter_profile != expected_profile or owner_pid != pid or owner_started_at != started:
+                continue
             due = retry_not_before(updated_at, last_error, attempts)
-            if (adapter_profile != expected_profile or owner_pid != pid or owner_started_at != started
-                    or due is None):
+            if due is None:
                 continue
             owner_guard = (now, oid, owner_pid, owner_started_at)
             if attempts >= MAX_ATTEMPTS or (now - created_at) > STALE_AFTER_SECONDS:  # exhausted -> abandoned
@@ -480,6 +483,10 @@ def pending_retries(now: Optional[float] = None) -> List[Dict[str, Any]]:
                WHERE state='failed' AND owner_pid IS ? AND owner_started_at IS ?""", (pid, started)).fetchall()
     earliest: Dict[tuple, float] = {}
     for platform, adapter_profile, updated_at, last_error, attempts, created_at in rows:
+        # Reconnect-only rows (a claim released because the adapter was gone) are re-claimed by the
+        # reconnect sweep; a timer would claim and release them every tick until the adapter is back.
+        if str(last_error or "").strip().lower() in _RUNTIME_RETRYABLE_ERRORS:
+            continue
         due = retry_not_before(updated_at, last_error, attempts)
         if due is None or attempts >= MAX_ATTEMPTS or (now - created_at) > STALE_AFTER_SECONDS:
             continue
diff --git a/gateway/platforms/base.py b/gateway/platforms/base.py
index a2d833275f..935ff4878a 100644
--- a/gateway/platforms/base.py
+++ b/gateway/platforms/base.py
@@ -4008,6 +4008,7 @@ class BasePlatformAdapter(ABC):
         the runner's timed redelivery, so the reply goes out once the flood penalty or the retry
         backoff has passed instead of waiting for the next restart (#91653)."""
         try:
+            from gateway.dead_targets import classify_dead_error
             from gateway.delivery_ledger import mark_delivered, mark_failed
             if getattr(result, "success", False):
                 await asyncio.to_thread(mark_delivered, obligation_id)
@@ -4021,7 +4022,7 @@ class BasePlatformAdapter(ABC):
                 if live is not delivery_adapter and callable(redeliver):
                     await redeliver(event.source.platform,
                                     profile=getattr(delivery_adapter, "_owner_profile", None))
-            else:
+            elif classify_dead_error(error) is None:  # a dead chat is never retried: no timer to wake
                 schedule = getattr(self.gateway_runner, "_schedule_flood_redelivery", None)
                 if callable(schedule):
                     schedule(event.source.platform,
diff --git a/tests/gateway/test_delivery_ledger.py b/tests/gateway/test_delivery_ledger.py
index cabb47f970..f07b9da7eb 100644
--- a/tests/gateway/test_delivery_ledger.py
+++ b/tests/gateway/test_delivery_ledger.py
@@ -211,6 +211,15 @@ class TestRuntimeFailedSweep:
         assert _row("ob-1")["state"] == "failed"
         assert _row("ob-1")["attempts"] == dl.MAX_ATTEMPTS - 1
 
+    def test_reconnect_only_row_is_never_timer_driven(self):
+        """A claim released because the adapter was gone comes back as `send_path_degraded` with a
+        fresh stamp; only the reconnect sweep may re-claim it, or a timer would loop every tick."""
+        _record(platform="telegram")
+        dl.mark_failed("ob-1", "send_path_degraded")
+
+        assert dl.pending_retries(now=time.time() + 10_000) == []
+        assert [r["obligation_id"] for r in dl.sweep_failed_for_runtime("telegram")] == ["ob-1"]
+
     def test_claim_is_platform_scoped_and_not_reclaimed_while_attempting(self):
         _record(platform="telegram")
         dl.mark_failed("ob-1", "send_path_degraded")
diff --git a/website/docs/user-guide/messaging/index.md b/website/docs/user-guide/messaging/index.md
index 339c9b3f77..7a02abced6 100644
--- a/website/docs/user-guide/messaging/index.md
+++ b/website/docs/user-guide/messaging/index.md
@@ -297,8 +297,9 @@ Semantics are honest at-least-once:
   and thread. A rate-limit recovery prefix warns that earlier chunks may already
   have arrived; the ledger cannot infer partial delivery from message length.
 - Any other rejected final send (a platform 5xx, an unclassified error) is retried the same
-  way after a growing backoff (30 s, 2 min, 10 min); a permanently unreachable chat (blocked
-  bot, deleted group) is not retried.
+  way after a growing backoff (30 s, then 2 min); the last budgeted attempt is left for the
+  next gateway start, so an outage that outlasts the timer never strands the reply. A
+  permanently unreachable chat (blocked bot, deleted group) is not retried.
 - Redelivery is bounded: 3 attempts, 24-hour freshness, then the row is
   abandoned. Delivered rows are pruned after 7 days.
 

From 877848d2f32cc0c8126abe9032e3ced5aa6f0370 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 01:12:13 +0530
Subject: [PATCH 073/190] fix(gateway): a released non-flood claim becomes
 reconnect-only

Gate review: releasing an undispatched runtime claim kept its pre-claim
error ("503 ..."), so the redelivery timer re-armed and claimed/released
the row every tier for as long as the adapter was absent - the loop the
previous commit closed for `send_path_degraded` rows only. Only a flood
row keeps its error (the platform wait must be honoured); every other
row is released as reconnect-only and re-claimed by the reconnect sweep.
`is_reconnect_only()` replaces the three spellings of that predicate.
---
 gateway/delivery_ledger.py | 9 +++++++--
 gateway/platforms/base.py  | 4 ++--
 gateway/run_startup.py     | 8 +++++++-
 3 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/gateway/delivery_ledger.py b/gateway/delivery_ledger.py
index 0bda393f3d..255ca60d09 100644
--- a/gateway/delivery_ledger.py
+++ b/gateway/delivery_ledger.py
@@ -93,6 +93,11 @@ def _raw_flood_wait(text: str) -> Optional[float]:
         return None
 
 
+def is_reconnect_only(error: Any) -> bool:
+    """True for a row that only an adapter reconnect may retry (no timer, no backoff)."""
+    return str(error or "").strip().lower() in _RUNTIME_RETRYABLE_ERRORS
+
+
 def is_flood_error(error: Any) -> bool:
     """True for a flood refusal: the adapters' fail-closed ``flood_control:<seconds>`` result, or a
     row still carrying the platform's own flood wording (see ``_RAW_FLOOD_RE``)."""
@@ -153,7 +158,7 @@ def retry_not_before(updated_at: Any, last_error: Any, attempts: Any) -> Optiona
     if is_flood_error(last_error):
         return flood_not_before(updated_at, last_error)
     text = str(last_error or "").strip().lower()
-    if text in _RUNTIME_RETRYABLE_ERRORS:
+    if is_reconnect_only(text):
         return _failed_stamp(updated_at)
     if classify_dead_error(text):
         return None
@@ -485,7 +490,7 @@ def pending_retries(now: Optional[float] = None) -> List[Dict[str, Any]]:
     for platform, adapter_profile, updated_at, last_error, attempts, created_at in rows:
         # Reconnect-only rows (a claim released because the adapter was gone) are re-claimed by the
         # reconnect sweep; a timer would claim and release them every tick until the adapter is back.
-        if str(last_error or "").strip().lower() in _RUNTIME_RETRYABLE_ERRORS:
+        if is_reconnect_only(last_error):
             continue
         due = retry_not_before(updated_at, last_error, attempts)
         if due is None or attempts >= MAX_ATTEMPTS or (now - created_at) > STALE_AFTER_SECONDS:
diff --git a/gateway/platforms/base.py b/gateway/platforms/base.py
index 935ff4878a..83b8a03985 100644
--- a/gateway/platforms/base.py
+++ b/gateway/platforms/base.py
@@ -4009,13 +4009,13 @@ class BasePlatformAdapter(ABC):
         backoff has passed instead of waiting for the next restart (#91653)."""
         try:
             from gateway.dead_targets import classify_dead_error
-            from gateway.delivery_ledger import mark_delivered, mark_failed
+            from gateway.delivery_ledger import is_reconnect_only, mark_delivered, mark_failed
             if getattr(result, "success", False):
                 await asyncio.to_thread(mark_delivered, obligation_id)
                 return
             error = str(getattr(result, "error", "") or "")
             await asyncio.to_thread(mark_failed, obligation_id, error)
-            if error == "send_path_degraded":
+            if is_reconnect_only(error):
                 redeliver = getattr(
                     self.gateway_runner, "_redeliver_failed_obligations_for_platform", None)
                 live = self._final_delivery_adapter(event.source)
diff --git a/gateway/run_startup.py b/gateway/run_startup.py
index ca06c85794..4686582bb4 100644
--- a/gateway/run_startup.py
+++ b/gateway/run_startup.py
@@ -449,10 +449,16 @@ class GatewayStartupMixin:
             adapter = self.adapters.get(platform)
         # A runtime claim whose reconnect vanished before dispatch is released without spending an
         # attempt; startup claims keep their state (attempts cap + stale cutoff bound retries).
+        # Only a flood row keeps its error (the platform's wait must be honoured); any other row
+        # becomes reconnect-only, or the redelivery timer would claim and release it until the
+        # adapter is back.
         if adapter is None and row.get("runtime_recovery"):
+            from gateway.delivery_ledger import is_flood_error
+
+            last_error = row.get("last_error")
             await self._release_runtime_claim_quiet(
                 row["obligation_id"], "failed to release undispatched runtime obligation %s",
-                error=row.get("last_error") or "send_path_degraded",
+                error=last_error if is_flood_error(last_error) else "send_path_degraded",
             )
         return adapter
 

From fe89acdeba2622b9a36204d5943098570760fc9e Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Fri, 18 Sep 2026 23:45:32 +0530
Subject: [PATCH 074/190] chore: map gauravsaxena1997 contributor email for the
 #48865 salvage

---
 .../emails/32961153+gauravsaxena1997@users.noreply.github.com   | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 contributors/emails/32961153+gauravsaxena1997@users.noreply.github.com

diff --git a/contributors/emails/32961153+gauravsaxena1997@users.noreply.github.com b/contributors/emails/32961153+gauravsaxena1997@users.noreply.github.com
new file mode 100644
index 0000000000..c2f256b12b
--- /dev/null
+++ b/contributors/emails/32961153+gauravsaxena1997@users.noreply.github.com
@@ -0,0 +1,2 @@
+gauravsaxena1997
+# PR #48865 salvage (anthropic: OAuth sanitizer keeps the docs host; #48860)

From e218f3641c5ebcd4ecd54fc3a884720df85dc924 Mon Sep 17 00:00:00 2001
From: Gaurav Saxena <32961153+gauravsaxena1997@users.noreply.github.com>
Date: Fri, 19 Jun 2026 11:44:08 +0530
Subject: [PATCH 075/190] fix(anthropic): preserve docs URL in OAuth sanitizer

---
 agent/anthropic_adapter.py            |  7 +++++--
 tests/agent/test_anthropic_adapter.py | 25 +++++++++++++++++++++++++
 2 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/agent/anthropic_adapter.py b/agent/anthropic_adapter.py
index aeeed9cfc9..efc88ca206 100644
--- a/agent/anthropic_adapter.py
+++ b/agent/anthropic_adapter.py
@@ -468,9 +468,11 @@ def _oauth_wire_namer(anthropic_tools: List[Dict[str, Any]]):
 
 
 _OAUTH_SYSTEM_REPLACEMENTS = (
-    ("Hermes Agent", "Claude Code"), ("Hermes agent", "Claude Code"),
-    ("hermes-agent", "claude-code"), ("Nous Research", "Anthropic"),
+    ("Hermes Agent", "Claude Code"), ("Hermes agent", "Claude Code"), ("Nous Research", "Anthropic"),
 )
+# The slug is rewritten only as a standalone word: inside the docs host it is an address the
+# model will dereference, and ``claude-code.nousresearch.com`` does not resolve (#48860).
+_OAUTH_SLUG_PATTERN = re.compile(r"\bhermes-agent\b(?!\.nousresearch\.com)")
 
 
 def _apply_claude_code_identity(system, anthropic_tools, anthropic_messages, to_wire):
@@ -487,6 +489,7 @@ def _apply_claude_code_identity(system, anthropic_tools, anthropic_messages, to_
             text = block.get("text", "")
             for old, new in _OAUTH_SYSTEM_REPLACEMENTS:
                 text = text.replace(old, new)
+            text = _OAUTH_SLUG_PATTERN.sub("claude-code", text)
             block["text"] = _apply_oauth_prose_aliases(text)
     for tool in anthropic_tools or []:
         if "name" in tool:
diff --git a/tests/agent/test_anthropic_adapter.py b/tests/agent/test_anthropic_adapter.py
index 5af08b5f36..53d185af15 100644
--- a/tests/agent/test_anthropic_adapter.py
+++ b/tests/agent/test_anthropic_adapter.py
@@ -1897,3 +1897,28 @@ class TestFinalPayloadHasNoBlankTextBlocks:
         )
         image_blocks = [b for b in tool_result_block["content"] if b.get("type") == "image"]
         assert len(image_blocks) == 1
+
+
+def test_oauth_system_prompt_sanitizer_preserves_docs_url():
+    kwargs = build_anthropic_kwargs(
+        model="claude-sonnet-4-20250514",
+        messages=[
+            {
+                "role": "system",
+                "content": (
+                    "Hermes Agent by Nous Research uses hermes-agent skills. "
+                    "Docs: https://hermes-agent.nousresearch.com/docs"
+                ),
+            },
+            {"role": "user", "content": "Hi"},
+        ],
+        tools=None,
+        max_tokens=4096,
+        reasoning_config=None,
+        is_oauth=True,
+    )
+
+    system_text = "\n".join(block["text"] for block in kwargs["system"])
+    assert "Claude Code by Anthropic uses claude-code skills." in system_text
+    assert "https://hermes-agent.nousresearch.com/docs" in system_text
+    assert "claude-code.nousresearch.com" not in system_text

From 75b62813942e3a217724d87bde4e5d62a66673f5 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Fri, 18 Sep 2026 23:50:46 +0530
Subject: [PATCH 076/190] fix(anthropic): OAuth slug rewrite skips paths, repo
 slugs and mailboxes too

The docs host was one instance of a class: every place the ``hermes-agent`` slug
is joined to an address the model dereferences. Subagent briefs naming
``~/.hermes/hermes-agent/venv/bin/python`` came back as ``~/.hermes/claude-code/...``
(a file that does not exist) and ``NousResearch/hermes-agent`` became a repo
nobody owns. Rewrite the slug only when it stands alone in prose: a lookbehind
rejects ``/ . : @ -`` and word characters on the left, a lookahead rejects
``/ . @ -`` and word characters on the right. Product-name prose ("the
hermes-agent skill") is still rewritten as before.

Path class reported by @chazmaniandinkle and @christophcemper on #48860.
---
 agent/anthropic_adapter.py            |  8 +++++---
 tests/agent/test_anthropic_adapter.py | 10 ++++++++--
 2 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/agent/anthropic_adapter.py b/agent/anthropic_adapter.py
index efc88ca206..9347acc466 100644
--- a/agent/anthropic_adapter.py
+++ b/agent/anthropic_adapter.py
@@ -470,9 +470,11 @@ def _oauth_wire_namer(anthropic_tools: List[Dict[str, Any]]):
 _OAUTH_SYSTEM_REPLACEMENTS = (
     ("Hermes Agent", "Claude Code"), ("Hermes agent", "Claude Code"), ("Nous Research", "Anthropic"),
 )
-# The slug is rewritten only as a standalone word: inside the docs host it is an address the
-# model will dereference, and ``claude-code.nousresearch.com`` does not resolve (#48860).
-_OAUTH_SLUG_PATTERN = re.compile(r"\bhermes-agent\b(?!\.nousresearch\.com)")
+# The slug is rewritten only as a standalone word. Joined to a host, path, repo or mailbox
+# (``hermes-agent.nousresearch.com``, ``~/.hermes/hermes-agent/venv``,
+# ``NousResearch/hermes-agent``) it is an address the model dereferences, and the rewritten
+# form does not exist (#48860).
+_OAUTH_SLUG_PATTERN = re.compile(r"(?<![\w./:@-])hermes-agent(?![\w./@-])")
 
 
 def _apply_claude_code_identity(system, anthropic_tools, anthropic_messages, to_wire):
diff --git a/tests/agent/test_anthropic_adapter.py b/tests/agent/test_anthropic_adapter.py
index 53d185af15..f0ef4abe0f 100644
--- a/tests/agent/test_anthropic_adapter.py
+++ b/tests/agent/test_anthropic_adapter.py
@@ -1907,7 +1907,9 @@ def test_oauth_system_prompt_sanitizer_preserves_docs_url():
                 "role": "system",
                 "content": (
                     "Hermes Agent by Nous Research uses hermes-agent skills. "
-                    "Docs: https://hermes-agent.nousresearch.com/docs"
+                    "Docs: https://hermes-agent.nousresearch.com/docs ; "
+                    "interpreter ~/.hermes/hermes-agent/venv/bin/python ; "
+                    "source github.com/NousResearch/hermes-agent"
                 ),
             },
             {"role": "user", "content": "Hi"},
@@ -1921,4 +1923,8 @@ def test_oauth_system_prompt_sanitizer_preserves_docs_url():
     system_text = "\n".join(block["text"] for block in kwargs["system"])
     assert "Claude Code by Anthropic uses claude-code skills." in system_text
     assert "https://hermes-agent.nousresearch.com/docs" in system_text
-    assert "claude-code.nousresearch.com" not in system_text
+    # Paths and repo slugs are addresses too: a subagent told to run
+    # ``~/.hermes/claude-code/venv/bin/python`` fails on a file that does not exist.
+    assert "~/.hermes/hermes-agent/venv/bin/python" in system_text
+    assert "github.com/NousResearch/hermes-agent" in system_text
+    assert "claude-code" not in system_text.replace("claude-code skills", "")

From f7676e7ff1f5d57d74e7c3bfe48f21feb8537c71 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:17:25 +0530
Subject: [PATCH 077/190] fix(anthropic): quoted slugs stay identifiers; a
 sentence-final dot is prose
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two boundary cases from review: excluding every `.` from the right boundary let
"…run by hermes-agent." leak the raw slug, so only a dot FOLLOWED by a word char
(host, extension) now counts as a joiner. And the shipped prompt says
`skill_view(name='hermes-agent')` / "the `hermes-agent` skill" — a quoted slug is
a name the model dereferences, so quote characters join both boundaries. The
regression covers a mailbox, the quoted identifier and the sentence-final dot.
---
 agent/anthropic_adapter.py            | 10 +++++-----
 tests/agent/test_anthropic_adapter.py |  8 ++++++--
 2 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/agent/anthropic_adapter.py b/agent/anthropic_adapter.py
index 9347acc466..228f4d5e45 100644
--- a/agent/anthropic_adapter.py
+++ b/agent/anthropic_adapter.py
@@ -470,11 +470,11 @@ def _oauth_wire_namer(anthropic_tools: List[Dict[str, Any]]):
 _OAUTH_SYSTEM_REPLACEMENTS = (
     ("Hermes Agent", "Claude Code"), ("Hermes agent", "Claude Code"), ("Nous Research", "Anthropic"),
 )
-# The slug is rewritten only as a standalone word. Joined to a host, path, repo or mailbox
-# (``hermes-agent.nousresearch.com``, ``~/.hermes/hermes-agent/venv``,
-# ``NousResearch/hermes-agent``) it is an address the model dereferences, and the rewritten
-# form does not exist (#48860).
-_OAUTH_SLUG_PATTERN = re.compile(r"(?<![\w./:@-])hermes-agent(?![\w./@-])")
+# The slug is rewritten only as a standalone prose word. Joined to a host, path, repo, mailbox
+# or quoted as an identifier (``hermes-agent.nousresearch.com``, ``~/.hermes/hermes-agent/venv``,
+# ``NousResearch/hermes-agent``, ``skill_view(name='hermes-agent')``) it is an address the model
+# dereferences, and the rewritten form does not exist (#48860). A sentence-final ``.`` is prose.
+_OAUTH_SLUG_PATTERN = re.compile(r"""(?<![\w./:@'"`-])hermes-agent(?![\w/@'"`-]|\.\w)""")
 
 
 def _apply_claude_code_identity(system, anthropic_tools, anthropic_messages, to_wire):
diff --git a/tests/agent/test_anthropic_adapter.py b/tests/agent/test_anthropic_adapter.py
index f0ef4abe0f..97684baffc 100644
--- a/tests/agent/test_anthropic_adapter.py
+++ b/tests/agent/test_anthropic_adapter.py
@@ -1909,7 +1909,8 @@ def test_oauth_system_prompt_sanitizer_preserves_docs_url():
                     "Hermes Agent by Nous Research uses hermes-agent skills. "
                     "Docs: https://hermes-agent.nousresearch.com/docs ; "
                     "interpreter ~/.hermes/hermes-agent/venv/bin/python ; "
-                    "source github.com/NousResearch/hermes-agent"
+                    "source github.com/NousResearch/hermes-agent ; mail hermes-agent@example.com ; "
+                    "skill_view(name='hermes-agent') ; built by hermes-agent."
                 ),
             },
             {"role": "user", "content": "Hi"},
@@ -1927,4 +1928,7 @@ def test_oauth_system_prompt_sanitizer_preserves_docs_url():
     # ``~/.hermes/claude-code/venv/bin/python`` fails on a file that does not exist.
     assert "~/.hermes/hermes-agent/venv/bin/python" in system_text
     assert "github.com/NousResearch/hermes-agent" in system_text
-    assert "claude-code" not in system_text.replace("claude-code skills", "")
+    assert "hermes-agent@example.com" in system_text
+    assert "skill_view(name='hermes-agent')" in system_text  # a quoted slug is an identifier
+    assert "built by claude-code." in system_text  # a sentence-final dot is prose
+    assert system_text.count("claude-code") == 2

From ae62e832cc355b2e7d3ff9e546ab98e5b75f0bb8 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:42:27 +0530
Subject: [PATCH 078/190] fix(anthropic): a possessive 'hermes-agent's' is
 prose and is still rewritten

Refusing every apostrophe on the right also protected the possessive, leaking
the raw slug in ordinary prose. Only an apostrophe that does not start 's'
joins (quoted identifiers such as name='hermes-agent' stay). The test counts
rewrites in the caller's block, not the Claude Code prefix.
---
 agent/anthropic_adapter.py            | 5 +++--
 tests/agent/test_anthropic_adapter.py | 5 +++--
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/agent/anthropic_adapter.py b/agent/anthropic_adapter.py
index 228f4d5e45..a7f73e3cb6 100644
--- a/agent/anthropic_adapter.py
+++ b/agent/anthropic_adapter.py
@@ -473,8 +473,9 @@ _OAUTH_SYSTEM_REPLACEMENTS = (
 # The slug is rewritten only as a standalone prose word. Joined to a host, path, repo, mailbox
 # or quoted as an identifier (``hermes-agent.nousresearch.com``, ``~/.hermes/hermes-agent/venv``,
 # ``NousResearch/hermes-agent``, ``skill_view(name='hermes-agent')``) it is an address the model
-# dereferences, and the rewritten form does not exist (#48860). A sentence-final ``.`` is prose.
-_OAUTH_SLUG_PATTERN = re.compile(r"""(?<![\w./:@'"`-])hermes-agent(?![\w/@'"`-]|\.\w)""")
+# dereferences, and the rewritten form does not exist (#48860). A sentence-final ``.`` and a
+# possessive ``'s`` are prose.
+_OAUTH_SLUG_PATTERN = re.compile(r"""(?<![\w./:@'"`-])hermes-agent(?![\w/@"`-]|\.\w|'(?!s\b))""")
 
 
 def _apply_claude_code_identity(system, anthropic_tools, anthropic_messages, to_wire):
diff --git a/tests/agent/test_anthropic_adapter.py b/tests/agent/test_anthropic_adapter.py
index 97684baffc..c2390dc257 100644
--- a/tests/agent/test_anthropic_adapter.py
+++ b/tests/agent/test_anthropic_adapter.py
@@ -1910,7 +1910,7 @@ def test_oauth_system_prompt_sanitizer_preserves_docs_url():
                     "Docs: https://hermes-agent.nousresearch.com/docs ; "
                     "interpreter ~/.hermes/hermes-agent/venv/bin/python ; "
                     "source github.com/NousResearch/hermes-agent ; mail hermes-agent@example.com ; "
-                    "skill_view(name='hermes-agent') ; built by hermes-agent."
+                    "skill_view(name='hermes-agent') ; hermes-agent's docs ; built by hermes-agent."
                 ),
             },
             {"role": "user", "content": "Hi"},
@@ -1931,4 +1931,5 @@ def test_oauth_system_prompt_sanitizer_preserves_docs_url():
     assert "hermes-agent@example.com" in system_text
     assert "skill_view(name='hermes-agent')" in system_text  # a quoted slug is an identifier
     assert "built by claude-code." in system_text  # a sentence-final dot is prose
-    assert system_text.count("claude-code") == 2
+    assert "claude-code's docs" in system_text  # so is a possessive
+    assert kwargs["system"][-1]["text"].count("claude-code") == 3  # the caller's block, not the CC prefix

From 9f5098c36c496a5e237beb63b0368f7be42b1b04 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 01:02:25 +0530
Subject: [PATCH 079/190] refactor(anthropic): quote characters only mark an
 identifier from the left

A quoted slug never matches because the lookbehind rejects the opening quote,
so the quote classes in the lookahead were dead; drop them.
---
 agent/anthropic_adapter.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/agent/anthropic_adapter.py b/agent/anthropic_adapter.py
index a7f73e3cb6..e93d068129 100644
--- a/agent/anthropic_adapter.py
+++ b/agent/anthropic_adapter.py
@@ -473,9 +473,9 @@ _OAUTH_SYSTEM_REPLACEMENTS = (
 # The slug is rewritten only as a standalone prose word. Joined to a host, path, repo, mailbox
 # or quoted as an identifier (``hermes-agent.nousresearch.com``, ``~/.hermes/hermes-agent/venv``,
 # ``NousResearch/hermes-agent``, ``skill_view(name='hermes-agent')``) it is an address the model
-# dereferences, and the rewritten form does not exist (#48860). A sentence-final ``.`` and a
-# possessive ``'s`` are prose.
-_OAUTH_SLUG_PATTERN = re.compile(r"""(?<![\w./:@'"`-])hermes-agent(?![\w/@"`-]|\.\w|'(?!s\b))""")
+# dereferences, and the rewritten form does not exist (#48860). The OPENING quote marks an
+# identifier; a sentence-final ``.`` or a possessive ``'s`` is prose.
+_OAUTH_SLUG_PATTERN = re.compile(r"""(?<![\w./:@'"`-])hermes-agent(?![\w/@-]|\.\w)""")
 
 
 def _apply_claude_code_identity(system, anthropic_tools, anthropic_messages, to_wire):

From 81cd8755b5e3ae91cefba530461beeffaa42d694 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Fri, 18 Sep 2026 23:54:58 +0530
Subject: [PATCH 080/190] fix(cli): a provider-qualified -m selects that
 provider on both CLI entry paths
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`hermes -m custom:jetson-vllm:nemotron-nano-30b` (and `-z`) kept the configured default
provider and sent the UNSPLIT string as the model name, so the whole prompt reached
api.anthropic.com before a 404 — a local endpoint the user picked never saw the request.
`parse_model_input` already decodes the form; nothing on the startup path called it.

`resolve_startup_model_route`, the owner of startup provider/model decoding, now consumes
the colon-qualified form through `parse_model_input` ahead of the `provider/model` branch,
so HermesCLI picks it up unchanged. The oneshot resolver routes through the same owner
before provider auto-detection instead of only after a direct-alias miss.

Live, config `providers.jetson-vllm` at 127.0.0.1:8000 and `model.provider: anthropic`:
before — HTTP 401 from Anthropic, local sink idle; after — sink receives
POST /v1/chat/completions model=nemotron-nano-30b, Anthropic untouched.

Closes #73943. First reported fix: PR #74082 by @Drexuxux (HermesCLI.__init__ decode); the
seam moved to the startup route owner during the Sep-2026 cli.py decomposition.

Co-authored-by: Drexuxux <drexux0@gmail.com>
---
 hermes_cli/model_switch.py                    | 11 ++++-
 hermes_cli/oneshot.py                         | 11 ++++-
 .../hermes_cli/test_startup_model_routing.py  | 45 +++++++++++++++++++
 3 files changed, 65 insertions(+), 2 deletions(-)

diff --git a/hermes_cli/model_switch.py b/hermes_cli/model_switch.py
index 4f73230bc9..c91daac9a7 100644
--- a/hermes_cli/model_switch.py
+++ b/hermes_cli/model_switch.py
@@ -385,7 +385,16 @@ def resolve_startup_model_route(
         return StartupModelRoute(
             model=direct.model, provider=alias_provider, base_url=direct.base_url, api_key=alias_key or "")
 
-    if explicit_provider or "/" not in raw:
+    if explicit_provider:
+        return None
+    # ``custom:<name>:<model>`` / ``<provider>:<model>`` — the same qualified form ``/model``
+    # accepts. Left undecoded, the configured default provider receives the unsplit string as
+    # the model name and the whole prompt goes to its endpoint before it 404s (#73943).
+    from hermes_cli.models import parse_model_input
+    qualified_provider, qualified_model = parse_model_input(raw, "")
+    if qualified_provider and qualified_model != raw:
+        return StartupModelRoute(model=qualified_model, provider=qualified_provider)
+    if "/" not in raw:
         return None
     prefix, model = (part.strip() for part in raw.split("/", 1))
     if not prefix or not model:
diff --git a/hermes_cli/oneshot.py b/hermes_cli/oneshot.py
index 524a6c2530..c024926e37 100644
--- a/hermes_cli/oneshot.py
+++ b/hermes_cli/oneshot.py
@@ -395,8 +395,8 @@ def _resolve_model_and_provider(cfg: dict, model: Optional[str], provider: Optio
 
     # DIRECT_ALIASES (config.yaml ``model_aliases:``) map a user alias to (model, provider,
     # base_url) for endpoints outside any catalog (local servers, custom proxies, ...).
+    from hermes_cli import model_switch as _ms
     try:
-        from hermes_cli import model_switch as _ms
         _ms._ensure_direct_aliases()
         direct = _ms.DIRECT_ALIASES.get(explicit_model.strip().lower())
     except Exception:
@@ -406,6 +406,15 @@ def _resolve_model_and_provider(cfg: dict, model: Optional[str], provider: Optio
         if isinstance(model_cfg, dict):
             cfg_provider = str(model_cfg.get("provider") or "").strip().lower()
         current_provider = cfg_provider or os.getenv("HERMES_INFERENCE_PROVIDER", "").strip().lower() or "auto"
+        # Same owner as HermesCLI startup: a provider-qualified string (``custom:<name>:<model>``,
+        # ``<provider>/<model>``) selects that provider before auto-detection can hand the unsplit
+        # string to the configured default (#73943).
+        route = _ms.resolve_startup_model_route(
+            explicit_model, current_provider=current_provider,
+            user_providers=cfg.get("providers"), custom_providers=cfg.get("custom_providers"))
+        if route is not None:
+            choice.provider, choice.model = route.provider, route.model
+            return choice
         detected = detect_provider_for_model(explicit_model, current_provider)
         if detected:
             choice.provider, choice.model = detected
diff --git a/tests/hermes_cli/test_startup_model_routing.py b/tests/hermes_cli/test_startup_model_routing.py
index ffa3b902a9..fcec1d29ff 100644
--- a/tests/hermes_cli/test_startup_model_routing.py
+++ b/tests/hermes_cli/test_startup_model_routing.py
@@ -1,5 +1,7 @@
 """Regression tests for startup model/provider routing (#87189)."""
 
+import pytest
+
 from hermes_cli import model_switch
 
 
@@ -149,3 +151,46 @@ def test_model_aliases_dict_entries_are_loaded(monkeypatch):
     assert aliases["localqwen"] == model_switch.DirectAlias(
         "qwen3.5:4b", "custom", "http://localhost:11434/v1"
     )
+
+
+def _write_named_provider(tmp_path, monkeypatch):
+    """A ``providers:`` entry the user selects by the documented ``custom:<name>:<model>`` form."""
+    home = tmp_path / "hermes-home"
+    home.mkdir()
+    (home / "config.yaml").write_text(
+        "model:\n  default: claude-sonnet-4-5\n  provider: anthropic\n"
+        "providers:\n  jetson-vllm:\n    base_url: http://127.0.0.1:8000/v1\n"
+        "    api_key: EMPTY\n    api_mode: chat_completions\n    models: [nemotron-nano-30b]\n"
+    )
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    monkeypatch.setattr(model_switch, "DIRECT_ALIASES", {})
+    from hermes_cli.config import load_config
+    return load_config()
+
+
+def test_startup_route_decodes_custom_colon_qualified_model(tmp_path, monkeypatch):
+    """``custom:<name>:<model>`` selects the named provider instead of leaving the unsplit string
+    to the configured default (#73943: the prompt went to api.anthropic.com before a 404)."""
+    cfg = _write_named_provider(tmp_path, monkeypatch)
+    route = model_switch.resolve_startup_model_route(
+        "custom:jetson-vllm:nemotron-nano-30b", current_provider="anthropic",
+        user_providers=cfg.get("providers"))
+    assert route == model_switch.StartupModelRoute("nemotron-nano-30b", "custom:jetson-vllm", "")
+    # A colon inside a plain model id is not a provider delimiter.
+    assert model_switch.resolve_startup_model_route(
+        "anthropic/claude-3.5-sonnet:beta", current_provider="anthropic",
+        user_providers=cfg.get("providers")) is None
+
+
+def test_oneshot_qualified_model_never_reaches_default_provider(tmp_path, monkeypatch):
+    """``hermes -z -m custom:<name>:<model>`` routes through the same startup owner, so provider
+    auto-detection never hands the qualified string to the configured default (#73943)."""
+    from hermes_cli.oneshot import _resolve_model_and_provider
+
+    cfg = _write_named_provider(tmp_path, monkeypatch)
+    monkeypatch.delenv("HERMES_INFERENCE_MODEL", raising=False)
+    monkeypatch.setattr(
+        "hermes_cli.models.detect_provider_for_model",
+        lambda *_a, **_k: pytest.fail("auto-detection ran on a provider-qualified model"))
+    choice = _resolve_model_and_provider(cfg, "custom:jetson-vllm:nemotron-nano-30b", None)
+    assert (choice.provider, choice.model) == ("custom:jetson-vllm", "nemotron-nano-30b")

From 10767ab099bc4bbdec19398fd23c6e16f2f93114 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:11:54 +0530
Subject: [PATCH 081/190] fix(tui): hermes --tui -m custom:<name>:<model>
 routes through the startup owner too

Third entry path with the same egress: `_resolve_startup_runtime` seeded the model
from HERMES_INFERENCE_MODEL and went straight to static provider detection, so the
qualified string reached the configured default. Route through
`resolve_startup_model_route` first, as HermesCLI and oneshot now do.

Also: an unconfigured `custom:<typo>:<model>` now logs a warning and leaves the
route undecided instead of steering a garbage model id at the bare custom endpoint,
and the redundant `qualified_model != raw` guard is gone.
---
 hermes_cli/model_switch.py                     |  8 +++++++-
 tests/hermes_cli/test_startup_model_routing.py | 18 +++++++++++++-----
 tui_gateway/server.py                          |  9 ++++++++-
 3 files changed, 28 insertions(+), 7 deletions(-)

diff --git a/hermes_cli/model_switch.py b/hermes_cli/model_switch.py
index c91daac9a7..5c7318186e 100644
--- a/hermes_cli/model_switch.py
+++ b/hermes_cli/model_switch.py
@@ -392,7 +392,13 @@ def resolve_startup_model_route(
     # the model name and the whole prompt goes to its endpoint before it 404s (#73943).
     from hermes_cli.models import parse_model_input
     qualified_provider, qualified_model = parse_model_input(raw, "")
-    if qualified_provider and qualified_model != raw:
+    if qualified_provider == "custom" and ":" in qualified_model:
+        # ``custom:<typo>:<model>`` — no such named provider; a bare-custom request with a garbage
+        # model id would be as silent as the default-provider egress this decode prevents.
+        logger.warning("No providers.%s entry configured; ignoring provider prefix in %r",
+                       qualified_model.split(":", 1)[0], raw)
+        return None
+    if qualified_provider:
         return StartupModelRoute(model=qualified_model, provider=qualified_provider)
     if "/" not in raw:
         return None
diff --git a/tests/hermes_cli/test_startup_model_routing.py b/tests/hermes_cli/test_startup_model_routing.py
index fcec1d29ff..363ac4980f 100644
--- a/tests/hermes_cli/test_startup_model_routing.py
+++ b/tests/hermes_cli/test_startup_model_routing.py
@@ -182,15 +182,23 @@ def test_startup_route_decodes_custom_colon_qualified_model(tmp_path, monkeypatc
         user_providers=cfg.get("providers")) is None
 
 
-def test_oneshot_qualified_model_never_reaches_default_provider(tmp_path, monkeypatch):
-    """``hermes -z -m custom:<name>:<model>`` routes through the same startup owner, so provider
-    auto-detection never hands the qualified string to the configured default (#73943)."""
+def test_oneshot_and_tui_qualified_model_never_reaches_default_provider(tmp_path, monkeypatch):
+    """``hermes -z -m custom:<name>:<model>`` and ``hermes --tui -m …`` route through the same
+    startup owner, so provider auto-detection never hands the qualified string to the configured
+    default (#73943)."""
     from hermes_cli.oneshot import _resolve_model_and_provider
+    from tui_gateway import server as tui_server
 
     cfg = _write_named_provider(tmp_path, monkeypatch)
-    monkeypatch.delenv("HERMES_INFERENCE_MODEL", raising=False)
+    monkeypatch.delenv("HERMES_INFERENCE_PROVIDER", raising=False)
+    monkeypatch.delenv("HERMES_TUI_PROVIDER", raising=False)
     monkeypatch.setattr(
         "hermes_cli.models.detect_provider_for_model",
         lambda *_a, **_k: pytest.fail("auto-detection ran on a provider-qualified model"))
-    choice = _resolve_model_and_provider(cfg, "custom:jetson-vllm:nemotron-nano-30b", None)
+    monkeypatch.setattr(
+        "hermes_cli.models.detect_static_provider_for_model",
+        lambda *_a, **_k: pytest.fail("auto-detection ran on a provider-qualified model"))
+    monkeypatch.setenv("HERMES_INFERENCE_MODEL", "custom:jetson-vllm:nemotron-nano-30b")
+    choice = _resolve_model_and_provider(cfg, None, None)
     assert (choice.provider, choice.model) == ("custom:jetson-vllm", "nemotron-nano-30b")
+    assert tui_server._resolve_startup_runtime() == ("nemotron-nano-30b", "custom:jetson-vllm")
diff --git a/tui_gateway/server.py b/tui_gateway/server.py
index 18e42ec42a..47c7c21f90 100644
--- a/tui_gateway/server.py
+++ b/tui_gateway/server.py
@@ -1432,10 +1432,17 @@ def _resolve_startup_runtime() -> tuple[str, str | None]:
     if not (explicit_model := _env_model_seed()):
         return model, None
     with contextlib.suppress(Exception):
+        from hermes_cli.model_switch import resolve_startup_model_route
         from hermes_cli.models import detect_static_provider_for_model
-        cfg = _load_cfg().get("model") or {}
+        full_cfg = _load_cfg()
+        cfg = full_cfg.get("model") or {}
         current_provider = ((str(cfg.get("provider") or "").strip().lower() if isinstance(cfg, dict) else "")
                             or os.environ.get("HERMES_INFERENCE_PROVIDER", "").strip().lower() or "auto")
+        # Same owner as HermesCLI/oneshot: ``custom:<name>:<model>`` selects that provider (#73943).
+        if route := resolve_startup_model_route(
+                explicit_model, current_provider=current_provider,
+                user_providers=full_cfg.get("providers"), custom_providers=full_cfg.get("custom_providers")):
+            return route.model, route.provider
         if detected := detect_static_provider_for_model(explicit_model, current_provider):
             provider, detected_model = detected
             return detected_model, provider

From b2d2cf4e248c68796c14ebc62ee3fd489e5cb6d7 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:59:40 +0530
Subject: [PATCH 082/190] fix(cli): the startup route decodes custom:<name>
 from the caller's providers, not a second config read
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review findings folded: (1) `parse_model_input` resolved the configured
`custom:<name>` ids through its own `load_config()`, so the `user_providers`/
`custom_providers` the three startup callers pass were ignored for this branch
— two config sources for one decision. It now takes `custom_ids` and the route
builds them from its arguments with `custom_provider_slug`, the same identity
`providers:` entries carry everywhere else. (2) The "typo" guard was wrong: it
fired on legitimate bare-custom tags (`custom:qwen3.5:4b`) and its `None` fell
straight back into the default-provider egress the fix exists to prevent. A
bare `custom` route with an unknown id now 404s on the user's own endpoint,
matching `/model`. Docstring lists the `provider:model` form.
---
 hermes_cli/model_switch.py                     | 18 +++++++++---------
 hermes_cli/models.py                           | 12 ++++++++----
 tests/hermes_cli/test_startup_model_routing.py |  6 +++++-
 3 files changed, 22 insertions(+), 14 deletions(-)

diff --git a/hermes_cli/model_switch.py b/hermes_cli/model_switch.py
index 5c7318186e..1df8d9c65c 100644
--- a/hermes_cli/model_switch.py
+++ b/hermes_cli/model_switch.py
@@ -357,7 +357,7 @@ def resolve_startup_model_route(
     raw_model: str, *, explicit_provider: str = "", current_provider: str = "",
     user_providers: Optional[dict] = None,
     custom_providers: Optional[list] = None) -> Optional[StartupModelRoute]:
-    """Resolve aliases and configured ``provider/model`` input at startup.
+    """Resolve aliases, ``provider:model`` and configured ``provider/model`` input at startup.
 
     ``HermesCLI`` is constructed before the interactive ``/model`` pipeline runs; resolving here
     keeps startup from attaching the configured default provider to an explicitly requested
@@ -389,15 +389,15 @@ def resolve_startup_model_route(
         return None
     # ``custom:<name>:<model>`` / ``<provider>:<model>`` — the same qualified form ``/model``
     # accepts. Left undecoded, the configured default provider receives the unsplit string as
-    # the model name and the whole prompt goes to its endpoint before it 404s (#73943).
+    # the model name and the whole prompt goes to its endpoint before it 404s (#73943). The
+    # configured ids come from the caller's config, the same source the ``/`` branch below uses.
     from hermes_cli.models import parse_model_input
-    qualified_provider, qualified_model = parse_model_input(raw, "")
-    if qualified_provider == "custom" and ":" in qualified_model:
-        # ``custom:<typo>:<model>`` — no such named provider; a bare-custom request with a garbage
-        # model id would be as silent as the default-provider egress this decode prevents.
-        logger.warning("No providers.%s entry configured; ignoring provider prefix in %r",
-                       qualified_model.split(":", 1)[0], raw)
-        return None
+    from hermes_cli.providers import custom_provider_slug
+    custom_ids = {custom_provider_slug(str(entry.get("name") or key), str(key))
+                  for key, entry in (user_providers or {}).items() if isinstance(entry, dict)}
+    custom_ids.update(custom_provider_slug(str(entry.get("name") or ""))
+                      for entry in (custom_providers or []) if isinstance(entry, dict) and _clean(entry.get("name")))
+    qualified_provider, qualified_model = parse_model_input(raw, "", custom_ids=custom_ids)
     if qualified_provider:
         return StartupModelRoute(model=qualified_model, provider=qualified_provider)
     if "/" not in raw:
diff --git a/hermes_cli/models.py b/hermes_cli/models.py
index 61ca444e6f..b04a475b5e 100644
--- a/hermes_cli/models.py
+++ b/hermes_cli/models.py
@@ -728,9 +728,12 @@ def list_available_providers() -> list[dict[str, str]]:
         for pid in [p.slug for p in CANONICAL_PROVIDERS] + ["custom"]]
 
 
-def parse_model_input(raw: str, current_provider: str) -> tuple[str, str]:
+def parse_model_input(
+        raw: str, current_provider: str, *, custom_ids: Optional[set[str]] = None) -> tuple[str, str]:
     """Parse ``/model`` input into ``(provider, model)``. The colon is a provider delimiter only when
-    the left side is a known provider/alias, so ``anthropic/claude-3.5-sonnet:beta`` stays a model."""
+    the left side is a known provider/alias, so ``anthropic/claude-3.5-sonnet:beta`` stays a model.
+    ``custom_ids`` is the caller's already-loaded set of configured ``custom:<name>`` ids (default:
+    read from config) so one decision never consults two config sources."""
     stripped = raw.strip()
     colon = stripped.find(":")
     if colon > 0:
@@ -738,9 +741,10 @@ def parse_model_input(raw: str, current_provider: str) -> tuple[str, str]:
         model_part = stripped[colon + 1:].strip()
         if provider_part and model_part and provider_part in _KNOWN_PROVIDER_NAMES:
             if provider_part == "custom":
+                configured = _configured_custom_provider_ids() if custom_ids is None else custom_ids
                 # Longest configured ``custom:<name>`` id that prefixes the input wins.
                 lowered = stripped.lower()
-                for custom_id in sorted(_configured_custom_provider_ids() - {"custom"}, key=len, reverse=True):
+                for custom_id in sorted(configured - {"custom"}, key=len, reverse=True):
                     if lowered.startswith(f"{custom_id.lower()}:"):
                         return custom_id, stripped[len(custom_id) + 1 :].strip()
                 # ``custom:local:qwen`` → ("custom:local", "qwen") for a configured named provider;
@@ -748,7 +752,7 @@ def parse_model_input(raw: str, current_provider: str) -> tuple[str, str]:
                 if ":" in model_part:
                     custom_name, actual_model = (part.strip() for part in model_part.split(":", 1))
                     if custom_name and actual_model:
-                        if f"custom:{custom_name.lower()}" in _configured_custom_provider_ids():
+                        if f"custom:{custom_name.lower()}" in configured:
                             return (f"custom:{custom_name.lower()}", actual_model)
                         return ("custom", model_part)
             return (normalize_provider(provider_part), model_part)
diff --git a/tests/hermes_cli/test_startup_model_routing.py b/tests/hermes_cli/test_startup_model_routing.py
index 363ac4980f..d814086409 100644
--- a/tests/hermes_cli/test_startup_model_routing.py
+++ b/tests/hermes_cli/test_startup_model_routing.py
@@ -176,6 +176,10 @@ def test_startup_route_decodes_custom_colon_qualified_model(tmp_path, monkeypatc
         "custom:jetson-vllm:nemotron-nano-30b", current_provider="anthropic",
         user_providers=cfg.get("providers"))
     assert route == model_switch.StartupModelRoute("nemotron-nano-30b", "custom:jetson-vllm", "")
+    # The caller's providers are the only source: without the entry the prefix is bare ``custom``.
+    assert model_switch.resolve_startup_model_route(
+        "custom:jetson-vllm:nemotron-nano-30b", current_provider="anthropic", user_providers={}
+    ).provider == "custom"
     # A colon inside a plain model id is not a provider delimiter.
     assert model_switch.resolve_startup_model_route(
         "anthropic/claude-3.5-sonnet:beta", current_provider="anthropic",
@@ -187,9 +191,9 @@ def test_oneshot_and_tui_qualified_model_never_reaches_default_provider(tmp_path
     startup owner, so provider auto-detection never hands the qualified string to the configured
     default (#73943)."""
     from hermes_cli.oneshot import _resolve_model_and_provider
-    from tui_gateway import server as tui_server
 
     cfg = _write_named_provider(tmp_path, monkeypatch)
+    from tui_gateway import server as tui_server  # binds the config path at import: after HERMES_HOME
     monkeypatch.delenv("HERMES_INFERENCE_PROVIDER", raising=False)
     monkeypatch.delenv("HERMES_TUI_PROVIDER", raising=False)
     monkeypatch.setattr(

From 910658002519f45eb1ef57d4c524dc8d5b398194 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Fri, 18 Sep 2026 23:55:36 +0530
Subject: [PATCH 083/190] fix(tools): search_files grep fallback finds content
 under hidden directories

The grep fallback passed --exclude-dir='.*' and the search root together. grep
applies --exclude-dir to the command-line root as well as to subdirectories
(GNU grep to every component of it), so any content search rooted at or under a
dot-directory such as ~/.hermes returned zero matches when ripgrep was absent,
while the same search returned results with rg. Reported in #18473 with a live
12-vs-0 comparison on GNU grep 3.7; BSD grep drops the root only when the root
itself is dot-named.

Route those roots through the existing find -prune pipeline, which already
mirrors rg's hidden-directory default for descendants, and give find -mindepth 1
so the prune cannot swallow a dot-named root. The macOS protected-folder branch
shares the pipeline, so the prune clause is now built only when there are
protected paths to prune.

Credit: @memosr (#34017) and @luxles (#48878) proposed dropping --exclude-dir for
hidden roots first; that variant leaks hidden descendants, which the find route
keeps excluded.
---
 tests/tools/test_search_hidden_dirs.py | 38 ++++++++++++++++++++++++++
 tools/file_operations_search.py        | 25 +++++++++++------
 2 files changed, 55 insertions(+), 8 deletions(-)

diff --git a/tests/tools/test_search_hidden_dirs.py b/tests/tools/test_search_hidden_dirs.py
index 0315c1edc6..9b25a8543e 100644
--- a/tests/tools/test_search_hidden_dirs.py
+++ b/tests/tools/test_search_hidden_dirs.py
@@ -137,6 +137,44 @@ class TestGrepExcludesHiddenDirs:
         assert not result.matches
 
 
+class TestGrepSearchesRootsUnderHiddenDirs:
+    """Regression for #18473: grep applies ``--exclude-dir='.*'`` to the command-line
+    root as well (GNU grep: to every component of it), so a search rooted anywhere
+    under a dot-directory such as ``~/.hermes`` returned nothing on the fallback."""
+
+    @staticmethod
+    def _hidden_tree(tmp_path):
+        home = tmp_path / ".hermes"
+        (home / "skills").mkdir(parents=True)
+        (home / "skills" / "SKILL.md").write_text("visible document under a hidden home")
+        (home / ".hub").mkdir()
+        (home / ".hub" / "catalog.json").write_text("visible document cached from the hub")
+        return home
+
+    def test_absolute_root_under_hidden_dir_is_searched_but_hidden_children_are_not(
+        self, tmp_path, monkeypatch
+    ):
+        home = self._hidden_tree(tmp_path)
+        ops = ShellFileOperations(LocalEnvironment(cwd=str(tmp_path)), cwd=str(tmp_path))
+        monkeypatch.setattr(ops, "_has_command", lambda command: command == "grep")
+
+        result = ops.search("visible document", path=str(home), target="content")
+
+        assert result.error is None
+        assert [m.path.rsplit("/", 1)[-1] for m in result.matches] == ["SKILL.md"]
+
+    def test_relative_root_resolves_against_a_hidden_cwd(self, tmp_path, monkeypatch):
+        home = self._hidden_tree(tmp_path)
+        ops = ShellFileOperations(LocalEnvironment(cwd=str(home)), cwd=str(home))
+        monkeypatch.setattr(ops, "_has_command", lambda command: command == "grep")
+
+        result = ops.search("visible document", path=".", target="content")
+
+        assert result.error is None
+        assert result.total_count == 1
+        assert result.matches[0].path.endswith("SKILL.md")
+
+
 class TestRipgrepAlreadyExcludesHidden:
     """Verify ripgrep's default behavior is to skip hidden directories."""
 
diff --git a/tools/file_operations_search.py b/tools/file_operations_search.py
index 5d4232c8e3..f7835fb8b2 100644
--- a/tools/file_operations_search.py
+++ b/tools/file_operations_search.py
@@ -464,6 +464,12 @@ class SearchMixin:
         terms = " -o ".join(f"-path {self._escape_shell_arg(item)}" for item in protected_paths)
         return f"\\( {terms} \\) -prune"
 
+    def _root_under_hidden_dir(self, path: str) -> bool:
+        """True when the search root or any ancestor is a dot-directory (``~/.hermes/skills``)."""
+        cwd = getattr(self.env, "cwd", None) or self.cwd
+        parts = os.path.normpath(os.path.join(cwd, path or ".")).replace("\\", "/").split("/")
+        return any(part.startswith(".") and part not in (".", "..") for part in parts)
+
     def _rg_exclusion_globs(self, path: str) -> List[str]:
         """``--glob '!<dir>/**'`` pairs excluding protected dirs from an rg run."""
         out: List[str] = []
@@ -899,7 +905,10 @@ class SearchMixin:
         # grep's --exclude-dir matches BASENAMES anywhere, so it can't express "only
         # the home-level Downloads"; route pruning through find's path-scoped -prune.
         protected_paths = self._protected_prune_paths(path)
-        if protected_paths:
+        # grep applies --exclude-dir='.*' to the command-line root too (GNU grep: to
+        # every component of it), so a search rooted under a hidden dir such as
+        # ~/.hermes returns nothing (#18473); find's -prune only sees descendants.
+        if protected_paths or self._root_under_hidden_dir(path):
             return self._search_with_grep_pruned(
                 pattern, path, file_glob, limit, offset, output_mode, context, protected_paths)
         # -H forces filenames; -E matches rg regex behavior; --exclude-dir='.*'
@@ -925,14 +934,14 @@ class SearchMixin:
         enumerates files (traversal never enters protected dirs) and hands them to
         grep via ``-exec {} +``; hidden dirs pruned to mirror ``--exclude-dir='.*'``.
         Trade-off: find folds grep's exit code, so a hard grep error surfaces as an
-        empty result — acceptable for this darwin-local-broad-search-only branch."""
+        empty result — accepted for these two branches (macOS protected dirs, roots
+        under a dot-directory) where grep's own --exclude-dir cannot express the intent."""
         grep_parts = self._grep_cmd(["grep", "-nHE"], pattern, output_mode, context)
-        find_parts = [
-            "find", self._escape_shell_arg(path or "."),
-            self._prune_expr(protected_paths), "-o",
-            "\\( -type d -name '.*' \\) -prune", "-o",
-            "-type f",
-        ]
+        # -mindepth 1: the ``-name '.*'`` prune must not swallow a dot-named root itself.
+        find_parts = ["find", self._escape_shell_arg(path or "."), "-mindepth", "1"]
+        if protected_paths:
+            find_parts.extend([self._prune_expr(protected_paths), "-o"])
+        find_parts.extend(["\\( -type d -name '.*' \\) -prune", "-o", "-type f"])
         if file_glob:
             find_parts.extend(["-name", self._escape_shell_arg(file_glob)])
         find_parts.extend(["-exec", *grep_parts, "{}", "+", "2>/dev/null"])

From ab9a9503b78d8d4945df9fa53c692d2d955b351c Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:36:15 +0530
Subject: [PATCH 084/190] fix(tools): a single-file search root under a hidden
 dir is searched too
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Gate review on the previous commit: `find <root> -mindepth 1` yields nothing
when the root is a file, so `search_files(path="~/.hermes/config.yaml")` on
the grep fallback returned 0 matches (main returned 1). Reuse the
`! -path <root>` exemption the filename walk in `_search_files` already uses:
a dot-named root — directory or single file — is never pruned, hidden
descendants still are.

The root predicate now goes through `_normalized_filename_search_root`, which
already handles MSYS paths on Windows and posixpath for remote environments
instead of applying host `os.path` to a backend path.
---
 tests/tools/test_search_hidden_dirs.py | 10 ++++++++++
 tools/file_operations_search.py        | 19 ++++++++++---------
 2 files changed, 20 insertions(+), 9 deletions(-)

diff --git a/tests/tools/test_search_hidden_dirs.py b/tests/tools/test_search_hidden_dirs.py
index 9b25a8543e..9a45a1ddb5 100644
--- a/tests/tools/test_search_hidden_dirs.py
+++ b/tests/tools/test_search_hidden_dirs.py
@@ -174,6 +174,16 @@ class TestGrepSearchesRootsUnderHiddenDirs:
         assert result.total_count == 1
         assert result.matches[0].path.endswith("SKILL.md")
 
+    def test_single_file_root_under_hidden_dir_is_searched(self, tmp_path, monkeypatch):
+        home = self._hidden_tree(tmp_path)
+        ops = ShellFileOperations(LocalEnvironment(cwd=str(tmp_path)), cwd=str(tmp_path))
+        monkeypatch.setattr(ops, "_has_command", lambda command: command == "grep")
+
+        result = ops.search("visible document", path=str(home / "skills" / "SKILL.md"), target="content")
+
+        assert result.error is None
+        assert result.total_count == 1
+
 
 class TestRipgrepAlreadyExcludesHidden:
     """Verify ripgrep's default behavior is to skip hidden directories."""
diff --git a/tools/file_operations_search.py b/tools/file_operations_search.py
index f7835fb8b2..078df8c2c4 100644
--- a/tools/file_operations_search.py
+++ b/tools/file_operations_search.py
@@ -465,10 +465,9 @@ class SearchMixin:
         return f"\\( {terms} \\) -prune"
 
     def _root_under_hidden_dir(self, path: str) -> bool:
-        """True when the search root or any ancestor is a dot-directory (``~/.hermes/skills``)."""
-        cwd = getattr(self.env, "cwd", None) or self.cwd
-        parts = os.path.normpath(os.path.join(cwd, path or ".")).replace("\\", "/").split("/")
-        return any(part.startswith(".") and part not in (".", "..") for part in parts)
+        """True when the search root or any ancestor is dot-named (``~/.hermes/skills``)."""
+        root = _normalized_filename_search_root(self.env, path or ".", self.cwd)
+        return any(part.startswith(".") and part not in (".", "..") for part in root.replace("\\", "/").split("/"))
 
     def _rg_exclusion_globs(self, path: str) -> List[str]:
         """``--glob '!<dir>/**'`` pairs excluding protected dirs from an rg run."""
@@ -934,14 +933,16 @@ class SearchMixin:
         enumerates files (traversal never enters protected dirs) and hands them to
         grep via ``-exec {} +``; hidden dirs pruned to mirror ``--exclude-dir='.*'``.
         Trade-off: find folds grep's exit code, so a hard grep error surfaces as an
-        empty result — accepted for these two branches (macOS protected dirs, roots
-        under a dot-directory) where grep's own --exclude-dir cannot express the intent."""
+        empty result. That covers every grep-fallback search rooted under a dot-directory
+        (``~/.hermes/...`` included), not just the macOS protected-dir corner."""
         grep_parts = self._grep_cmd(["grep", "-nHE"], pattern, output_mode, context)
-        # -mindepth 1: the ``-name '.*'`` prune must not swallow a dot-named root itself.
-        find_parts = ["find", self._escape_shell_arg(path or "."), "-mindepth", "1"]
+        q_root = self._escape_shell_arg(path or ".")
+        find_parts = ["find", q_root]
         if protected_paths:
             find_parts.extend([self._prune_expr(protected_paths), "-o"])
-        find_parts.extend(["\\( -type d -name '.*' \\) -prune", "-o", "-type f"])
+        # ``! -path <root>`` keeps a dot-named root itself (dir or single file) out of the prune,
+        # mirroring the filename walk in ``_search_files``.
+        find_parts.extend([f"\\( -type d -name '.*' ! -path {q_root} \\) -prune", "-o", "-type f"])
         if file_glob:
             find_parts.extend(["-name", self._escape_shell_arg(file_glob)])
         find_parts.extend(["-exec", *grep_parts, "{}", "+", "2>/dev/null"])

From 1768a5566ff6d0a3fc4ef1cc82013e36945673df Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 01:12:13 +0530
Subject: [PATCH 085/190] refactor(tools): one find clause for the hidden-dir
 prune

The filename walk and the grep fallback each hand-built the same
`-type d -name .* ! -path <root> -prune` clause; the first fold drifted
between them, which is how #18473 stayed open. One `_hidden_prune_expr`
serves both; docstring says when the pruned branch is used and why.
---
 tools/file_operations_search.py | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

diff --git a/tools/file_operations_search.py b/tools/file_operations_search.py
index 078df8c2c4..abbcfcda93 100644
--- a/tools/file_operations_search.py
+++ b/tools/file_operations_search.py
@@ -459,6 +459,13 @@ class SearchMixin:
                 f"an unattended privacy prompt: {skipped}. Search a protected "
                 "folder directly when access is intentional.")
 
+    @staticmethod
+    def _hidden_prune_expr(q_roots: List[str]) -> str:
+        """find clause pruning hidden dirs while keeping an explicitly selected dot-named root
+        (dir or single file) — find echoes each start point as given, so ``! -path`` matches it."""
+        exemptions = "".join(f" ! -path {root}" for root in q_roots)
+        return f"\\( -type d -name '.*'{exemptions} \\) -prune"
+
     def _prune_expr(self, protected_paths: List[str]) -> str:
         """find ``\\( -path A -o -path B \\) -prune`` clause for the protected dirs."""
         terms = " -o ".join(f"-path {self._escape_shell_arg(item)}" for item in protected_paths)
@@ -691,8 +698,7 @@ class SearchMixin:
         # ``./`` so find doesn't parse them as options.
         find_roots = [f"./{root}" if root.startswith("-") else root for root in roots]
         q_roots = [self._escape_shell_arg(root) for root in find_roots]
-        root_exemptions = "".join(f" ! -path {root}" for root in q_roots)
-        hidden_prune = f" \\( -type d -name '.*'{root_exemptions} \\) -prune -o"
+        hidden_prune = f" {self._hidden_prune_expr(q_roots)} -o"
         protected_paths = [absolute for _r, _rel, absolute in self._effective_macos_search_exclusions(roots)]
         protected_prune = f" {self._prune_expr(protected_paths)} -o" if protected_paths else ""
         fetch_limit = offset + limit + 1
@@ -929,20 +935,16 @@ class SearchMixin:
     def _search_with_grep_pruned(self, pattern: str, path: str, file_glob: Optional[str],
                                  limit: int, offset: int, output_mode: str, context: int,
                                  protected_paths: List[str]) -> SearchResult:
-        """grep fallback with PATH-scoped protected-dir pruning: ``find ... -prune``
-        enumerates files (traversal never enters protected dirs) and hands them to
-        grep via ``-exec {} +``; hidden dirs pruned to mirror ``--exclude-dir='.*'``.
-        Trade-off: find folds grep's exit code, so a hard grep error surfaces as an
-        empty result. That covers every grep-fallback search rooted under a dot-directory
-        (``~/.hermes/...`` included), not just the macOS protected-dir corner."""
+        """grep fallback via ``find ... -prune -exec grep {} +``, used when the root needs
+        path-scoped pruning (macOS protected dirs) or is itself under a dot-directory
+        (#18473: grep's ``--exclude-dir='.*'`` would drop the root). Trade-off: find folds
+        grep's exit code, so a hard grep error surfaces as an empty result."""
         grep_parts = self._grep_cmd(["grep", "-nHE"], pattern, output_mode, context)
         q_root = self._escape_shell_arg(path or ".")
         find_parts = ["find", q_root]
         if protected_paths:
             find_parts.extend([self._prune_expr(protected_paths), "-o"])
-        # ``! -path <root>`` keeps a dot-named root itself (dir or single file) out of the prune,
-        # mirroring the filename walk in ``_search_files``.
-        find_parts.extend([f"\\( -type d -name '.*' ! -path {q_root} \\) -prune", "-o", "-type f"])
+        find_parts.extend([self._hidden_prune_expr([q_root]), "-o", "-type f"])
         if file_glob:
             find_parts.extend(["-name", self._escape_shell_arg(file_glob)])
         find_parts.extend(["-exec", *grep_parts, "{}", "+", "2>/dev/null"])

From f12c3a163105924114ce1521ee877aea1120a670 Mon Sep 17 00:00:00 2001
From: r266-tech <r266-tech@users.noreply.github.com>
Date: Sun, 21 Jun 2026 00:55:33 +0800
Subject: [PATCH 086/190] fix(desktop): honor display.show_reasoning in the
 message renderer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The desktop Settings → Chat "Reasoning Blocks" toggle (display.show_reasoning)
is persisted to config.yaml but the React renderer never read it, so toggling
it had no effect — reasoning blocks were always shown regardless (issue #49664).

Wire the renderer to the setting:
- add a $showReasoning nanostore atom + setShowReasoning setter
- refreshHermesConfig populates it from Boolean(config.display?.show_reasoning),
  read from the same /api/config the Settings toggle uses, so an unset key
  resolves to false (matching the toggle and the gateway/CLI default)
- gate ReasoningAccordionGroup (the "Thinking" disclosure) and ReasoningTextPart
  on the atom; the existing hasContent guard is preserved
- add show_reasoning?: boolean to the HermesConfig display type
- store unit tests for the atom/setter

The atom defaults to true so reasoning keeps rendering if the (nice-to-have)
config read fails; the config refresh then resolves the real value.

Fixes #49664

(cherry picked from commit e199fadde81ffb8af70f49b9785f597295ac0f48)
---
 .../session/hooks/use-hermes-config.test.ts   | 19 ++++++++++++
 .../app/session/hooks/use-hermes-config.ts    |  2 ++
 .../assistant-ui/thread/message-parts.tsx     | 11 +++++--
 .../assistant-ui/thread/streaming.test.tsx    | 30 +++++++++++++++++--
 .../desktop/src/store/reasoning-disclosure.ts | 13 ++++++++
 apps/desktop/src/types/hermes.ts              |  1 +
 6 files changed, 72 insertions(+), 4 deletions(-)

diff --git a/apps/desktop/src/app/session/hooks/use-hermes-config.test.ts b/apps/desktop/src/app/session/hooks/use-hermes-config.test.ts
index 3cd5b72f85..5a3040cf49 100644
--- a/apps/desktop/src/app/session/hooks/use-hermes-config.test.ts
+++ b/apps/desktop/src/app/session/hooks/use-hermes-config.test.ts
@@ -5,6 +5,7 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { $terminalFontFamily, setTerminalFontFamilyFromConfig } from '@/app/right-sidebar/terminal/terminal-font'
 import { getHermesConfig } from '@/hermes'
 import { persistString } from '@/lib/storage'
+import { $showReasoning, setShowReasoningFromConfig } from '@/store/reasoning-disclosure'
 import {
   $currentCwd,
   $currentFastMode,
@@ -35,6 +36,7 @@ const mockConfig = (config: Record<string, unknown>) =>
 describe('useHermesConfig refreshHermesConfig', () => {
   beforeEach(() => {
     // Reset atoms and localStorage between tests
+    setShowReasoningFromConfig(undefined)
     setCurrentCwd('')
     setCurrentFastMode(false)
     setCurrentModelSource('')
@@ -44,6 +46,21 @@ describe('useHermesConfig refreshHermesConfig', () => {
     persistString(WORKSPACE_CWD_KEY, null)
   })
 
+  it.each([
+    [true, true], [false, false], ['false', false], ['off', false], ['0', false],
+    [' True ', true], ['yes', true], [1, true], [0, false], [undefined, true]
+  ])('resolves reasoning display %j to %j and resets missing config to the default', async (value, expected) => {
+    mockConfig({ display: { show_reasoning: value } })
+    const { result } = renderHook(() => useHermesConfig({ activeSessionIdRef: { current: null } }))
+
+    await act(async () => { await result.current.refreshHermesConfig() })
+    expect($showReasoning.get()).toBe(expected)
+
+    mockConfig({})
+    await act(async () => { await result.current.refreshHermesConfig() })
+    expect($showReasoning.get()).toBe(true)
+  })
+
   // Regression: the composer keeps a manual model pick sticky, which skips the
   // composer reseed. The profile default must still be published, because the
   // model picker resolves "the default effort" from it when applying a model's
@@ -133,6 +150,7 @@ describe('useHermesConfig refreshHermesConfig', () => {
 
     ownsSwitch = false
     staleConfig.resolve({
+      display: { show_reasoning: false },
       agent: { reasoning_effort: 'high', service_tier: 'priority' },
       terminal: { font_family: 'MesloLGS NF' }
     } as Awaited<ReturnType<typeof getHermesConfig>>)
@@ -145,6 +163,7 @@ describe('useHermesConfig refreshHermesConfig', () => {
     expect($currentReasoningEffort.get()).toBe('')
     expect($currentFastMode.get()).toBe(false)
     expect($terminalFontFamily.get()).toBe('')
+    expect($showReasoning.get()).toBe(true)
   })
 
   it('does not let an older profile config overwrite a newer profile', async () => {
diff --git a/apps/desktop/src/app/session/hooks/use-hermes-config.ts b/apps/desktop/src/app/session/hooks/use-hermes-config.ts
index a4ce3785b0..0b9b3ef958 100644
--- a/apps/desktop/src/app/session/hooks/use-hermes-config.ts
+++ b/apps/desktop/src/app/session/hooks/use-hermes-config.ts
@@ -5,6 +5,7 @@ import { getHermesConfig, getHermesConfigDefaults } from '@/hermes'
 import { BUILTIN_PERSONALITIES, normalizePersonalityValue, personalityNamesFromConfig } from '@/lib/chat-runtime'
 import { normalize } from '@/lib/text'
 import { setDisplayTimestampsFromConfig } from '@/store/display-timestamps'
+import { setShowReasoningFromConfig } from '@/store/reasoning-disclosure'
 import {
   getComposerSelectionGeneration,
   getCurrentModelSource,
@@ -140,6 +141,7 @@ export function useHermesConfig({ activeSessionIdRef }: HermesConfigOptions) {
         }
 
         setDisplayTimestampsFromConfig(config.display?.timestamps)
+        setShowReasoningFromConfig(config.display?.show_reasoning)
         setTerminalFontFamilyFromConfig(config.terminal?.font_family)
         setChatFontFamilyFromConfig(config.desktop?.font_family)
 
diff --git a/apps/desktop/src/components/assistant-ui/thread/message-parts.tsx b/apps/desktop/src/components/assistant-ui/thread/message-parts.tsx
index 6e336ced3a..c4caee0683 100644
--- a/apps/desktop/src/components/assistant-ui/thread/message-parts.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/message-parts.tsx
@@ -29,7 +29,7 @@ import { separateGluedReasoningBlocks } from '@/lib/reasoning-blocks'
 import { isTodoToolName } from '@/lib/todos'
 import { useEnterAnimation } from '@/lib/use-enter-animation'
 import { cn } from '@/lib/utils'
-import { $reasoningCollapsedByDefault } from '@/store/reasoning-disclosure'
+import { $reasoningCollapsedByDefault, $showReasoning } from '@/store/reasoning-disclosure'
 
 type TimelineToolCallProps = ToolCallMessagePartProps & { completedAt?: number; timestamp?: number }
 
@@ -308,6 +308,7 @@ const ReasoningAccordionGroup: FC<{ children?: ReactNode; endIndex: number; star
   endIndex,
   startIndex
 }) => {
+  const showReasoning = useStore($showReasoning)
   const messageId = useAuiState(s => s.message.id)
   const messageRunning = useAuiState(s => s.message.status?.type === 'running')
   // The guide's reasoning is it reading its own runbook ("Now step 4: offer
@@ -352,7 +353,7 @@ const ReasoningAccordionGroup: FC<{ children?: ReactNode; endIndex: number; star
     }, undefined)
   )
 
-  if (!hasContent || guidedChat) {
+  if (!hasContent || guidedChat || !showReasoning) {
     return null
   }
 
@@ -380,6 +381,12 @@ const ReasoningTextPart: ReasoningMessagePartComponent = () => {
   const { status, text } = useMessagePartReasoning()
   const messageRunning = useAuiState(s => s.message.status?.type === 'running')
 
+  const showReasoning = useStore($showReasoning)
+
+  if (!showReasoning) {
+    return null
+  }
+
   return (
     <MarkdownTextContent
       containerClassName="text-xs leading-snug text-muted-foreground/85"
diff --git a/apps/desktop/src/components/assistant-ui/thread/streaming.test.tsx b/apps/desktop/src/components/assistant-ui/thread/streaming.test.tsx
index cf6a746e3c..dc64fb764d 100644
--- a/apps/desktop/src/components/assistant-ui/thread/streaming.test.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/streaming.test.tsx
@@ -1,12 +1,14 @@
-import { AssistantRuntimeProvider, type ThreadMessage, useExternalStoreRuntime } from '@assistant-ui/react'
+import { AssistantRuntimeProvider, MessagePrimitive, type ThreadMessage, ThreadPrimitive, useExternalStoreRuntime } from '@assistant-ui/react'
 import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react'
 import { useEffect, useState } from 'react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
-import { $reasoningCollapsedByDefault } from '@/store/reasoning-disclosure'
+import { $reasoningCollapsedByDefault, setShowReasoningFromConfig } from '@/store/reasoning-disclosure'
 
 import { stubThreadEnvironment, stubThreadViewportSize, ThreadRuntime } from '../test-utils'
 
+import { MESSAGE_PARTS_COMPONENTS } from './message-parts'
+
 import { Thread } from '.'
 
 const createdAt = new Date('2026-05-01T00:00:00.000Z')
@@ -477,6 +479,30 @@ describe('assistant-ui streaming renderer', () => {
   beforeEach(() => {
     resizeObservers.clear()
     $reasoningCollapsedByDefault.set(false)
+    setShowReasoningFromConfig(undefined)
+  })
+
+  it.each([true, false])('honors reasoning visibility %j for grouped and standalone parts', async enabled => {
+    setShowReasoningFromConfig(enabled)
+
+    const UngroupedMessage = () => <MessagePrimitive.Root>
+      <MessagePrimitive.Parts components={{ Reasoning: MESSAGE_PARTS_COMPONENTS.Reasoning }} />
+    </MessagePrimitive.Root>
+
+    const { container } = render(<>
+      <RunningReasoningHarness />
+      <ThreadRuntime messages={[assistantReasoningMessage('standalone reasoning', true)]}>
+        <ThreadPrimitive.Root>
+          <ThreadPrimitive.Messages components={{ AssistantMessage: UngroupedMessage, UserMessage: () => null }} />
+        </ThreadPrimitive.Root>
+      </ThreadRuntime>
+    </>)
+
+    await waitFor(() => {
+      expect(container.querySelectorAll('[data-slot="aui_reasoning-text"]')).toHaveLength(enabled ? 2 : 0)
+    })
+    expect(within(container).queryByRole('button', { name: /thinking/i }) !== null).toBe(enabled)
+    expect(container.textContent?.includes('standalone reasoning')).toBe(enabled)
   })
 
   it('renders assistant text incrementally before completion', async () => {
diff --git a/apps/desktop/src/store/reasoning-disclosure.ts b/apps/desktop/src/store/reasoning-disclosure.ts
index 584c00a57a..fa59aa0d62 100644
--- a/apps/desktop/src/store/reasoning-disclosure.ts
+++ b/apps/desktop/src/store/reasoning-disclosure.ts
@@ -12,3 +12,16 @@ $reasoningCollapsedByDefault.subscribe(value => persistBoolean(REASONING_COLLAPS
 export function setReasoningCollapsedByDefault(value: boolean) {
   $reasoningCollapsedByDefault.set(value)
 }
+
+// Mirrors backend display.show_reasoning; omission follows DEFAULT_CONFIG.
+export const $showReasoning = atom(true)
+
+export function setShowReasoningFromConfig(value: unknown): void {
+  const enabled = value === undefined
+    ? true
+    : typeof value === 'string'
+      ? ['1', 'true', 'yes', 'on'].includes(value.trim().toLowerCase())
+      : Boolean(value)
+
+  $showReasoning.set(enabled)
+}
diff --git a/apps/desktop/src/types/hermes.ts b/apps/desktop/src/types/hermes.ts
index b79cf331c3..5b48336217 100644
--- a/apps/desktop/src/types/hermes.ts
+++ b/apps/desktop/src/types/hermes.ts
@@ -422,6 +422,7 @@ export interface HermesConfig {
     service_tier?: string
   }
   display?: {
+    show_reasoning?: boolean | null | number | string
     personality?: string
     skin?: string
     interim_assistant_messages?: boolean

From d12736c959899122822caeff4b5e3b5ab9d1eb87 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:14:19 +0530
Subject: [PATCH 087/190] refactor(desktop): mirror display.show_reasoning the
 way display.timestamps is mirrored

Collapse the string-coercion table to the one case config.yaml can actually
produce (a quoted "false"), matching setDisplayTimestampsFromConfig, and trim
the config-hook coverage to the single mirror/default contract. The renderer
test (grouped + standalone parts, on and off) is unchanged apart from
formatting.
---
 .../session/hooks/use-hermes-config.test.ts   | 20 ++++++-----
 .../assistant-ui/thread/streaming.test.tsx    | 34 ++++++++++++-------
 .../desktop/src/store/reasoning-disclosure.ts | 12 +++----
 3 files changed, 38 insertions(+), 28 deletions(-)

diff --git a/apps/desktop/src/app/session/hooks/use-hermes-config.test.ts b/apps/desktop/src/app/session/hooks/use-hermes-config.test.ts
index 5a3040cf49..57af4c10e8 100644
--- a/apps/desktop/src/app/session/hooks/use-hermes-config.test.ts
+++ b/apps/desktop/src/app/session/hooks/use-hermes-config.test.ts
@@ -46,18 +46,22 @@ describe('useHermesConfig refreshHermesConfig', () => {
     persistString(WORKSPACE_CWD_KEY, null)
   })
 
-  it.each([
-    [true, true], [false, false], ['false', false], ['off', false], ['0', false],
-    [' True ', true], ['yes', true], [1, true], [0, false], [undefined, true]
-  ])('resolves reasoning display %j to %j and resets missing config to the default', async (value, expected) => {
-    mockConfig({ display: { show_reasoning: value } })
+  // #49664: the Reasoning Blocks toggle wrote config but the renderer never
+  // read it. A refresh mirrors the key (quoted "false" included) and a
+  // missing key falls back to the DEFAULT_CONFIG default (on).
+  it('mirrors display.show_reasoning and resets a missing key to the default', async () => {
+    mockConfig({ display: { show_reasoning: 'false' } })
     const { result } = renderHook(() => useHermesConfig({ activeSessionIdRef: { current: null } }))
 
-    await act(async () => { await result.current.refreshHermesConfig() })
-    expect($showReasoning.get()).toBe(expected)
+    await act(async () => {
+      await result.current.refreshHermesConfig()
+    })
+    expect($showReasoning.get()).toBe(false)
 
     mockConfig({})
-    await act(async () => { await result.current.refreshHermesConfig() })
+    await act(async () => {
+      await result.current.refreshHermesConfig()
+    })
     expect($showReasoning.get()).toBe(true)
   })
 
diff --git a/apps/desktop/src/components/assistant-ui/thread/streaming.test.tsx b/apps/desktop/src/components/assistant-ui/thread/streaming.test.tsx
index dc64fb764d..6441f14602 100644
--- a/apps/desktop/src/components/assistant-ui/thread/streaming.test.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/streaming.test.tsx
@@ -1,4 +1,10 @@
-import { AssistantRuntimeProvider, MessagePrimitive, type ThreadMessage, ThreadPrimitive, useExternalStoreRuntime } from '@assistant-ui/react'
+import {
+  AssistantRuntimeProvider,
+  MessagePrimitive,
+  type ThreadMessage,
+  ThreadPrimitive,
+  useExternalStoreRuntime
+} from '@assistant-ui/react'
 import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react'
 import { useEffect, useState } from 'react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
@@ -485,18 +491,22 @@ describe('assistant-ui streaming renderer', () => {
   it.each([true, false])('honors reasoning visibility %j for grouped and standalone parts', async enabled => {
     setShowReasoningFromConfig(enabled)
 
-    const UngroupedMessage = () => <MessagePrimitive.Root>
-      <MessagePrimitive.Parts components={{ Reasoning: MESSAGE_PARTS_COMPONENTS.Reasoning }} />
-    </MessagePrimitive.Root>
+    const UngroupedMessage = () => (
+      <MessagePrimitive.Root>
+        <MessagePrimitive.Parts components={{ Reasoning: MESSAGE_PARTS_COMPONENTS.Reasoning }} />
+      </MessagePrimitive.Root>
+    )
 
-    const { container } = render(<>
-      <RunningReasoningHarness />
-      <ThreadRuntime messages={[assistantReasoningMessage('standalone reasoning', true)]}>
-        <ThreadPrimitive.Root>
-          <ThreadPrimitive.Messages components={{ AssistantMessage: UngroupedMessage, UserMessage: () => null }} />
-        </ThreadPrimitive.Root>
-      </ThreadRuntime>
-    </>)
+    const { container } = render(
+      <>
+        <RunningReasoningHarness />
+        <ThreadRuntime messages={[assistantReasoningMessage('standalone reasoning', true)]}>
+          <ThreadPrimitive.Root>
+            <ThreadPrimitive.Messages components={{ AssistantMessage: UngroupedMessage, UserMessage: () => null }} />
+          </ThreadPrimitive.Root>
+        </ThreadRuntime>
+      </>
+    )
 
     await waitFor(() => {
       expect(container.querySelectorAll('[data-slot="aui_reasoning-text"]')).toHaveLength(enabled ? 2 : 0)
diff --git a/apps/desktop/src/store/reasoning-disclosure.ts b/apps/desktop/src/store/reasoning-disclosure.ts
index fa59aa0d62..fd42d19820 100644
--- a/apps/desktop/src/store/reasoning-disclosure.ts
+++ b/apps/desktop/src/store/reasoning-disclosure.ts
@@ -13,15 +13,11 @@ export function setReasoningCollapsedByDefault(value: boolean) {
   $reasoningCollapsedByDefault.set(value)
 }
 
-// Mirrors backend display.show_reasoning; omission follows DEFAULT_CONFIG.
+// Mirrors `display.show_reasoning` (Settings → Chat → Reasoning Blocks). On
+// by default like DEFAULT_CONFIG; a quoted "false" in config.yaml still
+// means off (sibling: display-timestamps.ts).
 export const $showReasoning = atom(true)
 
 export function setShowReasoningFromConfig(value: unknown): void {
-  const enabled = value === undefined
-    ? true
-    : typeof value === 'string'
-      ? ['1', 'true', 'yes', 'on'].includes(value.trim().toLowerCase())
-      : Boolean(value)
-
-  $showReasoning.set(enabled)
+  $showReasoning.set(!(value === false || value === 'false' || value === 0))
 }

From ad12cbbd552e5739cf266faf1b6ce6f5c3d5108f Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:49:31 +0530
Subject: [PATCH 088/190] docs(desktop): document the Reasoning Blocks toggle;
 narrow its config type

The desktop guide listed every other Settings toggle but not this one, and
the key's type only needs the two shapes config.yaml can hold (boolean, or a
quoted string), matching `display.timestamps` beside it.
---
 apps/desktop/src/types/hermes.ts   | 2 +-
 website/docs/user-guide/desktop.md | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/apps/desktop/src/types/hermes.ts b/apps/desktop/src/types/hermes.ts
index 5b48336217..aee88d0367 100644
--- a/apps/desktop/src/types/hermes.ts
+++ b/apps/desktop/src/types/hermes.ts
@@ -422,7 +422,7 @@ export interface HermesConfig {
     service_tier?: string
   }
   display?: {
-    show_reasoning?: boolean | null | number | string
+    show_reasoning?: boolean | string
     personality?: string
     skin?: string
     interim_assistant_messages?: boolean
diff --git a/website/docs/user-guide/desktop.md b/website/docs/user-guide/desktop.md
index 92d8a0fa0f..9cff9563d8 100644
--- a/website/docs/user-guide/desktop.md
+++ b/website/docs/user-guide/desktop.md
@@ -196,6 +196,7 @@ Manage providers, models, tools, and credentials from a real UI instead of editi
 - **xAI Grok OAuth** — Grok is a first-class OAuth provider in the launcher; sign in through the browser flow like the other OAuth providers.
 - **Tool-backend installs from the GUI** — run a tool backend's post-setup install steps directly from the app instead of dropping to a terminal. In the terminal backend picker, selecting a backend marked **Needs setup** asks for confirmation first; declining leaves the current backend selected.
 - **Terminal font picker** — choose an installed font in **Settings → Appearance**. Nerd Fonts such as `MesloLGS NF` render Powerlevel10k separators and icons in both interactive and agent terminals; the setting is saved per profile.
+- **Reasoning Blocks** — **Settings → Chat → Reasoning Blocks** (`display.show_reasoning` in `config.yaml`) hides or shows the model's thinking in the transcript; off means answers only, on the next refresh of the chat view after you save.
 - **Reopen Last Chat on Launch** — by default the app picks up where you left off on cold start. Turn it off in **Settings → Appearance** (or set `display.resume_last_session: false` in `config.yaml`) to always begin with a fresh chat. Deep links and explicit destinations are never overridden either way.
 - **Auxiliary-model warning** — if you switch the main model to a new provider while auxiliary tasks (titling, summarization, and similar helpers) are still pinned to another provider, the app warns you so you don't unknowingly split work across two providers.
 - **Per-task reasoning effort** — each row under **Settings → Model → Auxiliary models** has a reasoning selector next to its provider/model pick: a level, **Off**, or **inherit · main model effort** (the default, which removes the task's override). It is saved as `auxiliary.<task>.reasoning_effort` in `config.yaml`, the same key `hermes model` writes, and shows in the row's summary when set. Use it to run frequent helpers such as compression or titling at low or no reasoning while the main agent stays at high.

From fc8b671cf7f40a55b88642a5ad97751523383ccf Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 01:24:48 +0530
Subject: [PATCH 089/190] refactor(desktop): say why the standalone reasoning
 gate exists; sharpen the toggle test
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The docs line implied a manual refresh step — open chats update as soon as
the setting saves. The ungrouped `Reasoning` gate reads as dead next to the
group's, so name the path that reaches it. The on/off assertions now fail
with the element, not `expected false to be true`.
---
 .../components/assistant-ui/thread/message-parts.tsx |  3 +++
 .../assistant-ui/thread/streaming.test.tsx           | 12 ++++++++++--
 website/docs/user-guide/desktop.md                   |  2 +-
 3 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/apps/desktop/src/components/assistant-ui/thread/message-parts.tsx b/apps/desktop/src/components/assistant-ui/thread/message-parts.tsx
index c4caee0683..80022ef408 100644
--- a/apps/desktop/src/components/assistant-ui/thread/message-parts.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/message-parts.tsx
@@ -381,6 +381,9 @@ const ReasoningTextPart: ReasoningMessagePartComponent = () => {
   const { status, text } = useMessagePartReasoning()
   const messageRunning = useAuiState(s => s.message.status?.type === 'running')
 
+  // The group above already hides grouped parts; this covers a Reasoning part
+  // rendered without a ReasoningGroup wrapper (assistant-ui drops the group
+  // when a ChainOfThought component is registered).
   const showReasoning = useStore($showReasoning)
 
   if (!showReasoning) {
diff --git a/apps/desktop/src/components/assistant-ui/thread/streaming.test.tsx b/apps/desktop/src/components/assistant-ui/thread/streaming.test.tsx
index 6441f14602..65a94549a7 100644
--- a/apps/desktop/src/components/assistant-ui/thread/streaming.test.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/streaming.test.tsx
@@ -511,8 +511,16 @@ describe('assistant-ui streaming renderer', () => {
     await waitFor(() => {
       expect(container.querySelectorAll('[data-slot="aui_reasoning-text"]')).toHaveLength(enabled ? 2 : 0)
     })
-    expect(within(container).queryByRole('button', { name: /thinking/i }) !== null).toBe(enabled)
-    expect(container.textContent?.includes('standalone reasoning')).toBe(enabled)
+    const thinking = within(container).queryByRole('button', { name: /thinking/i })
+    const standalone = within(container).queryByText('standalone reasoning')
+
+    if (enabled) {
+      expect(thinking).not.toBeNull()
+      expect(standalone).not.toBeNull()
+    } else {
+      expect(thinking).toBeNull()
+      expect(standalone).toBeNull()
+    }
   })
 
   it('renders assistant text incrementally before completion', async () => {
diff --git a/website/docs/user-guide/desktop.md b/website/docs/user-guide/desktop.md
index 9cff9563d8..b6ff3720e8 100644
--- a/website/docs/user-guide/desktop.md
+++ b/website/docs/user-guide/desktop.md
@@ -196,7 +196,7 @@ Manage providers, models, tools, and credentials from a real UI instead of editi
 - **xAI Grok OAuth** — Grok is a first-class OAuth provider in the launcher; sign in through the browser flow like the other OAuth providers.
 - **Tool-backend installs from the GUI** — run a tool backend's post-setup install steps directly from the app instead of dropping to a terminal. In the terminal backend picker, selecting a backend marked **Needs setup** asks for confirmation first; declining leaves the current backend selected.
 - **Terminal font picker** — choose an installed font in **Settings → Appearance**. Nerd Fonts such as `MesloLGS NF` render Powerlevel10k separators and icons in both interactive and agent terminals; the setting is saved per profile.
-- **Reasoning Blocks** — **Settings → Chat → Reasoning Blocks** (`display.show_reasoning` in `config.yaml`) hides or shows the model's thinking in the transcript; off means answers only, on the next refresh of the chat view after you save.
+- **Reasoning Blocks** — **Settings → Chat → Reasoning Blocks** (`display.show_reasoning` in `config.yaml`) shows or hides the model's thinking in the transcript (off shows answers only). Open chats update as soon as the setting saves.
 - **Reopen Last Chat on Launch** — by default the app picks up where you left off on cold start. Turn it off in **Settings → Appearance** (or set `display.resume_last_session: false` in `config.yaml`) to always begin with a fresh chat. Deep links and explicit destinations are never overridden either way.
 - **Auxiliary-model warning** — if you switch the main model to a new provider while auxiliary tasks (titling, summarization, and similar helpers) are still pinned to another provider, the app warns you so you don't unknowingly split work across two providers.
 - **Per-task reasoning effort** — each row under **Settings → Model → Auxiliary models** has a reasoning selector next to its provider/model pick: a level, **Off**, or **inherit · main model effort** (the default, which removes the task's override). It is saved as `auxiliary.<task>.reasoning_effort` in `config.yaml`, the same key `hermes model` writes, and shows in the row's summary when set. Use it to run frequent helpers such as compression or titling at low or no reasoning while the main agent stays at high.

From b9c2660ca479d9a2cf000d1d45ac9aadd1b7e3bd Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 01:16:41 +0530
Subject: [PATCH 090/190] chore: credit jkobject as first submitter of the
 Codex TTFB cap fix
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

#69228 (2026-07-22) made HERMES_CODEX_TTFB_MAX_SECONDS opt-in a month before
#91635, with the identical one-line change that landed via #115291
(b1968795b2). The salvage sweep searched by issue number only and missed it;
this records the authorship the merge should have carried.

Co-authored-by: Jérémie Kalfon <jkobject@gmail.com>
---
 contributors/emails/jkobject@gmail.com | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 contributors/emails/jkobject@gmail.com

diff --git a/contributors/emails/jkobject@gmail.com b/contributors/emails/jkobject@gmail.com
new file mode 100644
index 0000000000..62e4167cc8
--- /dev/null
+++ b/contributors/emails/jkobject@gmail.com
@@ -0,0 +1,2 @@
+jkobject
+# PR #69228: first fix for the Codex TTFB cap default (#91621), landed via #115291

From 6520b9a1edba42fe073e0219e91d5f7a5a2e6d5a Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Fri, 18 Sep 2026 23:38:17 +0530
Subject: [PATCH 091/190] chore: map contributor email for @eliasburlison
 (#92060 salvage)

---
 contributors/emails/eburlison@me.com | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 contributors/emails/eburlison@me.com

diff --git a/contributors/emails/eburlison@me.com b/contributors/emails/eburlison@me.com
new file mode 100644
index 0000000000..a149528f7f
--- /dev/null
+++ b/contributors/emails/eburlison@me.com
@@ -0,0 +1,2 @@
+eliasburlison
+# PR #92060 salvage

From b945645bfd391dd705dc55da0e3f46d8d11b3f93 Mon Sep 17 00:00:00 2001
From: mrnosilrub <eburlison@me.com>
Date: Fri, 21 Aug 2026 23:35:21 -0500
Subject: [PATCH 092/190] fix(gateway): wait for api_server port before a
 replacement starts

On macOS api_server cannot SO_REUSEADDR, so replacing the process as
soon as the old PID exits still hits EADDRINUSE. The new process then
stays up with no API. Wait for the listen port to refuse connections,
and retry the bind a few times before treating the conflict as fatal.

Fixes #91547

(cherry picked from commit 5cb9545023646277b2fb59ebfb5e89b0fd161aba)
---
 gateway/platforms/api_server.py  | 17 ++++++++++-
 hermes_cli/gateway.py            | 51 ++++++++++++++++++++++++++++++++
 tests/hermes_cli/test_gateway.py | 33 +++++++++++++++++++++
 3 files changed, 100 insertions(+), 1 deletion(-)

diff --git a/gateway/platforms/api_server.py b/gateway/platforms/api_server.py
index 514bb3bb2d..8227b2b361 100644
--- a/gateway/platforms/api_server.py
+++ b/gateway/platforms/api_server.py
@@ -4021,7 +4021,22 @@ class APIServerAdapter(OpenAICompatRoutesMixin, BasePlatformAdapter):
             self._site = web.TCPSite(
                 self._runner, self._host, self._port, reuse_address=False if sys.platform == "darwin" else None)
             try:
-                await self._site.start()
+                last_exc: OSError | None = None
+                for attempt in range(5):
+                    try:
+                        await self._site.start()
+                        last_exc = None
+                        break
+                    except OSError as exc:
+                        last_exc = exc
+                        if (
+                            getattr(exc, "errno", None) != errno.EADDRINUSE
+                            or attempt == 4
+                        ):
+                            break
+                        await asyncio.sleep(0.2 * (attempt + 1))
+                if last_exc is not None:
+                    raise last_exc
             except OSError as exc:
                 await self._runner.cleanup()
                 self._runner = None
diff --git a/hermes_cli/gateway.py b/hermes_cli/gateway.py
index db710d34c8..35b479bdd5 100644
--- a/hermes_cli/gateway.py
+++ b/hermes_cli/gateway.py
@@ -4328,6 +4328,53 @@ def _wait_for_gateway_exit(timeout: float = 10.0, force_after: float | None = 5.
     return True
 
 
+def _wait_for_tcp_port_free(
+    host: str,
+    port: int,
+    *,
+    timeout: float = 10.0,
+    clock=time.monotonic,
+    sleeper=time.sleep,
+    connect=None,
+) -> bool:
+    """Wait until nothing accepts TCP connections on host:port.
+
+    PID exit is not enough on macOS: api_server disables SO_REUSEADDR, so a
+    restart that wins the race logs EADDRINUSE and keeps running with no API.
+    Connection-refused means the listener is gone.
+    """
+    probe = connect
+    if probe is None:
+        def probe(target_host: str, target_port: int) -> bool:
+            with socket.create_connection((target_host, target_port), timeout=0.2):
+                return True
+
+    deadline = clock() + timeout
+    while clock() < deadline:
+        try:
+            probe(host, port)
+        except OSError:
+            return True
+        sleeper(0.1)
+    return False
+
+
+def _wait_for_api_server_port_free(*, timeout: float = 10.0) -> bool:
+    """Wait for the configured api_server listen address to stop accepting."""
+    host = os.getenv("API_SERVER_HOST", "127.0.0.1") or "127.0.0.1"
+    try:
+        port = int(os.getenv("API_SERVER_PORT", "8642"))
+    except ValueError:
+        port = 8642
+    freed = _wait_for_tcp_port_free(host, port, timeout=timeout)
+    if not freed:
+        print(
+            f"⚠ {host}:{port} still accepting connections — "
+            "new api_server may fail to bind"
+        )
+    return freed
+
+
 def _launchd_kickstart(label: str, domain: str) -> None:
     """``launchctl kickstart -k domain/label``; raises so callers own per-label failure accounting."""
     subprocess.run(["launchctl", "kickstart", "-k", f"{domain}/{label}"], check=True, timeout=90, **_CAPTURE_TEXT)
@@ -4382,6 +4429,7 @@ def launchd_restart():
                 print(f"⚠ Gateway drain timed out after {wait_budget:.0f}s — forcing launchd restart")
         # Captured: an unloaded job (3/113/125) is the expected case below, which
         # prints its own ↻ line — and e.stderr feeds the update_cmd failure diagnostic.
+        _wait_for_api_server_port_free()
         subprocess.run(["launchctl", "kickstart", "-k", target], check=True, timeout=90, **_CAPTURE_TEXT)
         _launchd_ok("✓ Service restarted")
     except subprocess.CalledProcessError as e:
@@ -6364,6 +6412,7 @@ def _cmd_start(args):
         if killed:
             print(f"✓ Killed {killed} stale gateway process(es) across all profiles")
             _wait_for_gateway_exit(timeout=10.0, force_after=5.0)
+            _wait_for_api_server_port_free()
 
     if is_termux():
         _no_backend_exit("start", "termux")
@@ -6419,6 +6468,7 @@ def _restart_all(system: bool) -> None:
     if total:
         print(f"✓ Stopped {total} gateway process(es) across all profiles")
     _wait_for_gateway_exit(timeout=10.0, force_after=5.0)
+    _wait_for_api_server_port_free()
 
     print("Starting gateway...")
     # Even without a registered task, gateway_windows.start() uses the detached launcher.
@@ -6492,6 +6542,7 @@ def _cmd_restart(args):
     if stop_profile_gateway():
         print("✓ Stopped gateway for this profile")
     _wait_for_gateway_exit(timeout=10.0, force_after=5.0)
+    _wait_for_api_server_port_free()
     print("Starting gateway...")
     run_gateway(verbose=0, force=force)
 
diff --git a/tests/hermes_cli/test_gateway.py b/tests/hermes_cli/test_gateway.py
index d173728396..a71506ebea 100644
--- a/tests/hermes_cli/test_gateway.py
+++ b/tests/hermes_cli/test_gateway.py
@@ -529,6 +529,39 @@ class TestWaitForGatewayExit:
         assert calls == [(22, True)]
 
 
+class TestWaitForTcpPortFree:
+    def test_returns_true_once_connect_fails(self):
+        attempts = {"n": 0}
+
+        def connect(_host, _port):
+            attempts["n"] += 1
+            if attempts["n"] < 3:
+                return True
+            raise OSError("refused")
+
+        times = iter([0.0, 0.0, 0.1, 0.2, 0.3])
+        assert gateway._wait_for_tcp_port_free(
+            "127.0.0.1",
+            8642,
+            timeout=1.0,
+            clock=lambda: next(times),
+            sleeper=lambda _: None,
+            connect=connect,
+        )
+        assert attempts["n"] == 3
+
+    def test_times_out_while_port_stays_busy(self):
+        times = iter([0.0, 0.0, 0.5, 1.5])
+        assert gateway._wait_for_tcp_port_free(
+            "127.0.0.1",
+            8642,
+            timeout=1.0,
+            clock=lambda: next(times),
+            sleeper=lambda _: None,
+            connect=lambda _h, _p: True,
+        ) is False
+
+
 class TestStopProfileGateway:
     def test_windows_stop_drains_marker_before_force_termination(self, monkeypatch):
         """Windows must let the marker watcher run before escalating (#112750)."""

From 5d48722517b6b871fe2a4eae8c61c7a6e1396aab Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:15:08 +0530
Subject: [PATCH 093/190] fix(gateway): restart waits on the configured
 api_server address and treats a slow accept as busy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Folds on the salvaged #92060 (@eliasburlison):

- `_wait_for_api_server_port_free` read only API_SERVER_HOST/PORT from the
  environment, so an api_server port set in config.yaml (`platforms.api_server.port`)
  was never waited on. The adapter's host/port resolution is now the shared
  `gateway.platforms.api_server.listen_address()`, used by both the adapter and the
  restart path, and the wait is skipped when api_server is disabled (a foreign
  listener on the default port is nobody's race).
- Only ECONNREFUSED means the listener is gone. A timed-out connect (full accept
  queue on a draining predecessor) was reported as "free", which would have let the
  replacement start straight into EADDRINUSE again.
- The bind retry in `APIServerAdapter.connect` creates a fresh TCPSite per attempt
  and unregisters the failed one: aiohttp registers the site before binding, so
  re-starting the same object raises "already registered".
- The injected clock/sleeper/connect knobs are gone; the tests bind a real listener.

Tests: a real listener closed 300 ms in → wait returns True; a busy port taken from
config.yaml (env unset) → wait reports busy while enabled and is skipped when disabled.
E2E: with the predecessor releasing the port 0.5 s after the first bind, origin/main
logs `Errno 48 ... address already in use` and connect() returns False; this head
binds on the third attempt (+0.61 s) and connect() returns True.
---
 gateway/platforms/api_server.py  | 39 +++++++++++---------
 hermes_cli/gateway.py            | 51 ++++++++++++--------------
 tests/hermes_cli/test_gateway.py | 61 +++++++++++++++++---------------
 3 files changed, 77 insertions(+), 74 deletions(-)

diff --git a/gateway/platforms/api_server.py b/gateway/platforms/api_server.py
index 8227b2b361..ebc735a254 100644
--- a/gateway/platforms/api_server.py
+++ b/gateway/platforms/api_server.py
@@ -199,6 +199,19 @@ def _hermes_version() -> str:
 # Default settings
 DEFAULT_HOST = "127.0.0.1"
 DEFAULT_PORT = 8642
+
+
+def listen_address(extra: Dict[str, Any]) -> tuple[str, int]:
+    """Host/port the adapter binds: config.yaml ``platforms.api_server`` wins over the env fallbacks.
+
+    Shared with the CLI restart path, which must wait on the SAME address the replacement will
+    bind — an env-only reading missed every config.yaml port (#91547).
+    """
+    host = extra.get("host", os.getenv("API_SERVER_HOST", DEFAULT_HOST))
+    raw_port = extra.get("port")
+    if raw_port is None:
+        raw_port = os.getenv("API_SERVER_PORT", str(DEFAULT_PORT))
+    return host, _coerce_port(raw_port, DEFAULT_PORT)
 MAX_STORED_RESPONSES = 100
 MAX_REQUEST_BYTES = 10_000_000  # 10 MB — accommodates long agent conversations with tool calls
 # Send a comment before remote API clients' common 20-second idle deadline.
@@ -1142,11 +1155,7 @@ class APIServerAdapter(OpenAICompatRoutesMixin, BasePlatformAdapter):
     def __init__(self, config: PlatformConfig):
         super().__init__(config, Platform.API_SERVER)
         extra = config.extra or {}
-        self._host: str = extra.get("host", os.getenv("API_SERVER_HOST", DEFAULT_HOST))
-        raw_port = extra.get("port")
-        if raw_port is None:
-            raw_port = os.getenv("API_SERVER_PORT", str(DEFAULT_PORT))
-        self._port: int = _coerce_port(raw_port, DEFAULT_PORT)
+        self._host, self._port = listen_address(extra)
         self._api_key: str = extra.get("key", _get_scoped_secret("API_SERVER_KEY", ""))
         self._cors_origins: tuple[str, ...] = self._parse_cors_origins(
             extra.get("cors_origins", os.getenv("API_SERVER_CORS_ORIGINS", "")))
@@ -4018,25 +4027,21 @@ class APIServerAdapter(OpenAICompatRoutesMixin, BasePlatformAdapter):
             # while both report success — disable. - Linux: SO_REUSEADDR only permits rebinding past
             # TIME_WAIT (a second live listener needs SO_REUSEPORT, never set), so keep the default
             # (enabled) for instant restart rebinds.
-            self._site = web.TCPSite(
-                self._runner, self._host, self._port, reuse_address=False if sys.platform == "darwin" else None)
             try:
-                last_exc: OSError | None = None
+                # A restart's predecessor may still hold the port for a moment after its PID is gone;
+                # a fresh TCPSite per attempt (a failed one stays registered in the runner) bounds the
+                # retry before the conflict is treated as a real config error.
                 for attempt in range(5):
+                    self._site = web.TCPSite(
+                        self._runner, self._host, self._port, reuse_address=False if sys.platform == "darwin" else None)
                     try:
                         await self._site.start()
-                        last_exc = None
                         break
                     except OSError as exc:
-                        last_exc = exc
-                        if (
-                            getattr(exc, "errno", None) != errno.EADDRINUSE
-                            or attempt == 4
-                        ):
-                            break
+                        self._runner._unreg_site(self._site)
+                        if getattr(exc, "errno", None) != errno.EADDRINUSE or attempt == 4:
+                            raise
                         await asyncio.sleep(0.2 * (attempt + 1))
-                if last_exc is not None:
-                    raise last_exc
             except OSError as exc:
                 await self._runner.cleanup()
                 self._runner = None
diff --git a/hermes_cli/gateway.py b/hermes_cli/gateway.py
index 35b479bdd5..f5c11069d7 100644
--- a/hermes_cli/gateway.py
+++ b/hermes_cli/gateway.py
@@ -4328,44 +4328,37 @@ def _wait_for_gateway_exit(timeout: float = 10.0, force_after: float | None = 5.
     return True
 
 
-def _wait_for_tcp_port_free(
-    host: str,
-    port: int,
-    *,
-    timeout: float = 10.0,
-    clock=time.monotonic,
-    sleeper=time.sleep,
-    connect=None,
-) -> bool:
+def _wait_for_tcp_port_free(host: str, port: int, *, timeout: float = 10.0) -> bool:
     """Wait until nothing accepts TCP connections on host:port.
 
-    PID exit is not enough on macOS: api_server disables SO_REUSEADDR, so a
-    restart that wins the race logs EADDRINUSE and keeps running with no API.
-    Connection-refused means the listener is gone.
+    PID exit is not enough on macOS: api_server disables SO_REUSEADDR, so a restart that wins
+    the race logs EADDRINUSE and keeps running with no API. Only connection-refused means the
+    listener is gone; a timed-out connect is a live listener with a slow accept queue.
     """
-    probe = connect
-    if probe is None:
-        def probe(target_host: str, target_port: int) -> bool:
-            with socket.create_connection((target_host, target_port), timeout=0.2):
-                return True
-
-    deadline = clock() + timeout
-    while clock() < deadline:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
         try:
-            probe(host, port)
-        except OSError:
+            with socket.create_connection((host, port), timeout=0.2):
+                pass
+        except ConnectionRefusedError:
             return True
-        sleeper(0.1)
+        except OSError:
+            pass
+        time.sleep(0.1)
     return False
 
 
 def _wait_for_api_server_port_free(*, timeout: float = 10.0) -> bool:
-    """Wait for the configured api_server listen address to stop accepting."""
-    host = os.getenv("API_SERVER_HOST", "127.0.0.1") or "127.0.0.1"
-    try:
-        port = int(os.getenv("API_SERVER_PORT", "8642"))
-    except ValueError:
-        port = 8642
+    """Wait for the configured api_server listen address to stop accepting.
+
+    Only when api_server is enabled: with the platform off, a foreign listener on the default
+    port is nobody's race and must not delay the restart."""
+    from gateway.config import Platform
+    from gateway.platforms.api_server import listen_address
+    pconfig = load_gateway_config().platforms.get(Platform.API_SERVER)
+    if pconfig is None or not pconfig.enabled:
+        return True
+    host, port = listen_address(pconfig.extra or {})
     freed = _wait_for_tcp_port_free(host, port, timeout=timeout)
     if not freed:
         print(
diff --git a/tests/hermes_cli/test_gateway.py b/tests/hermes_cli/test_gateway.py
index a71506ebea..50aa0fa2e3 100644
--- a/tests/hermes_cli/test_gateway.py
+++ b/tests/hermes_cli/test_gateway.py
@@ -529,37 +529,42 @@ class TestWaitForGatewayExit:
         assert calls == [(22, True)]
 
 
-class TestWaitForTcpPortFree:
-    def test_returns_true_once_connect_fails(self):
-        attempts = {"n": 0}
+class TestRestartWaitsForApiServerPort:
+    """Regression for #91547: ``hermes gateway restart`` waited only for the old PID; on macOS the
+    replacement then hit EADDRINUSE and ran with no API server."""
 
-        def connect(_host, _port):
-            attempts["n"] += 1
-            if attempts["n"] < 3:
-                return True
-            raise OSError("refused")
+    def test_port_is_reported_free_once_the_old_listener_closes(self):
+        import socket
+        import threading
 
-        times = iter([0.0, 0.0, 0.1, 0.2, 0.3])
-        assert gateway._wait_for_tcp_port_free(
-            "127.0.0.1",
-            8642,
-            timeout=1.0,
-            clock=lambda: next(times),
-            sleeper=lambda _: None,
-            connect=connect,
-        )
-        assert attempts["n"] == 3
+        listener = socket.socket()
+        listener.bind(("127.0.0.1", 0))
+        listener.listen(8)
+        port = listener.getsockname()[1]
+        threading.Timer(0.3, listener.close).start()
 
-    def test_times_out_while_port_stays_busy(self):
-        times = iter([0.0, 0.0, 0.5, 1.5])
-        assert gateway._wait_for_tcp_port_free(
-            "127.0.0.1",
-            8642,
-            timeout=1.0,
-            clock=lambda: next(times),
-            sleeper=lambda _: None,
-            connect=lambda _h, _p: True,
-        ) is False
+        assert gateway._wait_for_tcp_port_free("127.0.0.1", port, timeout=5.0) is True
+
+    def test_wait_targets_the_configured_api_server_port_only_when_enabled(self, monkeypatch):
+        import socket
+
+        from gateway.config import GatewayConfig, Platform, PlatformConfig
+
+        listener = socket.socket()
+        listener.bind(("127.0.0.1", 0))
+        listener.listen(8)
+        port = listener.getsockname()[1]
+        cfg = GatewayConfig()
+        cfg.platforms[Platform.API_SERVER] = PlatformConfig(enabled=True, extra={"port": port})
+        monkeypatch.setattr(gateway, "load_gateway_config", lambda: cfg)
+        monkeypatch.delenv("API_SERVER_PORT", raising=False)
+        try:
+            # config.yaml port wins over the env default: the busy configured port is what we wait on
+            assert gateway._wait_for_api_server_port_free(timeout=0.3) is False
+            cfg.platforms[Platform.API_SERVER].enabled = False
+            assert gateway._wait_for_api_server_port_free(timeout=0.3) is True
+        finally:
+            listener.close()
 
 
 class TestStopProfileGateway:

From 182f623fe50aee814e303153ed71cadcbd6da483 Mon Sep 17 00:00:00 2001
From: finn763 <165816600+finn763@users.noreply.github.com>
Date: Thu, 17 Sep 2026 04:29:39 +0800
Subject: [PATCH 094/190] fix(gateway): a boot that lost a configured platform
 must not report itself as a normal run

The shared startup gate returned early whenever any sibling platform connected,
so a non-retryable fatal platform failure left one WARNING and a 'running'
runtime state: the gateway served messaging while every API client was gone,
with nothing retried and no observable trace.

Park the failures, log at ERROR and stamp gateway_state 'degraded'. Retryable
peers are untouched (the reconnect watcher heals them). Behaviour and exit code
unchanged; only logging and health reporting. Port-race half of the report is
left to the open PRs #92060/#96419.

(cherry picked from commit edfb98f86911b70aa247ab0f718f0218002e154e)
---
 gateway/run_startup.py                        |  31 +++-
 ...tartup_failed_platform_reports_degraded.py | 153 ++++++++++++++++++
 2 files changed, 182 insertions(+), 2 deletions(-)
 create mode 100644 tests/gateway/test_startup_failed_platform_reports_degraded.py

diff --git a/gateway/run_startup.py b/gateway/run_startup.py
index 4686582bb4..af395f1330 100644
--- a/gateway/run_startup.py
+++ b/gateway/run_startup.py
@@ -40,6 +40,11 @@ logger = logging.getLogger("gateway.run")
 class GatewayStartupMixin:
     """Startup sequence, resume/restore and handoff methods for GatewayRunner."""
 
+    # Non-retryable platform failures this boot left the gateway serving WITHOUT: recorded by
+    # ``_start_handle_no_connections`` and consumed when the runtime state is stamped, so a boot that
+    # lost a configured platform never reports itself as a normal run.
+    _startup_parked_platforms: Optional[str] = None
+
     async def _run_startup_resume_event(
         self, adapter: BasePlatformAdapter, event: MessageEvent, session_key: str,
     ) -> None:
@@ -1226,9 +1231,27 @@ class GatewayStartupMixin:
         self, connected_count: int, enabled_platform_count: int, startup_retryable_errors: list,
         startup_nonretryable_errors: list,
     ) -> bool:
-        """Log/degrade when nothing connected; return True when startup must exit."""
+        """Log/degrade when a configured platform failed to start; return True when startup must exit.
+
+        The SHARED gate for every platform, not the api_server path: a configured platform that never
+        came up must leave a loud, observable trace (ERROR + a ``degraded`` runtime state) even while
+        sibling platforms serve normally. One WARNING next to "Gateway running with N platform(s)" let
+        a gateway with no API server at all look healthy for half an hour (api_server lost the bind
+        race against the gateway it was replacing, and nothing retried).
+        """
         from gateway.run import _write_runtime_status_quiet
         if connected_count != 0:
+            if startup_nonretryable_errors:
+                # Parked fatal failures never heal on their own, so the platforms still serving must
+                # not be reported as a healthy run. Retryable peers are deliberately left alone: the
+                # reconnect watcher recovers them and their platform entry already says "retrying".
+                self._startup_parked_platforms = "; ".join(startup_nonretryable_errors)
+                logger.error(
+                    "%d configured platform(s) failed to start and are parked (fix the reported error, "
+                    "then `/platform resume <platform>`): %s. The gateway is DEGRADED — it serves the "
+                    "remaining platform(s) with those unserved.",
+                    len(startup_nonretryable_errors), self._startup_parked_platforms,
+                )
             return False
         if startup_nonretryable_errors and not startup_retryable_errors:
             reason = "; ".join(startup_nonretryable_errors)
@@ -1417,6 +1440,7 @@ class GatewayStartupMixin:
         self._start_startup_warmup()
         startup_nonretryable_errors: list[str] = []
         startup_retryable_errors: list[str] = []
+        self._startup_parked_platforms = None  # fresh boot: no platform has failed yet
         (
             _aborted, enabled_platform_count, _multiplex_skipped_platforms, _pending_connects
         ) = await self._start_prefilter_platforms()
@@ -1447,7 +1471,10 @@ class GatewayStartupMixin:
         self._wire_teams_pipeline_runtime()
         self._running = True
         self._install_plugin_message_injector()
-        self._update_runtime_status("running")
+        # A boot that could not start every configured platform is not a normal run: stamp ``degraded``
+        # so ``gateway status`` / /api/status / the health snapshot surface it, instead of only a log
+        # line next to "Gateway running with N platform(s)".
+        self._update_runtime_status("degraded" if self._startup_parked_platforms else "running")
         await self._start_finish_wiring(connected_count)
         self._start_spawn_background_watchers()
         logger.info("Press Ctrl+C to stop")
diff --git a/tests/gateway/test_startup_failed_platform_reports_degraded.py b/tests/gateway/test_startup_failed_platform_reports_degraded.py
new file mode 100644
index 0000000000..e91688d0c0
--- /dev/null
+++ b/tests/gateway/test_startup_failed_platform_reports_degraded.py
@@ -0,0 +1,153 @@
+"""A configured platform that fails to start must not let the gateway report a normal run.
+
+api_server lost the bind race against the gateway it was replacing (Errno 48 / 10048), logged
+``✗ api_server failed to connect`` at WARNING, and carried on serving its messaging platforms. The
+startup summary said ``Gateway running with 1 platform(s)`` and the runtime state said ``running``:
+status looked healthy, every API client was gone, nothing retried. The startup summary is the SHARED
+gate — every platform, not just api_server — so the same failure on any other platform is reported
+the same way.
+"""
+import logging
+
+import pytest
+
+from gateway.config import GatewayConfig, Platform, PlatformConfig
+from gateway.platforms.base import BasePlatformAdapter
+from gateway.run import GatewayRunner
+from gateway.status import read_runtime_status
+
+
+class _PortTakenAdapter(BasePlatformAdapter):
+    """Loses the bind race exactly like api_server: fatal AND non-retryable, so it is parked."""
+
+    def __init__(self):
+        super().__init__(PlatformConfig(enabled=True, extra={"port": 8642}), Platform.API_SERVER)
+
+    async def connect(self, *, is_reconnect: bool = False) -> bool:
+        self._set_fatal_error(
+            "api_server_port_in_use",
+            "Port 8642 already in use. Set platforms.api_server.port in config.yaml to a different "
+            "value, then `/platform resume api_server`.",
+            retryable=False,
+        )
+        return False
+
+    async def disconnect(self) -> None:
+        self._mark_disconnected()
+
+    async def send(self, chat_id, content, reply_to=None, metadata=None):
+        raise NotImplementedError
+
+    async def get_chat_info(self, chat_id):
+        return {"id": chat_id}
+
+
+class _HealthyAdapter(BasePlatformAdapter):
+    """The messaging platform that keeps the gateway useful — and used to hide the failure."""
+
+    def __init__(self):
+        super().__init__(PlatformConfig(enabled=True, token="***"), Platform.TELEGRAM)
+
+    async def connect(self, *, is_reconnect: bool = False) -> bool:
+        return True
+
+    async def disconnect(self) -> None:
+        self._mark_disconnected()
+
+    async def send(self, chat_id, content, reply_to=None, metadata=None):
+        raise NotImplementedError
+
+    async def get_chat_info(self, chat_id):
+        return {"id": chat_id}
+
+
+def _runner_with_one_parked_platform(monkeypatch, tmp_path) -> GatewayRunner:
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+    config = GatewayConfig(
+        platforms={
+            Platform.API_SERVER: PlatformConfig(enabled=True, extra={"port": 8642}),
+            Platform.TELEGRAM: PlatformConfig(enabled=True, token="***"),
+        },
+        sessions_dir=tmp_path / "sessions",
+    )
+    runner = GatewayRunner(config)
+    monkeypatch.setattr(
+        runner,
+        "_create_adapter",
+        lambda platform, platform_config: (
+            _PortTakenAdapter() if platform is Platform.API_SERVER else _HealthyAdapter()
+        ),
+    )
+    async def _no_secondary_profiles():
+        return 0
+
+    monkeypatch.setattr(runner, "_start_secondary_profile_adapters", _no_secondary_profiles)
+    return runner
+
+
+@pytest.mark.asyncio
+async def test_parked_platform_is_reported_at_error_when_others_serve(monkeypatch, tmp_path, caplog):
+    """The failure is logged at ERROR — not only the WARNING that hid it."""
+    runner = _runner_with_one_parked_platform(monkeypatch, tmp_path)
+
+    with caplog.at_level(logging.ERROR):
+        ok = await runner.start()
+    try:
+        assert ok is True, "the working platform keeps the gateway alive; only reporting changes"
+        assert runner.should_exit_cleanly is False
+        assert any(
+            record.levelno >= logging.ERROR and "api_server" in record.getMessage()
+            for record in caplog.records
+        ), "a configured platform that never came up must be reported at ERROR, not only a WARNING"
+    finally:
+        await runner.stop()
+
+
+@pytest.mark.asyncio
+async def test_parked_platform_is_not_reported_as_a_normal_run(monkeypatch, tmp_path):
+    """The runtime state must not claim a normal run while a configured platform is unserved."""
+    runner = _runner_with_one_parked_platform(monkeypatch, tmp_path)
+
+    ok = await runner.start()
+    try:
+        assert ok is True
+        assert runner.should_exit_cleanly is False
+        state = read_runtime_status()
+        assert state["gateway_state"] == "degraded", (
+            "the gateway is serving with a configured platform missing — it must not claim a normal run"
+        )
+        assert state["platforms"]["api_server"]["state"] == "fatal"
+        assert state["platforms"]["api_server"]["error_code"] == "api_server_port_in_use"
+        assert state["platforms"]["telegram"]["state"] == "connected"
+    finally:
+        await runner.stop()
+
+
+@pytest.mark.asyncio
+async def test_every_platform_connected_still_reports_a_normal_run(monkeypatch, tmp_path, caplog):
+    """Protection: a clean startup keeps the normal ``running`` state and logs no ERROR."""
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+    config = GatewayConfig(
+        platforms={Platform.TELEGRAM: PlatformConfig(enabled=True, token="***")},
+        sessions_dir=tmp_path / "sessions",
+    )
+    runner = GatewayRunner(config)
+    monkeypatch.setattr(runner, "_create_adapter", lambda platform, platform_config: _HealthyAdapter())
+
+    async def _no_secondary_profiles():
+        return 0
+
+    monkeypatch.setattr(runner, "_start_secondary_profile_adapters", _no_secondary_profiles)
+
+    with caplog.at_level(logging.ERROR):
+        ok = await runner.start()
+    try:
+        assert ok is True
+        state = read_runtime_status()
+        assert state["gateway_state"] == "running"
+        assert state["platforms"]["telegram"]["state"] == "connected"
+        assert not [r for r in caplog.records if r.levelno >= logging.ERROR], (
+            "a healthy startup must not log ERROR"
+        )
+    finally:
+        await runner.stop()

From ab4433812bc445eb1a10fdfbc910d9aab0fc913a Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:17:18 +0530
Subject: [PATCH 095/190] test(gateway): fold the two parked-platform
 assertions into one invariant

ERROR log and the degraded runtime state come from the same boot; one test
asserts both, the clean-boot negative control stays.
---
 ...tartup_failed_platform_reports_degraded.py | 24 ++++---------------
 1 file changed, 5 insertions(+), 19 deletions(-)

diff --git a/tests/gateway/test_startup_failed_platform_reports_degraded.py b/tests/gateway/test_startup_failed_platform_reports_degraded.py
index e91688d0c0..5c6fcbe540 100644
--- a/tests/gateway/test_startup_failed_platform_reports_degraded.py
+++ b/tests/gateway/test_startup_failed_platform_reports_degraded.py
@@ -86,8 +86,9 @@ def _runner_with_one_parked_platform(monkeypatch, tmp_path) -> GatewayRunner:
 
 
 @pytest.mark.asyncio
-async def test_parked_platform_is_reported_at_error_when_others_serve(monkeypatch, tmp_path, caplog):
-    """The failure is logged at ERROR — not only the WARNING that hid it."""
+async def test_parked_platform_is_logged_at_error_and_the_run_is_degraded(monkeypatch, tmp_path, caplog):
+    """A configured platform that never came up is reported at ERROR (not the WARNING that hid it)
+    and the runtime state says ``degraded`` while the surviving platform keeps the gateway alive."""
     runner = _runner_with_one_parked_platform(monkeypatch, tmp_path)
 
     with caplog.at_level(logging.ERROR):
@@ -98,24 +99,9 @@ async def test_parked_platform_is_reported_at_error_when_others_serve(monkeypatc
         assert any(
             record.levelno >= logging.ERROR and "api_server" in record.getMessage()
             for record in caplog.records
-        ), "a configured platform that never came up must be reported at ERROR, not only a WARNING"
-    finally:
-        await runner.stop()
-
-
-@pytest.mark.asyncio
-async def test_parked_platform_is_not_reported_as_a_normal_run(monkeypatch, tmp_path):
-    """The runtime state must not claim a normal run while a configured platform is unserved."""
-    runner = _runner_with_one_parked_platform(monkeypatch, tmp_path)
-
-    ok = await runner.start()
-    try:
-        assert ok is True
-        assert runner.should_exit_cleanly is False
-        state = read_runtime_status()
-        assert state["gateway_state"] == "degraded", (
-            "the gateway is serving with a configured platform missing — it must not claim a normal run"
         )
+        state = read_runtime_status()
+        assert state["gateway_state"] == "degraded"
         assert state["platforms"]["api_server"]["state"] == "fatal"
         assert state["platforms"]["api_server"]["error_code"] == "api_server_port_in_use"
         assert state["platforms"]["telegram"]["state"] == "connected"

From ed8f8498d32e3bb92fa37596be90d3959e585f3c Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:54:44 +0530
Subject: [PATCH 096/190] fix(gateway): a degraded boot stays degraded and
 still counts as a completed restart
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Gate review on the stack:

- `hermes gateway restart` under systemd only accepted `gateway_state == "running"`
  as proof of the replacement; a boot with a parked platform stamps `degraded` for
  its whole life, so every restart/update on such a host waited out the 60 s+
  budget and reported a false failure while the gateway was serving. The verifier
  now accepts `degraded` as restarted and prints one DEGRADED warning.
- Drain release and scale-to-zero wake re-stamped `running` unconditionally, wiping
  the parked-platform signal after the first `.drain_request.json` cycle. Every
  "we are serving" stamp now goes through `_serving_state()`; the mixed fatal +
  retryable boot path sets the flag too (it fell through as a plain run before).
  `_startup_parked_platforms` is a bool — the joined error text was only ever logged.
- `_wait_for_tcp_port_free`: an unresolvable or unreachable configured host raised
  a non-refused OSError on every probe and burned the full 10 s wait; only a
  connect timeout means "listener alive", anything else means nothing to wait for.
- Windows `restart()` replaces its blind `time.sleep(1.0)` "let Windows release the
  port" with the same configured-address wait.
- The api_server bind retry rebuilds the AppRunner per EADDRINUSE attempt instead of
  calling aiohttp's private `_unreg_site`; attempt count is a named constant.

Test: a `degraded` replacement is reported as restarted (red on the previous head).
E2E re-run: predecessor releases the port 0.5 s after the first bind → bound on the
third attempt (+0.61 s), connect() True.
---
 gateway/platforms/api_server.py          | 15 +++++++++------
 gateway/run_shutdown.py                  |  8 ++++----
 gateway/run_startup.py                   | 19 +++++++++++--------
 hermes_cli/gateway.py                    | 12 +++++++++---
 hermes_cli/gateway_windows.py            |  4 +++-
 tests/hermes_cli/test_gateway_service.py | 21 +++++++++++++++++++++
 6 files changed, 57 insertions(+), 22 deletions(-)

diff --git a/gateway/platforms/api_server.py b/gateway/platforms/api_server.py
index ebc735a254..2798bf1037 100644
--- a/gateway/platforms/api_server.py
+++ b/gateway/platforms/api_server.py
@@ -199,6 +199,7 @@ def _hermes_version() -> str:
 # Default settings
 DEFAULT_HOST = "127.0.0.1"
 DEFAULT_PORT = 8642
+_BIND_ATTEMPTS = 5  # EADDRINUSE retries while a restart's predecessor releases the port (#91547)
 
 
 def listen_address(extra: Dict[str, Any]) -> tuple[str, int]:
@@ -4028,19 +4029,21 @@ class APIServerAdapter(OpenAICompatRoutesMixin, BasePlatformAdapter):
             # TIME_WAIT (a second live listener needs SO_REUSEPORT, never set), so keep the default
             # (enabled) for instant restart rebinds.
             try:
-                # A restart's predecessor may still hold the port for a moment after its PID is gone;
-                # a fresh TCPSite per attempt (a failed one stays registered in the runner) bounds the
-                # retry before the conflict is treated as a real config error.
-                for attempt in range(5):
+                # A restart's predecessor may still hold the port for a moment after its PID is gone.
+                # aiohttp registers a site with its runner before binding, so a failed start leaves the
+                # site registered: rebuild the runner per attempt rather than reach into its internals.
+                for attempt in range(_BIND_ATTEMPTS):
                     self._site = web.TCPSite(
                         self._runner, self._host, self._port, reuse_address=False if sys.platform == "darwin" else None)
                     try:
                         await self._site.start()
                         break
                     except OSError as exc:
-                        self._runner._unreg_site(self._site)
-                        if getattr(exc, "errno", None) != errno.EADDRINUSE or attempt == 4:
+                        if exc.errno != errno.EADDRINUSE or attempt == _BIND_ATTEMPTS - 1:
                             raise
+                        await self._runner.cleanup()
+                        self._runner = web.AppRunner(self._app)
+                        await self._runner.setup()
                         await asyncio.sleep(0.2 * (attempt + 1))
             except OSError as exc:
                 await self._runner.cleanup()
diff --git a/gateway/run_shutdown.py b/gateway/run_shutdown.py
index 96fa0fc72d..1483b985c1 100644
--- a/gateway/run_shutdown.py
+++ b/gateway/run_shutdown.py
@@ -439,7 +439,7 @@ class GatewayShutdownMixin:
         """
         self._last_inbound_at = time.time()
         if getattr(self, "_scale_to_zero_cooldown_until", 0.0) > 0:
-            self._scale_to_zero_status("running", "scale-to-zero: status restore failed")
+            self._scale_to_zero_status(self._serving_state(), "scale-to-zero: status restore failed")
             self._scale_to_zero_cooldown_until = 0.0
 
     def _scale_to_zero_status(self, state: str, fail_msg: str) -> None:
@@ -626,7 +626,7 @@ class GatewayShutdownMixin:
         # Same guard as _exit_external_drain: a real shutdown drain must win, so never resurrect
         # a stopping gateway to `running`.
         if not getattr(self, "_draining", False) and self._running:
-            self._scale_to_zero_status("running", "scale-to-zero: status restore failed")
+            self._scale_to_zero_status(self._serving_state(), "scale-to-zero: status restore failed")
         # An abort before the cooldown is set would otherwise retry every tick.
         self._scale_to_zero_cooldown_until = max(
             self._scale_to_zero_cooldown_until, time.time() + 60.0
@@ -676,9 +676,9 @@ class GatewayShutdownMixin:
             return
         logger.info(
             "External drain RELEASED (.drain_request.json removed) — "
-            "re-accepting new turns; gateway_state -> running."
+            "re-accepting new turns; gateway_state -> %s.", self._serving_state(),
         )
-        self._update_runtime_status("running")
+        self._update_runtime_status(self._serving_state())
 
     async def _drain_control_watcher(self, interval: float = 1.0) -> None:
         """Poll ``.drain_request.json`` at 1s: present -> enter drain, absent -> exit; a stale epoch = absent."""
diff --git a/gateway/run_startup.py b/gateway/run_startup.py
index af395f1330..a97622aa1c 100644
--- a/gateway/run_startup.py
+++ b/gateway/run_startup.py
@@ -40,10 +40,12 @@ logger = logging.getLogger("gateway.run")
 class GatewayStartupMixin:
     """Startup sequence, resume/restore and handoff methods for GatewayRunner."""
 
-    # Non-retryable platform failures this boot left the gateway serving WITHOUT: recorded by
-    # ``_start_handle_no_connections`` and consumed when the runtime state is stamped, so a boot that
-    # lost a configured platform never reports itself as a normal run.
-    _startup_parked_platforms: Optional[str] = None
+    # A configured platform failed non-retryably this boot and is parked: every "we are serving"
+    # status stamp (startup, drain release, scale-to-zero wake) must say ``degraded``, not ``running``.
+    _startup_parked_platforms: bool = False
+
+    def _serving_state(self) -> str:
+        return "degraded" if self._startup_parked_platforms else "running"
 
     async def _run_startup_resume_event(
         self, adapter: BasePlatformAdapter, event: MessageEvent, session_key: str,
@@ -1245,12 +1247,12 @@ class GatewayStartupMixin:
                 # Parked fatal failures never heal on their own, so the platforms still serving must
                 # not be reported as a healthy run. Retryable peers are deliberately left alone: the
                 # reconnect watcher recovers them and their platform entry already says "retrying".
-                self._startup_parked_platforms = "; ".join(startup_nonretryable_errors)
+                self._startup_parked_platforms = True
                 logger.error(
                     "%d configured platform(s) failed to start and are parked (fix the reported error, "
                     "then `/platform resume <platform>`): %s. The gateway is DEGRADED — it serves the "
                     "remaining platform(s) with those unserved.",
-                    len(startup_nonretryable_errors), self._startup_parked_platforms,
+                    len(startup_nonretryable_errors), "; ".join(startup_nonretryable_errors),
                 )
             return False
         if startup_nonretryable_errors and not startup_retryable_errors:
@@ -1261,6 +1263,7 @@ class GatewayStartupMixin:
         if startup_nonretryable_errors:
             # Mixed (some fatal, some transient): exiting 78 would take the gateway PERMANENTLY down
             # over a blip. Log the fatal side loudly and fall through to the degraded/retry path.
+            self._startup_parked_platforms = True
             logger.error(
                 # WhatsApp enabled but never paired) while others hit merely transient errors (e.g. Telegram
                 # TimedOut during polling startup). Exiting with GATEWAY_FATAL_CONFIG_EXIT_CODE here is
@@ -1440,7 +1443,7 @@ class GatewayStartupMixin:
         self._start_startup_warmup()
         startup_nonretryable_errors: list[str] = []
         startup_retryable_errors: list[str] = []
-        self._startup_parked_platforms = None  # fresh boot: no platform has failed yet
+        self._startup_parked_platforms = False  # fresh boot: no platform has failed yet
         (
             _aborted, enabled_platform_count, _multiplex_skipped_platforms, _pending_connects
         ) = await self._start_prefilter_platforms()
@@ -1474,7 +1477,7 @@ class GatewayStartupMixin:
         # A boot that could not start every configured platform is not a normal run: stamp ``degraded``
         # so ``gateway status`` / /api/status / the health snapshot surface it, instead of only a log
         # line next to "Gateway running with N platform(s)".
-        self._update_runtime_status("degraded" if self._startup_parked_platforms else "running")
+        self._update_runtime_status(self._serving_state())
         await self._start_finish_wiring(connected_count)
         self._start_spawn_background_watchers()
         logger.info("Press Ctrl+C to stop")
diff --git a/hermes_cli/gateway.py b/hermes_cli/gateway.py
index f5c11069d7..c90580de8d 100644
--- a/hermes_cli/gateway.py
+++ b/hermes_cli/gateway.py
@@ -1223,8 +1223,12 @@ def _wait_for_systemd_service_restart(
                 if runtime_state and _runtime_state_pid(runtime_state) != new_pid:
                     runtime_state = None
             gateway_state = (runtime_state or {}).get("gateway_state")
-            if gateway_state == "running":
+            if gateway_state in ("running", "degraded"):
                 print(f"✓ {scope_label} service restarted (PID {new_pid})")
+                if gateway_state == "degraded":
+                    # Serving, but a configured platform is parked or retrying: a real restart, not a
+                    # failure — say so instead of waiting out the timeout and reporting one.
+                    print(f"⚠ {scope_label} gateway is DEGRADED — see `hermes gateway status`")
                 return True
             if gateway_state == "startup_failed":
                 reason = (runtime_state or {}).get("exit_reason") or "startup failed"
@@ -4332,7 +4336,7 @@ def _wait_for_tcp_port_free(host: str, port: int, *, timeout: float = 10.0) -> b
     """Wait until nothing accepts TCP connections on host:port.
 
     PID exit is not enough on macOS: api_server disables SO_REUSEADDR, so a restart that wins
-    the race logs EADDRINUSE and keeps running with no API. Only connection-refused means the
+    the race logs EADDRINUSE and keeps running with no API. Connection-refused means the
     listener is gone; a timed-out connect is a live listener with a slow accept queue.
     """
     deadline = time.monotonic() + timeout
@@ -4342,8 +4346,10 @@ def _wait_for_tcp_port_free(host: str, port: int, *, timeout: float = 10.0) -> b
                 pass
         except ConnectionRefusedError:
             return True
+        except TimeoutError:
+            pass  # a slow accept queue is still a live listener
         except OSError:
-            pass
+            return True  # unresolvable/unreachable address: nothing to wait for; the bind retry covers it
         time.sleep(0.1)
     return False
 
diff --git a/hermes_cli/gateway_windows.py b/hermes_cli/gateway_windows.py
index 098c506720..e90b4cb981 100644
--- a/hermes_cli/gateway_windows.py
+++ b/hermes_cli/gateway_windows.py
@@ -1671,7 +1671,9 @@ def restart() -> None:
                 "start a duplicate. Investigate stray PIDs before retrying."
             )
 
-    time.sleep(1.0)   # let Windows release the listening port
+    from hermes_cli.gateway import _wait_for_api_server_port_free  # avoid circular init
+
+    _wait_for_api_server_port_free()
     start()
 
     if not _wait_for_gateway_ready(timeout_s=15.0):
diff --git a/tests/hermes_cli/test_gateway_service.py b/tests/hermes_cli/test_gateway_service.py
index 5bc28e7e3e..319c3789b7 100644
--- a/tests/hermes_cli/test_gateway_service.py
+++ b/tests/hermes_cli/test_gateway_service.py
@@ -1115,6 +1115,27 @@ class TestGatewaySystemServiceRouting:
         assert result is False
         assert replacement_observed == [True]
 
+    def test_wait_accepts_a_degraded_replacement_as_restarted(self, monkeypatch, capsys):
+        """A replacement serving with a parked platform stamps ``degraded`` for its whole life; the
+        restart verifier must report a restart (with a warning), not wait out the timeout (#91547)."""
+        monkeypatch.setattr(gateway_cli.time, "sleep", lambda _seconds: None)
+        monkeypatch.setattr(
+            gateway_cli,
+            "_read_systemd_unit_properties",
+            lambda system=False, properties=None: {"ActiveState": "active", "MainPID": "777"},
+        )
+        monkeypatch.setattr("gateway.status.get_running_pid", lambda: 777)
+        monkeypatch.setattr(
+            gateway_cli,
+            "_read_gateway_runtime_status",
+            lambda: {"pid": 777, "gateway_state": "degraded"},
+        )
+
+        result = gateway_cli._wait_for_systemd_service_restart(previous_pid=654, timeout=1.0)
+
+        assert result is True
+        assert "DEGRADED" in capsys.readouterr().out
+
     def test_launchd_restart_uses_sigusr1_and_exit_wait_budget(self, monkeypatch, capsys):
         """launchd_restart must take the same graceful path as systemd_restart.
 

From b97b0c6bc9b8d862f69aaccf40751da93396d053 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 01:12:13 +0530
Subject: [PATCH 097/190] fix(gateway): every live-state check knows a degraded
 gateway is serving

Gate review: `degraded` became a whole-life serving state but four
sibling predicates only accepted `running`: derive_gateway_busy /
derive_gateway_drainable (the NAS drain gate reported a degraded gateway
with in-flight turns as idle and undrainable), the stale-heartbeat
detectors in `hermes gateway status` and the dashboard, and the Windows
doctor probe. All four accept `degraded`; a dead watchdog-stamped
`degraded` is still excluded by `gateway_running=False`.

The parked-platform ERROR pointed at `/platform resume`, which only
resumes platforms in the retry queue - a non-retryable failure never
enters it. The remedy is `hermes gateway restart`.

Test: a degraded gateway with active agents is busy; not live => not
drainable.
---
 gateway/run_startup.py           | 2 +-
 gateway/status.py                | 9 +++++----
 hermes_cli/gateway.py            | 2 +-
 hermes_cli/gateway_windows.py    | 2 +-
 hermes_cli/web_routers/status.py | 2 +-
 tests/gateway/test_status.py     | 9 +++++++++
 6 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/gateway/run_startup.py b/gateway/run_startup.py
index a97622aa1c..a8dc7f05d7 100644
--- a/gateway/run_startup.py
+++ b/gateway/run_startup.py
@@ -1250,7 +1250,7 @@ class GatewayStartupMixin:
                 self._startup_parked_platforms = True
                 logger.error(
                     "%d configured platform(s) failed to start and are parked (fix the reported error, "
-                    "then `/platform resume <platform>`): %s. The gateway is DEGRADED — it serves the "
+                    "then `hermes gateway restart`): %s. The gateway is DEGRADED — it serves the "
                     "remaining platform(s) with those unserved.",
                     len(startup_nonretryable_errors), "; ".join(startup_nonretryable_errors),
                 )
diff --git a/gateway/status.py b/gateway/status.py
index b351cd03fd..9419b6bf60 100644
--- a/gateway/status.py
+++ b/gateway/status.py
@@ -944,12 +944,13 @@ def parse_active_agents(raw: Any) -> int:
         return 0
 
 
-# Only a live ``running`` gateway is a valid begin-drain target.
-_DRAINABLE_GATEWAY_STATES = frozenset({"running"})
+# Live, serving states: a valid begin-drain target. ``degraded`` is a serving gateway with a parked
+# platform (a dead watchdog-stamped ``degraded`` is already excluded by ``gateway_running=False``).
+_DRAINABLE_GATEWAY_STATES = frozenset({"running", "degraded"})
 
 
 def derive_gateway_busy(*, gateway_running: bool, gateway_state: Any, active_agents: Any) -> bool:
-    """Busy iff live, ``running``, and ``active_agents > 0`` -- the contract NAS gates on. Liveness
+    """Busy iff live, serving (``running``/``degraded``), and ``active_agents > 0`` -- the contract NAS gates on. Liveness
     keys off ``gateway_running``, NEVER ``updated_at`` (a stale heartbeat is a health warning, not death)."""
     if not derive_gateway_drainable(gateway_running=gateway_running, gateway_state=gateway_state):
         return False
@@ -957,7 +958,7 @@ def derive_gateway_busy(*, gateway_running: bool, gateway_state: Any, active_age
 
 
 def derive_gateway_drainable(*, gateway_running: bool, gateway_state: Any) -> bool:
-    """Drainable iff live and ``running``; independent of ``active_agents`` (idle drains finish)."""
+    """Drainable iff live and serving; independent of ``active_agents`` (idle drains finish)."""
     return bool(gateway_running) and gateway_state in _DRAINABLE_GATEWAY_STATES
 
 
diff --git a/hermes_cli/gateway.py b/hermes_cli/gateway.py
index c90580de8d..dcdec3f6b9 100644
--- a/hermes_cli/gateway.py
+++ b/hermes_cli/gateway.py
@@ -5173,7 +5173,7 @@ def _runtime_health_lines() -> list[str]:
 
     # A live-claiming snapshot can outlive an ungracefully killed gateway (taskkill /F, OOM). Past
     # the freshness TTL with the recorded PID gone, say so instead of rendering stale live state.
-    if gateway_state in ("running", "starting", "draining") and runtime_status_is_stale(state):
+    if gateway_state in ("running", "degraded", "starting", "draining") and runtime_status_is_stale(state):
         if not runtime_status_pid_is_live(state):
             lines.append(
                 f"⚠ Stale gateway_state.json: recorded state '{gateway_state}' but the "
diff --git a/hermes_cli/gateway_windows.py b/hermes_cli/gateway_windows.py
index e90b4cb981..56eae9a9fd 100644
--- a/hermes_cli/gateway_windows.py
+++ b/hermes_cli/gateway_windows.py
@@ -1407,7 +1407,7 @@ def _probe_state_file(state_path: Path) -> None:
                 age_str = f" (updated {age_seconds}s ago)"
             except Exception:
                 pass
-        _probe(5, gateway_state == "running", f"gateway_state.json state={gateway_state!r}{age_str}")
+        _probe(5, gateway_state in ("running", "degraded"), f"gateway_state.json state={gateway_state!r}{age_str}")
     except Exception as exc:
         _probe(5, False, f"gateway_state.json present but unreadable: {exc}")
 
diff --git a/hermes_cli/web_routers/status.py b/hermes_cli/web_routers/status.py
index c41a9f1c89..86994a6f7c 100644
--- a/hermes_cli/web_routers/status.py
+++ b/hermes_cli/web_routers/status.py
@@ -306,7 +306,7 @@ async def _resolve_gateway_status(profile_dir: Optional[Path], health_url) -> Di
             # The health probe confirmed the gateway is alive, but the local runtime status
             # file may be stale (cross-container): override so the badge is correct.
             gateway_state = "running"
-        elif gateway_state in {"running", "starting"} and runtime_status_is_stale(runtime):
+        elif gateway_state in {"running", "degraded", "starting"} and runtime_status_is_stale(runtime):
             # Alive PID, but housekeeping stopped re-stamping the heartbeat: the loop or the
             # housekeeping thread wedged while the file still says 'running' (#113372). Same arm
             # as ``hermes gateway status`` so the sidebar strip and the CLI agree.
diff --git a/tests/gateway/test_status.py b/tests/gateway/test_status.py
index a25890fe58..c5438e2b6b 100644
--- a/tests/gateway/test_status.py
+++ b/tests/gateway/test_status.py
@@ -1224,6 +1224,15 @@ class TestGatewayBusyDerivation:
             gateway_running=True, gateway_state="running", active_agents=0
         ) is False
 
+    def test_degraded_gateway_with_work_is_busy_and_drainable(self):
+        # Serving with a parked platform (#91547): in-flight turns must not look idle to NAS.
+        assert status.derive_gateway_busy(
+            gateway_running=True, gateway_state="degraded", active_agents=2
+        ) is True
+        assert status.derive_gateway_drainable(
+            gateway_running=False, gateway_state="degraded"
+        ) is False
+
 
 class TestRespawnStormBreaker:
     def test_no_storm_under_threshold(self, tmp_path, monkeypatch):

From 4405813281d64e1dbff897e3d88ee554e48a9672 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 01:52:11 +0530
Subject: [PATCH 098/190] test(gateway): the NS-609 mixed boot is degraded, not
 running

CI: `test_token_lock_plus_retryable_peer_stays_alive` pinned `running` for a
boot whose Telegram adapter is parked fatal while Discord retries. That is a
serving gateway with a parked platform, which this stack stamps `degraded`
for its whole life; the assertion was the stale half of the contract.

All 67 test files that touch gateway_state / the status derivations: green.
---
 tests/gateway/test_runner_startup_failures.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/tests/gateway/test_runner_startup_failures.py b/tests/gateway/test_runner_startup_failures.py
index c3f906f171..8b94df1a42 100644
--- a/tests/gateway/test_runner_startup_failures.py
+++ b/tests/gateway/test_runner_startup_failures.py
@@ -570,7 +570,8 @@ async def test_token_lock_plus_retryable_peer_stays_alive(monkeypatch, tmp_path)
         assert runner.exit_code is None
         assert set(runner._failed_platforms) == {Platform.DISCORD}
         state = read_runtime_status()
-        assert state["gateway_state"] == "running"
+        # Alive, but Telegram is parked fatal: a serving-with-a-parked-platform boot is degraded.
+        assert state["gateway_state"] == "degraded"
         assert state["platforms"]["telegram"]["state"] == "fatal"
         assert state["platforms"]["discord"]["state"] == "retrying"
     finally:

From ef7c7f9e082f41dc81208dea3f83ddbf6746ebb2 Mon Sep 17 00:00:00 2001
From: KoNit-K <konit.block@protonmail.com>
Date: Thu, 10 Sep 2026 04:54:11 +0800
Subject: [PATCH 099/190] fix(compression): warn and remediate opaque
 checkpoint_required blocks

When compression.checkpoint_required is set but the active memory provider
lacks checkpoint API v2, keep fail-closed compress and surface a startup
warning plus actionable remediation on the block error.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 agent/agent_init.py                           |   2 +
 agent/conversation_compression.py             |  57 ++++++-
 .../test_pre_compress_checkpoint_contract.py  | 144 ++++++++++++++++++
 3 files changed, 202 insertions(+), 1 deletion(-)

diff --git a/agent/agent_init.py b/agent/agent_init.py
index cf2b06d460..7fa654fb07 100644
--- a/agent/agent_init.py
+++ b/agent/agent_init.py
@@ -1894,6 +1894,8 @@ def _build_context_engine(agent, _agent_cfg, cs, _custom_providers, _effective_c
         if hasattr(_cc, _attr):
             setattr(_cc, _attr, _value)
     agent.compression_checkpoint_required = cs.checkpoint_required
+    from agent.conversation_compression import _warn_checkpoint_required_without_capable_provider
+    _warn_checkpoint_required_without_capable_provider(agent)
     agent.codex_app_server_auto_compaction = cs.codex_app_server_auto
     agent.codex_responses_native_compaction = cs.codex_responses_native
     agent.codex_responses_compact_threshold = cs.codex_responses_compact_threshold
diff --git a/agent/conversation_compression.py b/agent/conversation_compression.py
index 54946df3ed..e247058185 100644
--- a/agent/conversation_compression.py
+++ b/agent/conversation_compression.py
@@ -1253,9 +1253,64 @@ class CompressionCheckpointUnavailable(RuntimeError):
     """Raised when required durable pre-compress checkpointing is unavailable."""
 
 
+# Shared by the startup warning and compress-time block so operators see the
+# same recovery path: disable the fail-closed flag, or switch providers.
+_CHECKPOINT_REQUIRED_REMEDIATION = (
+    "set compression.checkpoint_required: false, or switch to a memory "
+    "provider that implements checkpoint API v2"
+)
+
+
+def _active_memory_provider_label(agent: Any) -> str:
+    """Human-readable active provider name, or an explicit none sentinel."""
+    memory_manager = getattr(agent, "_memory_manager", None)
+    if memory_manager is None:
+        return "no active provider"
+    providers = getattr(memory_manager, "providers", None)
+    names: list[str] = []
+    if providers is not None:
+        try:
+            iterable = list(providers)
+        except TypeError:
+            iterable = []
+        for provider in iterable:
+            name = getattr(provider, "name", None)
+            if isinstance(name, str) and name.strip():
+                names.append(name.strip())
+    return ", ".join(names) if names else "no active provider"
+
+
 def _checkpoint_blocked(reason: str) -> CompressionCheckpointUnavailable:
     return CompressionCheckpointUnavailable(
-        f"BLOCKED_MISSING_PREREQUISITE: required pre-compress checkpoint unavailable: {reason}"
+        f"BLOCKED_MISSING_PREREQUISITE: required pre-compress checkpoint unavailable: {reason}. "
+        f"Recover by {_CHECKPOINT_REQUIRED_REMEDIATION}."
+    )
+
+
+def _warn_checkpoint_required_without_capable_provider(agent: Any) -> None:
+    """Startup warning when fail-closed compress will block (init itself must not refuse).
+
+    Capability-probe exceptions are suppressed so a broken provider cannot crash
+    agent construction — same fail-open style as the micro-compact warning.
+    """
+    if getattr(agent, "compression_checkpoint_required", False) is not True:
+        return
+    memory_manager = getattr(agent, "_memory_manager", None)
+    if memory_manager is not None:
+        supports_checkpoint = getattr(memory_manager, "supports_pre_compress_checkpoint", None)
+        if callable(supports_checkpoint):
+            try:
+                if bool(supports_checkpoint(PRE_COMPRESS_CHECKPOINT_API_VERSION)):
+                    return
+            except Exception:
+                return
+    logger.warning(
+        "compression.checkpoint_required is enabled but the active memory "
+        "provider (%s) does not implement checkpoint API v%s. Compress will "
+        "fail closed. Recover by %s.",
+        _active_memory_provider_label(agent),
+        PRE_COMPRESS_CHECKPOINT_API_VERSION,
+        _CHECKPOINT_REQUIRED_REMEDIATION,
     )
 
 
diff --git a/tests/agent/test_pre_compress_checkpoint_contract.py b/tests/agent/test_pre_compress_checkpoint_contract.py
index b54c0caef2..70252a9452 100644
--- a/tests/agent/test_pre_compress_checkpoint_contract.py
+++ b/tests/agent/test_pre_compress_checkpoint_contract.py
@@ -556,3 +556,147 @@ def test_agent_init_suppresses_micro_compaction_under_checkpoint_gate():
     )
     assert assign_idx != -1
     assert suppress_idx < assign_idx
+
+
+def _warn_text(caplog) -> str:
+    return "\n".join(r.getMessage() for r in caplog.records)
+
+
+def test_startup_warns_when_checkpoint_required_and_legacy_provider(caplog):
+    """Fail-closed compress is correct, but operators need a startup hint.
+
+    holographic-style v1 providers do not implement checkpoint API v2; with
+    ``compression.checkpoint_required`` armed, init must warn with the config
+    key, the active provider name, and how to recover.
+    """
+    import logging
+    from types import SimpleNamespace
+
+    from agent.conversation_compression import (
+        _warn_checkpoint_required_without_capable_provider,
+    )
+
+    manager = MemoryManager()
+    manager.add_provider(_BaseStubProvider("holographic"))
+    agent = SimpleNamespace(
+        compression_checkpoint_required=True,
+        _memory_manager=manager,
+    )
+
+    with caplog.at_level(logging.WARNING, logger="agent.conversation_compression"):
+        _warn_checkpoint_required_without_capable_provider(agent)
+
+    text = _warn_text(caplog)
+    assert "compression.checkpoint_required" in text
+    assert "holographic" in text
+    assert "false" in text.lower()
+
+
+def test_pre_compress_blocked_error_includes_checkpoint_required_remediation():
+    """Compress-time block must name the flag, not just the missing API."""
+    from types import SimpleNamespace
+
+    from agent.conversation_compression import _pre_compress_memory_context
+
+    manager = MemoryManager()
+    manager.add_provider(_BaseStubProvider("legacy"))
+    agent = SimpleNamespace(_memory_manager=manager)
+
+    with pytest.raises(CompressionCheckpointUnavailable) as excinfo:
+        _pre_compress_memory_context(
+            agent, [{"role": "user", "content": "evidence"}], True
+        )
+
+    msg = str(excinfo.value)
+    assert "BLOCKED_MISSING_PREREQUISITE" in msg
+    assert "compression.checkpoint_required" in msg
+
+
+def test_startup_does_not_warn_when_provider_is_checkpoint_capable(caplog):
+    import logging
+    from types import SimpleNamespace
+
+    from agent.conversation_compression import (
+        _warn_checkpoint_required_without_capable_provider,
+    )
+
+    manager = MemoryManager()
+    manager.add_provider(_CheckpointProvider("durable"))
+    agent = SimpleNamespace(
+        compression_checkpoint_required=True,
+        _memory_manager=manager,
+    )
+
+    with caplog.at_level(logging.WARNING, logger="agent.conversation_compression"):
+        _warn_checkpoint_required_without_capable_provider(agent)
+
+    assert "compression.checkpoint_required" not in _warn_text(caplog)
+
+
+def test_startup_does_not_warn_when_checkpoint_required_is_false(caplog):
+    import logging
+    from types import SimpleNamespace
+
+    from agent.conversation_compression import (
+        _warn_checkpoint_required_without_capable_provider,
+    )
+
+    manager = MemoryManager()
+    manager.add_provider(_BaseStubProvider("holographic"))
+    agent = SimpleNamespace(
+        compression_checkpoint_required=False,
+        _memory_manager=manager,
+    )
+
+    with caplog.at_level(logging.WARNING, logger="agent.conversation_compression"):
+        _warn_checkpoint_required_without_capable_provider(agent)
+
+    assert "compression.checkpoint_required" not in _warn_text(caplog)
+
+
+def test_startup_warns_when_checkpoint_required_and_no_memory_manager(caplog):
+    """skip_memory leaves no manager; compress still blocks, so init must warn."""
+    import logging
+    from types import SimpleNamespace
+
+    from agent.conversation_compression import (
+        _warn_checkpoint_required_without_capable_provider,
+    )
+
+    agent = SimpleNamespace(
+        compression_checkpoint_required=True,
+        _memory_manager=None,
+    )
+
+    with caplog.at_level(logging.WARNING, logger="agent.conversation_compression"):
+        _warn_checkpoint_required_without_capable_provider(agent)
+
+    text = _warn_text(caplog)
+    assert "compression.checkpoint_required" in text
+    assert "no active provider" in text.lower() or "none" in text.lower()
+
+
+def test_startup_probe_exception_fails_open_without_crash_or_warning(caplog):
+    """A broken capability probe must not refuse init (micro_compact-style)."""
+    import logging
+    from types import SimpleNamespace
+
+    from agent.conversation_compression import (
+        _warn_checkpoint_required_without_capable_provider,
+    )
+
+    class _ExplodingManager:
+        providers = []
+
+        def supports_pre_compress_checkpoint(self, api_version):
+            raise RuntimeError("probe exploded")
+
+    agent = SimpleNamespace(
+        compression_checkpoint_required=True,
+        _memory_manager=_ExplodingManager(),
+    )
+
+    with caplog.at_level(logging.WARNING, logger="agent.conversation_compression"):
+        _warn_checkpoint_required_without_capable_provider(agent)
+
+    assert "compression.checkpoint_required" not in _warn_text(caplog)

From 8e7120e2fd075c14267c101d2fb84a702a3752ce Mon Sep 17 00:00:00 2001
From: KoNit-K <konit.block@protonmail.com>
Date: Thu, 10 Sep 2026 18:08:14 +0800
Subject: [PATCH 100/190] fix(compression): debug-log checkpoint capability
 probe failures

Keep init fail-open on a broken probe, but emit DEBUG so flaky probes are diagnosable.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 agent/conversation_compression.py                    |  9 ++++++++-
 tests/agent/test_pre_compress_checkpoint_contract.py | 12 ++++++++++--
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/agent/conversation_compression.py b/agent/conversation_compression.py
index e247058185..614ab7c1b0 100644
--- a/agent/conversation_compression.py
+++ b/agent/conversation_compression.py
@@ -1292,6 +1292,8 @@ def _warn_checkpoint_required_without_capable_provider(agent: Any) -> None:
 
     Capability-probe exceptions are suppressed so a broken provider cannot crash
     agent construction — same fail-open style as the micro-compact warning.
+    Probe failures log at DEBUG so a flaky probe can be diagnosed without
+    refusing init or emitting the incapable-provider WARNING.
     """
     if getattr(agent, "compression_checkpoint_required", False) is not True:
         return
@@ -1302,7 +1304,12 @@ def _warn_checkpoint_required_without_capable_provider(agent: Any) -> None:
             try:
                 if bool(supports_checkpoint(PRE_COMPRESS_CHECKPOINT_API_VERSION)):
                     return
-            except Exception:
+            except Exception as exc:
+                logger.debug(
+                    "checkpoint-required capability probe failed; init continues: %s",
+                    exc,
+                    exc_info=True,
+                )
                 return
     logger.warning(
         "compression.checkpoint_required is enabled but the active memory "
diff --git a/tests/agent/test_pre_compress_checkpoint_contract.py b/tests/agent/test_pre_compress_checkpoint_contract.py
index 70252a9452..d47ad68cef 100644
--- a/tests/agent/test_pre_compress_checkpoint_contract.py
+++ b/tests/agent/test_pre_compress_checkpoint_contract.py
@@ -696,7 +696,15 @@ def test_startup_probe_exception_fails_open_without_crash_or_warning(caplog):
         _memory_manager=_ExplodingManager(),
     )
 
-    with caplog.at_level(logging.WARNING, logger="agent.conversation_compression"):
+    with caplog.at_level(logging.DEBUG, logger="agent.conversation_compression"):
         _warn_checkpoint_required_without_capable_provider(agent)
 
-    assert "compression.checkpoint_required" not in _warn_text(caplog)
+    warnings = "\n".join(
+        r.getMessage() for r in caplog.records if r.levelno >= logging.WARNING
+    )
+    debugs = "\n".join(
+        r.getMessage() for r in caplog.records if r.levelno == logging.DEBUG
+    )
+    assert "compression.checkpoint_required" not in warnings
+    assert "probe exploded" in debugs
+    assert "capability probe failed" in debugs

From ece262150a3f35a270e1e5b63ebbe4b88e27a2dd Mon Sep 17 00:00:00 2001
From: Konstantin Khlopkov <konstantin.khlopkov93@gmail.com>
Date: Fri, 18 Sep 2026 13:34:41 -0700
Subject: [PATCH 101/190] docs(memory-provider): state that no bundled provider
 advertises checkpoint API v2

Operators enabling compression.checkpoint_required need to know up front that
the contract is opt-in for third-party archiving providers; otherwise the flag
blocks every compression attempt and the reason is only visible after the fact.

Docs hunk of #106882 (the code change was consolidated with #106879).
---
 website/docs/developer-guide/memory-provider-plugin.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/website/docs/developer-guide/memory-provider-plugin.md b/website/docs/developer-guide/memory-provider-plugin.md
index df51517307..7b4610406e 100644
--- a/website/docs/developer-guide/memory-provider-plugin.md
+++ b/website/docs/developer-guide/memory-provider-plugin.md
@@ -212,6 +212,12 @@ uncompressed transcript is preserved, the compaction attempt errors with
 `BLOCKED_MISSING_PREREQUISITE`, and it can be retried once your store
 recovers. With the gate off (default), nothing changes for existing providers.
 
+None of the providers bundled with Hermes advertise checkpoint API v2 — the
+contract is opt-in and exists for third-party archiving providers. Enabling
+`checkpoint_required` without one therefore blocks every compression attempt
+(manual and automatic): agent init logs a warning naming the active provider,
+and each refusal names `compression.checkpoint_required` as the key to disable.
+
 The gate binds to every compaction authority, not just the Hermes
 summarizer: server-side native compaction (`compression.codex_responses_native`)
 is suppressed while the gate is armed, post-turn micro-compaction

From 96030a353662860b16ecad447d88e3cafe672a13 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 13:36:57 -0700
Subject: [PATCH 102/190] fix(compression): scope the checkpoint remediation to
 capability refusals; trim tests

The remediation ("set compression.checkpoint_required: false, or switch
provider") is right only when the gate can never pass with the active provider
set. Attached to every _checkpoint_blocked() it also decorated the transient
"provider checkpoint API v2 failed" path, where the provider IS capable and the
correct move is a retry once the store recovers, and the codex_app_server
refusal, where switching memory provider changes nothing. A small
_checkpoint_incapable() wrapper carries it on the two capability branches only.

Tests: six near-duplicates collapse into three invariants (warn on mismatch,
parametrized over v1 provider / no manager; silent when off or capable; the
compress-time refusal names the flag). Proven red with the fix neutralized.

Consolidates #106879 (KoNit-K) and #106882 (kokhlo); fixes #106870.
---
 agent/conversation_compression.py             |  14 +-
 .../test_pre_compress_checkpoint_contract.py  | 162 ++++--------------
 2 files changed, 46 insertions(+), 130 deletions(-)

diff --git a/agent/conversation_compression.py b/agent/conversation_compression.py
index 614ab7c1b0..f282354b35 100644
--- a/agent/conversation_compression.py
+++ b/agent/conversation_compression.py
@@ -1282,11 +1282,17 @@ def _active_memory_provider_label(agent: Any) -> str:
 
 def _checkpoint_blocked(reason: str) -> CompressionCheckpointUnavailable:
     return CompressionCheckpointUnavailable(
-        f"BLOCKED_MISSING_PREREQUISITE: required pre-compress checkpoint unavailable: {reason}. "
-        f"Recover by {_CHECKPOINT_REQUIRED_REMEDIATION}."
+        f"BLOCKED_MISSING_PREREQUISITE: required pre-compress checkpoint unavailable: {reason}"
     )
 
 
+def _checkpoint_incapable(reason: str) -> CompressionCheckpointUnavailable:
+    """Capability refusal: the gate can never pass with this provider set, so the
+    message carries the config-level way out. Transient checkpoint failures keep
+    the plain form — there the provider is capable and the right move is a retry."""
+    return _checkpoint_blocked(f"{reason}. Recover by {_CHECKPOINT_REQUIRED_REMEDIATION}")
+
+
 def _warn_checkpoint_required_without_capable_provider(agent: Any) -> None:
     """Startup warning when fail-closed compress will block (init itself must not refuse).
 
@@ -2847,7 +2853,7 @@ def _pre_compress_memory_context(agent: Any, messages: list, checkpoint_required
     if checkpoint_required:
         supports_checkpoint = getattr(memory_manager, "supports_pre_compress_checkpoint", None)
         if memory_manager is None or not callable(supports_checkpoint):
-            raise _checkpoint_blocked(
+            raise _checkpoint_incapable(
                 f"no active provider implements checkpoint API v{PRE_COMPRESS_CHECKPOINT_API_VERSION}"
             )
         try:
@@ -2855,7 +2861,7 @@ def _pre_compress_memory_context(agent: Any, messages: list, checkpoint_required
         except Exception as exc:
             raise _checkpoint_blocked("provider capability probe failed") from exc
         if not compatible:
-            raise _checkpoint_blocked(
+            raise _checkpoint_incapable(
                 f"active provider does not implement checkpoint API v{PRE_COMPRESS_CHECKPOINT_API_VERSION}"
             )
         try:
diff --git a/tests/agent/test_pre_compress_checkpoint_contract.py b/tests/agent/test_pre_compress_checkpoint_contract.py
index d47ad68cef..7fa9e756bf 100644
--- a/tests/agent/test_pre_compress_checkpoint_contract.py
+++ b/tests/agent/test_pre_compress_checkpoint_contract.py
@@ -9,12 +9,17 @@ The contract has three parts:
   before handing them to v2+ providers.
 """
 
+import logging
+from types import SimpleNamespace
+
 import pytest
 
 from agent.conversation_compression import (
     CompressionCheckpointUnavailable,
     _checkpoint_blocked,
     _direct_messages_for_pre_compress_memory,
+    _pre_compress_memory_context,
+    _warn_checkpoint_required_without_capable_provider,
 )
 from agent.context_compressor import COMPRESSED_SUMMARY_METADATA_KEY
 from agent.memory_manager import MemoryManager
@@ -559,152 +564,57 @@ def test_agent_init_suppresses_micro_compaction_under_checkpoint_gate():
 
 
 def _warn_text(caplog) -> str:
-    return "\n".join(r.getMessage() for r in caplog.records)
+    return "\n".join(r.getMessage() for r in caplog.records if r.levelno >= logging.WARNING)
 
 
-def test_startup_warns_when_checkpoint_required_and_legacy_provider(caplog):
-    """Fail-closed compress is correct, but operators need a startup hint.
+def _armed_agent(manager):
+    return SimpleNamespace(compression_checkpoint_required=True, _memory_manager=manager)
 
-    holographic-style v1 providers do not implement checkpoint API v2; with
-    ``compression.checkpoint_required`` armed, init must warn with the config
-    key, the active provider name, and how to recover.
-    """
-    import logging
-    from types import SimpleNamespace
-
-    from agent.conversation_compression import (
-        _warn_checkpoint_required_without_capable_provider,
-    )
 
+def _legacy_manager():
     manager = MemoryManager()
     manager.add_provider(_BaseStubProvider("holographic"))
-    agent = SimpleNamespace(
-        compression_checkpoint_required=True,
-        _memory_manager=manager,
-    )
+    return manager
 
+
+@pytest.mark.parametrize(
+    "manager, expected_label",
+    [(_legacy_manager(), "holographic"), (None, "no active provider")],
+    ids=["v1-provider", "no-manager"],
+)
+def test_startup_warns_when_checkpoint_required_cannot_pass(caplog, manager, expected_label):
+    """Regression for #106870: the fail-closed gate is right, but with the flag armed and
+    no checkpoint-capable provider every compression will block, and that is knowable at
+    init. The warning must name the config key, the active provider and the way out."""
     with caplog.at_level(logging.WARNING, logger="agent.conversation_compression"):
-        _warn_checkpoint_required_without_capable_provider(agent)
+        _warn_checkpoint_required_without_capable_provider(_armed_agent(manager))
 
     text = _warn_text(caplog)
     assert "compression.checkpoint_required" in text
-    assert "holographic" in text
+    assert expected_label in text
     assert "false" in text.lower()
 
 
-def test_pre_compress_blocked_error_includes_checkpoint_required_remediation():
-    """Compress-time block must name the flag, not just the missing API."""
-    from types import SimpleNamespace
+def test_startup_is_silent_when_gate_off_or_provider_capable(caplog):
+    capable = MemoryManager()
+    capable.add_provider(_CheckpointProvider("archiver"))
+    off = SimpleNamespace(compression_checkpoint_required=False, _memory_manager=_legacy_manager())
 
-    from agent.conversation_compression import _pre_compress_memory_context
+    with caplog.at_level(logging.WARNING, logger="agent.conversation_compression"):
+        _warn_checkpoint_required_without_capable_provider(_armed_agent(capable))
+        _warn_checkpoint_required_without_capable_provider(off)
 
-    manager = MemoryManager()
-    manager.add_provider(_BaseStubProvider("legacy"))
-    agent = SimpleNamespace(_memory_manager=manager)
+    assert "compression.checkpoint_required" not in _warn_text(caplog)
 
+
+def test_capability_refusal_names_the_config_key_to_change():
+    """The compress-time block must point at the flag that armed it, not only the missing API."""
     with pytest.raises(CompressionCheckpointUnavailable) as excinfo:
         _pre_compress_memory_context(
-            agent, [{"role": "user", "content": "evidence"}], True
+            SimpleNamespace(_memory_manager=_legacy_manager()), [{"role": "user", "content": "evidence"}], True
         )
 
     msg = str(excinfo.value)
-    assert "BLOCKED_MISSING_PREREQUISITE" in msg
+    assert msg.startswith("BLOCKED_MISSING_PREREQUISITE")
     assert "compression.checkpoint_required" in msg
-
-
-def test_startup_does_not_warn_when_provider_is_checkpoint_capable(caplog):
-    import logging
-    from types import SimpleNamespace
-
-    from agent.conversation_compression import (
-        _warn_checkpoint_required_without_capable_provider,
-    )
-
-    manager = MemoryManager()
-    manager.add_provider(_CheckpointProvider("durable"))
-    agent = SimpleNamespace(
-        compression_checkpoint_required=True,
-        _memory_manager=manager,
-    )
-
-    with caplog.at_level(logging.WARNING, logger="agent.conversation_compression"):
-        _warn_checkpoint_required_without_capable_provider(agent)
-
-    assert "compression.checkpoint_required" not in _warn_text(caplog)
-
-
-def test_startup_does_not_warn_when_checkpoint_required_is_false(caplog):
-    import logging
-    from types import SimpleNamespace
-
-    from agent.conversation_compression import (
-        _warn_checkpoint_required_without_capable_provider,
-    )
-
-    manager = MemoryManager()
-    manager.add_provider(_BaseStubProvider("holographic"))
-    agent = SimpleNamespace(
-        compression_checkpoint_required=False,
-        _memory_manager=manager,
-    )
-
-    with caplog.at_level(logging.WARNING, logger="agent.conversation_compression"):
-        _warn_checkpoint_required_without_capable_provider(agent)
-
-    assert "compression.checkpoint_required" not in _warn_text(caplog)
-
-
-def test_startup_warns_when_checkpoint_required_and_no_memory_manager(caplog):
-    """skip_memory leaves no manager; compress still blocks, so init must warn."""
-    import logging
-    from types import SimpleNamespace
-
-    from agent.conversation_compression import (
-        _warn_checkpoint_required_without_capable_provider,
-    )
-
-    agent = SimpleNamespace(
-        compression_checkpoint_required=True,
-        _memory_manager=None,
-    )
-
-    with caplog.at_level(logging.WARNING, logger="agent.conversation_compression"):
-        _warn_checkpoint_required_without_capable_provider(agent)
-
-    text = _warn_text(caplog)
-    assert "compression.checkpoint_required" in text
-    assert "no active provider" in text.lower() or "none" in text.lower()
-
-
-def test_startup_probe_exception_fails_open_without_crash_or_warning(caplog):
-    """A broken capability probe must not refuse init (micro_compact-style)."""
-    import logging
-    from types import SimpleNamespace
-
-    from agent.conversation_compression import (
-        _warn_checkpoint_required_without_capable_provider,
-    )
-
-    class _ExplodingManager:
-        providers = []
-
-        def supports_pre_compress_checkpoint(self, api_version):
-            raise RuntimeError("probe exploded")
-
-    agent = SimpleNamespace(
-        compression_checkpoint_required=True,
-        _memory_manager=_ExplodingManager(),
-    )
-
-    with caplog.at_level(logging.DEBUG, logger="agent.conversation_compression"):
-        _warn_checkpoint_required_without_capable_provider(agent)
-
-    warnings = "\n".join(
-        r.getMessage() for r in caplog.records if r.levelno >= logging.WARNING
-    )
-    debugs = "\n".join(
-        r.getMessage() for r in caplog.records if r.levelno == logging.DEBUG
-    )
-    assert "compression.checkpoint_required" not in warnings
-    assert "probe exploded" in debugs
-    assert "capability probe failed" in debugs
+    assert "false" in msg.lower()

From 0d4339145db1b7c139bb6fe889d5b3fafd40fe77 Mon Sep 17 00:00:00 2001
From: ourines <ourines@icloud.com>
Date: Fri, 18 Sep 2026 16:45:49 +0800
Subject: [PATCH 103/190] feat(plugin-catalog): add explicit Jev decision
 sidekick

---
 plugin-catalog/jev.yaml | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)
 create mode 100644 plugin-catalog/jev.yaml

diff --git a/plugin-catalog/jev.yaml b/plugin-catalog/jev.yaml
new file mode 100644
index 0000000000..10f0141186
--- /dev/null
+++ b/plugin-catalog/jev.yaml
@@ -0,0 +1,20 @@
+name: jev
+repo: https://github.com/ourines/hermes-jev
+sha: 591bf074158ecc85c992b5ed76f7eda0592a6d9a
+subdir: ""
+description: "Explicit Jev decision sidekick via TypeSafe or Cloudflare; advisory judgments, no automatic tool gating."
+maintainer: ourines
+tier: community
+category: tools
+requires_hermes: ">=0.21.3"
+docs_url: https://github.com/ourines/hermes-jev/blob/591bf074158ecc85c992b5ed76f7eda0592a6d9a/README.md
+version: "0.1.2"
+platforms: []
+capabilities:
+  provides_tools:
+    - jev_evaluate
+  provides_hooks: []
+  provides_middleware: []
+  # Credentials are alternatives, selected per backend during interactive setup.
+  # Offline guide/status/presets and plugin registration require neither key.
+  requires_env: []

From 88b4e83e0c02da3a8ce5f1a8d06ed4c2aed1399b Mon Sep 17 00:00:00 2001
From: ourines <ourines@icloud.com>
Date: Fri, 18 Sep 2026 16:48:40 +0800
Subject: [PATCH 104/190] chore(plugin-catalog): pin final Jev v0.1.2 release

---
 plugin-catalog/jev.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/plugin-catalog/jev.yaml b/plugin-catalog/jev.yaml
index 10f0141186..8e6b2872e8 100644
--- a/plugin-catalog/jev.yaml
+++ b/plugin-catalog/jev.yaml
@@ -1,13 +1,13 @@
 name: jev
 repo: https://github.com/ourines/hermes-jev
-sha: 591bf074158ecc85c992b5ed76f7eda0592a6d9a
+sha: 28a4ea390f80d97fcdc8c20d6b630dfe2de645de
 subdir: ""
 description: "Explicit Jev decision sidekick via TypeSafe or Cloudflare; advisory judgments, no automatic tool gating."
 maintainer: ourines
 tier: community
 category: tools
 requires_hermes: ">=0.21.3"
-docs_url: https://github.com/ourines/hermes-jev/blob/591bf074158ecc85c992b5ed76f7eda0592a6d9a/README.md
+docs_url: https://github.com/ourines/hermes-jev/blob/28a4ea390f80d97fcdc8c20d6b630dfe2de645de/README.md
 version: "0.1.2"
 platforms: []
 capabilities:

From e9d00156f91bf92cf6f864a4f97331edbd11f16e Mon Sep 17 00:00:00 2001
From: teknium <teknium@nousresearch.com>
Date: Fri, 18 Sep 2026 14:08:00 -0700
Subject: [PATCH 105/190] chore: map contributor email for @ourines

So check-attribution passes on the catalog PR.
---
 contributors/emails/ourines@icloud.com | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 contributors/emails/ourines@icloud.com

diff --git a/contributors/emails/ourines@icloud.com b/contributors/emails/ourines@icloud.com
new file mode 100644
index 0000000000..a96d637c7a
--- /dev/null
+++ b/contributors/emails/ourines@icloud.com
@@ -0,0 +1 @@
+ourines

From daefa066fdaa6cc2958aa773e4355f757650583d Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 14:08:21 -0700
Subject: [PATCH 106/190] chore: map contributor emails for org-fork catalog
 PRs

prismhq, youdotcom-oss, superagents-lab and JetBrains forks deny maintainer
pushes, so check-attribution for #112375 #113715 #113739 #114202 needs the
mapping on main.
---
 contributors/emails/devin@cognition.ai     | 1 +
 contributors/emails/edward@you.com         | 1 +
 contributors/emails/junie@jetbrains.com    | 1 +
 contributors/emails/rajitskhanna@gmail.com | 1 +
 4 files changed, 4 insertions(+)
 create mode 100644 contributors/emails/devin@cognition.ai
 create mode 100644 contributors/emails/edward@you.com
 create mode 100644 contributors/emails/junie@jetbrains.com
 create mode 100644 contributors/emails/rajitskhanna@gmail.com

diff --git a/contributors/emails/devin@cognition.ai b/contributors/emails/devin@cognition.ai
new file mode 100644
index 0000000000..ac4308b104
--- /dev/null
+++ b/contributors/emails/devin@cognition.ai
@@ -0,0 +1 @@
+fatwang2
diff --git a/contributors/emails/edward@you.com b/contributors/emails/edward@you.com
new file mode 100644
index 0000000000..a4d860da4c
--- /dev/null
+++ b/contributors/emails/edward@you.com
@@ -0,0 +1 @@
+EdwardIrby
diff --git a/contributors/emails/junie@jetbrains.com b/contributors/emails/junie@jetbrains.com
new file mode 100644
index 0000000000..c43d95f252
--- /dev/null
+++ b/contributors/emails/junie@jetbrains.com
@@ -0,0 +1 @@
+AlexanderPrendota
diff --git a/contributors/emails/rajitskhanna@gmail.com b/contributors/emails/rajitskhanna@gmail.com
new file mode 100644
index 0000000000..0471d674e8
--- /dev/null
+++ b/contributors/emails/rajitskhanna@gmail.com
@@ -0,0 +1 @@
+rajitkhanna

From 6b219b56fe1323f822a35ebb10cb115647264008 Mon Sep 17 00:00:00 2001
From: souf <sofianekal95@gmail.com>
Date: Thu, 17 Sep 2026 21:21:55 +0200
Subject: [PATCH 107/190] feat(catalog): add hermes-town community plugin

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: souf <sofianekal95@gmail.com>
---
 plugin-catalog/hermes-town.yaml | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)
 create mode 100644 plugin-catalog/hermes-town.yaml

diff --git a/plugin-catalog/hermes-town.yaml b/plugin-catalog/hermes-town.yaml
new file mode 100644
index 0000000000..a0b9f723f2
--- /dev/null
+++ b/plugin-catalog/hermes-town.yaml
@@ -0,0 +1,27 @@
+name: hermes-town
+repo: https://github.com/sxuff/hermes-town
+sha: 83aae757264b8cbae541830ba91834eed067c31a
+subdir: integrations/hermes-town-plugin
+description: Local pixel-art town where every Hermes session is a resident and every tool call walks to a building. Passive lifecycle bridge to a loopback-only server; prompts, arguments, and output never leave the process.
+maintainer: sxuff
+tier: community
+category: tools
+requires_hermes: ">=0.21"
+docs_url: https://github.com/sxuff/hermes-town#readme
+version: "0.2.0"
+image: https://raw.githubusercontent.com/sxuff/hermes-town/83aae757264b8cbae541830ba91834eed067c31a/artifacts/catalog-banner.png
+capabilities:
+  provides_tools: []
+  provides_hooks:
+    - pre_llm_call
+    - post_llm_call
+    - pre_tool_call
+    - post_tool_call
+    - on_session_start
+    - on_session_end
+    - on_session_finalize
+    - on_session_reset
+    - subagent_start
+    - subagent_stop
+  provides_middleware: []
+  requires_env: []

From 21e44431cc96f25ee3be81e77011b815192c3db4 Mon Sep 17 00:00:00 2001
From: teknium <teknium@nousresearch.com>
Date: Fri, 18 Sep 2026 14:07:31 -0700
Subject: [PATCH 108/190] chore: map contributor email for @sxuff

So check-attribution passes on the catalog PR.
---
 contributors/emails/sofianekal95@gmail.com | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 contributors/emails/sofianekal95@gmail.com

diff --git a/contributors/emails/sofianekal95@gmail.com b/contributors/emails/sofianekal95@gmail.com
new file mode 100644
index 0000000000..2878ded52f
--- /dev/null
+++ b/contributors/emails/sofianekal95@gmail.com
@@ -0,0 +1 @@
+sxuff

From 4594092006f5031faafb819eca193f389f604112 Mon Sep 17 00:00:00 2001
From: Alexander Prendota <alexander.prendota@gmail.com>
Date: Thu, 17 Sep 2026 16:48:25 +0200
Subject: [PATCH 109/190] =?UTF-8?q?feat(plugin-catalog):=20add=20junie-acp?=
 =?UTF-8?q?=20=E2=80=94=20JetBrains=20Junie=20as=20an=20ACP=20model=20prov?=
 =?UTF-8?q?ider?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Junie driven over the Agent Client Protocol, shipped from the JetBrains/junie
repository as an out-of-tree model provider against the registration seam that
landed in #95679 and #101456.

Pinned at 296ea839b354956fbd22544687a88b944c18dc22, subdir hermes-plugin.

capabilities are empty by design: a model-provider plugin registers a
ProviderProfile at import and no tools, hooks or middleware, which the pinned
tree's capability probe confirms. requires_env is empty because no variable is
required — the CLI authenticates by JetBrains account login, a JUNIE_API_KEY
token, or BYOK, and the plugin forwards the token only when it is set.

Co-Authored-By: Junie <junie@jetbrains.com>
---
 plugin-catalog/junie-acp.yaml | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)
 create mode 100644 plugin-catalog/junie-acp.yaml

diff --git a/plugin-catalog/junie-acp.yaml b/plugin-catalog/junie-acp.yaml
new file mode 100644
index 0000000000..1b499af5b3
--- /dev/null
+++ b/plugin-catalog/junie-acp.yaml
@@ -0,0 +1,16 @@
+name: junie-acp
+repo: https://github.com/JetBrains/junie
+sha: 296ea839b354956fbd22544687a88b944c18dc22
+subdir: hermes-plugin
+description: JetBrains Junie coding agent as a Hermes model provider over ACP.
+maintainer: JetBrains
+tier: community
+category: models
+requires_hermes: ">=0.21.1"
+docs_url: https://github.com/JetBrains/junie/tree/main/hermes-plugin
+platforms: []
+capabilities:
+  provides_tools: []
+  provides_hooks: []
+  provides_middleware: []
+  requires_env: []

From c5fba43c5317575eff7f2b34ef9002ed6a4e18e6 Mon Sep 17 00:00:00 2001
From: serply <googio@serply.io>
Date: Thu, 17 Sep 2026 10:44:12 -0400
Subject: [PATCH 110/190] feat(plugin-catalog): add web-serply

Serply web search provider, pinned at c6cab414. Registers a single
WebSearchProvider and reads SERPLY_API_KEY; no tools, hooks, or middleware.
Submitted as the owner of serply-inc/hermes-web-serply.
---
 plugin-catalog/web-serply.yaml | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)
 create mode 100644 plugin-catalog/web-serply.yaml

diff --git a/plugin-catalog/web-serply.yaml b/plugin-catalog/web-serply.yaml
new file mode 100644
index 0000000000..ab9c3c2181
--- /dev/null
+++ b/plugin-catalog/web-serply.yaml
@@ -0,0 +1,16 @@
+name: web-serply
+repo: https://github.com/serply-inc/hermes-web-serply
+sha: c6cab41471586a110e5a584061168a045f566e08
+description: Serply web search provider for Hermes Agent. Google web results via the Serply
+  SERP API. Requires SERPLY_API_KEY (sign up at https://serply.io).
+maintainer: serply-inc
+tier: community
+category: web
+docs_url: https://github.com/serply-inc/hermes-web-serply#readme
+version: "1.0.0"
+capabilities:
+  provides_tools: []
+  provides_hooks: []
+  provides_middleware: []
+  requires_env:
+  - SERPLY_API_KEY

From c1e9dce8b10d1e507ee9cb091e0bfafadc795200 Mon Sep 17 00:00:00 2001
From: teknium <teknium@nousresearch.com>
Date: Fri, 18 Sep 2026 14:07:16 -0700
Subject: [PATCH 111/190] chore: map contributor email for @googio

So check-attribution passes on the catalog PR.
---
 contributors/emails/googio@serply.io | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 contributors/emails/googio@serply.io

diff --git a/contributors/emails/googio@serply.io b/contributors/emails/googio@serply.io
new file mode 100644
index 0000000000..d6e2e9f1dd
--- /dev/null
+++ b/contributors/emails/googio@serply.io
@@ -0,0 +1 @@
+googio

From c0bdb65e8e278b3cc780650bc80269b6316a73e0 Mon Sep 17 00:00:00 2001
From: aydnOktay <xaydinoktay@gmail.com>
Date: Thu, 17 Sep 2026 17:31:19 +0300
Subject: [PATCH 112/190] feat(plugin-catalog): add debug-desk community plugin

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 plugin-catalog/debug-desk.yaml | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
 create mode 100644 plugin-catalog/debug-desk.yaml

diff --git a/plugin-catalog/debug-desk.yaml b/plugin-catalog/debug-desk.yaml
new file mode 100644
index 0000000000..c6267ef49a
--- /dev/null
+++ b/plugin-catalog/debug-desk.yaml
@@ -0,0 +1,22 @@
+name: debug-desk
+repo: https://github.com/aydnOktay/hermes-debug-desk
+sha: f9d2b5b4feea2aa110859280a724e93af8682919
+description: Today's git digest in the current repo, plus the last failed terminal
+  command the Hermes agent ran. Desktop pane, status chip, optional local LLM
+  summary. Does not watch OS or editor terminals.
+maintainer: aydnOktay
+tier: community
+category: desktop
+requires_hermes: ">=0.21"
+docs_url: https://github.com/aydnOktay/hermes-debug-desk
+version: "1.0.0"
+image: https://raw.githubusercontent.com/aydnOktay/hermes-debug-desk/f9d2b5b4feea2aa110859280a724e93af8682919/assets/banner.png
+platforms: []
+capabilities:
+  provides_tools:
+  - debug_daily_report
+  - debug_last_failure
+  provides_hooks:
+  - post_tool_call
+  provides_middleware: []
+  requires_env: []

From a23482a1f4beffd8ae59ee0190a65d8751620945 Mon Sep 17 00:00:00 2001
From: Doug Richar <drichar@gmail.com>
Date: Thu, 17 Sep 2026 09:53:15 -0400
Subject: [PATCH 113/190] feat(catalog): add zerosignal provider v0.1.0

---
 plugin-catalog/zerosignal.yaml | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
 create mode 100644 plugin-catalog/zerosignal.yaml

diff --git a/plugin-catalog/zerosignal.yaml b/plugin-catalog/zerosignal.yaml
new file mode 100644
index 0000000000..1779f8b47d
--- /dev/null
+++ b/plugin-catalog/zerosignal.yaml
@@ -0,0 +1,15 @@
+name: zerosignal
+repo: https://github.com/TxnLab/hermes-zerosignal-provider
+sha: ce1ba1f1603b4f191d3cd1aad284879df51a9f4a  # v0.1.0
+version: "0.1.0"
+description: ZeroSignal — private, pay-per-request inference through the local zs-proxy; no API key, your wallet is the credential.
+maintainer: TxnLab
+tier: community
+category: models
+docs_url: https://github.com/TxnLab/hermes-zerosignal-provider#readme
+capabilities:
+  provides_tools: []
+  provides_hooks: []
+  provides_middleware: []
+  requires_env:
+    - ZEROSIGNAL_API_KEY

From d02a840fb4794c3aa41d42fb52ea716cdd71a23a Mon Sep 17 00:00:00 2001
From: Doug Richar <drichar@gmail.com>
Date: Thu, 17 Sep 2026 13:27:18 -0400
Subject: [PATCH 114/190] feat(catalog): declare hermes floor and note the
 placeholder key for zerosignal

---
 plugin-catalog/zerosignal.yaml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/plugin-catalog/zerosignal.yaml b/plugin-catalog/zerosignal.yaml
index 1779f8b47d..b152e9f886 100644
--- a/plugin-catalog/zerosignal.yaml
+++ b/plugin-catalog/zerosignal.yaml
@@ -6,10 +6,13 @@ description: ZeroSignal — private, pay-per-request inference through the local
 maintainer: TxnLab
 tier: community
 category: models
+requires_hermes: ">=0.21"
 docs_url: https://github.com/TxnLab/hermes-zerosignal-provider#readme
 capabilities:
   provides_tools: []
   provides_hooks: []
   provides_middleware: []
+  # ZEROSIGNAL_API_KEY is a placeholder: Hermes needs a non-empty value, the
+  # proxy ignores it (the wallet is the credential). Any string works.
   requires_env:
     - ZEROSIGNAL_API_KEY

From 0b17162fa31d7d7f5ebf3b7c9f46e71eb1c6612b Mon Sep 17 00:00:00 2001
From: teknium <teknium@nousresearch.com>
Date: Fri, 18 Sep 2026 14:07:07 -0700
Subject: [PATCH 115/190] chore: map contributor email for @drichar

So check-attribution passes on the catalog PR.
---
 contributors/emails/drichar@gmail.com | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 contributors/emails/drichar@gmail.com

diff --git a/contributors/emails/drichar@gmail.com b/contributors/emails/drichar@gmail.com
new file mode 100644
index 0000000000..8f12b42e87
--- /dev/null
+++ b/contributors/emails/drichar@gmail.com
@@ -0,0 +1 @@
+drichar

From 2438d0a97e472550bc3542619f4a4d651107c9bf Mon Sep 17 00:00:00 2001
From: webtecnica <webtecnica@gmail.com>
Date: Fri, 11 Sep 2026 15:28:01 -0300
Subject: [PATCH 116/190] fix(state): track repair/probe connections so
 byte-probes can't cancel their locks

_connect_repair_durable() -- the single entry point for every repair/probe
connection to state.db -- opened the database with a bare sqlite3.connect(),
outside the live-connection registry in hermes_cli/sqlite_safe_read.py. While
a repair connection was open, has_live_connection() reported false, so any
byte-level probe in the process (zeroed-file detector, header verification,
kanban's post-commit page check) was free to open()/close() the file --
cancelling every POSIX advisory lock the process holds on it (howtocorrupt
2.2) and letting an external writer commit into a database the repair still
believed it owned. These paths hold the strongest locks in the process:
_open_exclusive() keeps locking_mode=EXCLUSIVE across the whole snapshot ->
strategies -> promotion window.

Open through connect_tracked() instead: the fd stays registered for its whole
lifetime and is released on close(). The sqlite3.connect(str(db_path), ...)
call stays in this module so tests patching it keep control, and installs
without hermes_cli keep the durable (untracked) connection as before.

Verified on real files, no mocks: with a repair connection holding
BEGIN EXCLUSIVE, an external writer is BLOCKED, a byte probe now returns None
(refused instead of opening the fd), the same writer stays BLOCKED after it,
and the registry is empty again once the repair closes. A real #63386-damaged
database (stale B-tree index) still reports exit 1 on --check-only and repairs
via reindex_btree to integrity_check 'ok'.

Refs #63386

(cherry picked from commit a031f1be26b777bc09e744b3fa6081ce2af1f851)
---
 hermes_state_repair.py                        | 24 ++++++-
 .../test_sqlite_lock_safe_inspection.py       | 62 +++++++++++++++++++
 2 files changed, 84 insertions(+), 2 deletions(-)

diff --git a/hermes_state_repair.py b/hermes_state_repair.py
index 7e8cc95879..e90f67b48c 100644
--- a/hermes_state_repair.py
+++ b/hermes_state_repair.py
@@ -580,8 +580,28 @@ def _connect_repair_durable(db_path: Path, *, timeout: float = 5.0) -> sqlite3.C
     no ``checkpoint_fullfsync`` — on Darwin an interrupted ``REINDEX``/``VACUUM``/``writable_schema`` rewrite leaves
     half-written b-tree pages. Autocommit (``isolation_level=None``): DDL and ``VACUUM`` are illegal inside an
     implicit transaction. Barriers are best-effort: on a malformed schema even ``PRAGMA synchronous=FULL`` raises,
-    so whole-file rewrites call :func:`_reapply_durability_barriers` once the schema parses again."""
-    conn = sqlite3.connect(str(db_path), timeout=timeout, isolation_level=None)
+    so whole-file rewrites call :func:`_reapply_durability_barriers` once the schema parses again.
+
+    Opened through :func:`hermes_cli.sqlite_safe_read.connect_tracked` so the fd is registered for its whole
+    lifetime: the repair paths hold the strongest locks in the process (``_open_exclusive`` keeps
+    ``locking_mode=EXCLUSIVE`` across the snapshot → strategies → promotion window, and the write-health probe
+    opens a ``BEGIN IMMEDIATE`` reservation). While untracked, every byte-level probe of a *live* state.db — the
+    zeroed-file detector, header verification, kanban's post-commit page check — was allowed to ``open()``/
+    ``close()`` the file, which cancels every POSIX advisory lock this process holds on it
+    (https://sqlite.org/howtocorrupt.html#_posix_advisory_locks_canceled_by_a_separate_thread_doing_close_)
+    and lets an external writer commit into a database the repair still believes it owns (#63386).
+    """
+    try:
+        from hermes_cli.sqlite_safe_read import connect_tracked
+    except ImportError:
+        # Scaffold/embed installs without hermes_cli: the durable connection stays, only the guard is off.
+        logger.debug("hermes_cli.sqlite_safe_read unavailable; opening %s untracked "
+                     "(byte-probe guard inactive in this install)", db_path)
+        conn = sqlite3.connect(str(db_path), timeout=timeout, isolation_level=None)
+    else:
+        # Open through THIS module's sqlite3.connect so tests patching it keep control of the fd.
+        conn = connect_tracked(db_path, tracking_path=db_path, connect_fn=sqlite3.connect,
+                               timeout=timeout, isolation_level=None)
     _reapply_durability_barriers(conn)
     return conn
 
diff --git a/tests/hermes_state/test_sqlite_lock_safe_inspection.py b/tests/hermes_state/test_sqlite_lock_safe_inspection.py
index 45a2d05b82..9eaea87b53 100644
--- a/tests/hermes_state/test_sqlite_lock_safe_inspection.py
+++ b/tests/hermes_state/test_sqlite_lock_safe_inspection.py
@@ -285,6 +285,68 @@ def test_session_db_read_only_is_tracked(tmp_path, clean_registry, monkeypatch):
     assert read_header_bytes_preopen(db_path, length=16) is not None
 
 
+def test_repair_connections_are_tracked_for_byte_probe_safety(tmp_path, clean_registry, monkeypatch):
+    """End-to-end: live repair/probe connections block byte-level reads (#63386).
+
+    The repair paths never go through ``SessionDB`` and they hold the strongest
+    locks in the process: ``_open_exclusive`` keeps ``locking_mode=EXCLUSIVE``
+    across the whole snapshot -> strategies -> promotion window, and the
+    write-health probe opens a ``BEGIN IMMEDIATE`` reservation. They used to
+    connect outside the registry, so the byte-probe guard could not see them and
+    every inspection ``open()``/``close()`` cancelled those POSIX advisory locks
+    (``howtocorrupt`` §2.2), letting an external writer commit into the database
+    the repair still believed it owned.
+    """
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+    from hermes_state import SessionDB
+    from hermes_state_repair import _connect_repair_durable, _repair_conn
+
+    db_path = tmp_path / "state.db"
+    seed = SessionDB(db_path=db_path)
+    seed.create_session("s1", source="cli")
+    seed.close()
+    assert not has_live_connection(db_path)
+
+    conn = _connect_repair_durable(db_path)
+    try:
+        assert has_live_connection(db_path)
+        assert read_header_bytes_preopen(db_path, length=16) is None
+    finally:
+        conn.close()
+    assert not has_live_connection(db_path)
+
+    with _repair_conn(db_path):
+        assert has_live_connection(db_path)
+        assert read_header_bytes_preopen(db_path, length=16) is None
+    assert not has_live_connection(db_path)
+    # The guard is released with the connection, not for good.
+    assert read_header_bytes_preopen(db_path, length=16) is not None
+
+
+def test_byte_probe_never_cancels_the_repair_exclusion(tmp_path, clean_registry):
+    """A live repair's EXCLUSIVE lock must survive Hermes' own inspection (#63386).
+
+    With the connection tracked the probe is refused, so nothing closes an fd and
+    the exclusion keeps holding; if the probe were allowed through, its ``close()``
+    would cancel the lock and the intruder would commit into the file mid-repair.
+    """
+    import hermes_state_repair as repair
+
+    db_path = tmp_path / "state.db"
+    _make_db(db_path, "DELETE")
+
+    guard = repair._open_exclusive(db_path, "BEGIN EXCLUSIVE")
+    try:
+        assert _external_writer_can_break_in(db_path) is False
+        assert read_header_bytes_preopen(db_path, length=16) is None
+        assert _external_writer_can_break_in(db_path) is False, (
+            "the repair's EXCLUSIVE lock was cancelled by a byte-level probe "
+            "on the database it holds"
+        )
+    finally:
+        guard.close()
+
+
 
 
 

From 471738da278b3b1416f2301b13c9aa982208f58d Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 02:30:08 +0530
Subject: [PATCH 117/190] refactor(state): drop the hermes_cli ImportError shim
 from the tracked repair connect

`hermes_cli` ships with every install that has `hermes_state_repair`, so the
"scaffold/embed installs without hermes_cli" fallback could never run and only
hid a broken import behind an untracked connection. Import directly; docstring
keeps the why (locks cancelled by a probe close, howtocorrupt 2.2) and drops
the restated mechanism.
---
 hermes_state_repair.py | 28 +++++++++-------------------
 1 file changed, 9 insertions(+), 19 deletions(-)

diff --git a/hermes_state_repair.py b/hermes_state_repair.py
index e90f67b48c..bb83bffb06 100644
--- a/hermes_state_repair.py
+++ b/hermes_state_repair.py
@@ -582,26 +582,16 @@ def _connect_repair_durable(db_path: Path, *, timeout: float = 5.0) -> sqlite3.C
     implicit transaction. Barriers are best-effort: on a malformed schema even ``PRAGMA synchronous=FULL`` raises,
     so whole-file rewrites call :func:`_reapply_durability_barriers` once the schema parses again.
 
-    Opened through :func:`hermes_cli.sqlite_safe_read.connect_tracked` so the fd is registered for its whole
-    lifetime: the repair paths hold the strongest locks in the process (``_open_exclusive`` keeps
-    ``locking_mode=EXCLUSIVE`` across the snapshot → strategies → promotion window, and the write-health probe
-    opens a ``BEGIN IMMEDIATE`` reservation). While untracked, every byte-level probe of a *live* state.db — the
-    zeroed-file detector, header verification, kanban's post-commit page check — was allowed to ``open()``/
-    ``close()`` the file, which cancels every POSIX advisory lock this process holds on it
-    (https://sqlite.org/howtocorrupt.html#_posix_advisory_locks_canceled_by_a_separate_thread_doing_close_)
-    and lets an external writer commit into a database the repair still believes it owns (#63386).
+    Tracked (:func:`hermes_cli.sqlite_safe_read.connect_tracked`) because repair connections hold the
+    strongest locks in the process (``locking_mode=EXCLUSIVE``, ``BEGIN IMMEDIATE``); an untracked fd let
+    the byte-level probes ``open()``/``close()`` the live file, which cancels every POSIX advisory lock this
+    process holds on it (sqlite.org/howtocorrupt §2.2) and lets an external writer commit mid-repair (#63386).
     """
-    try:
-        from hermes_cli.sqlite_safe_read import connect_tracked
-    except ImportError:
-        # Scaffold/embed installs without hermes_cli: the durable connection stays, only the guard is off.
-        logger.debug("hermes_cli.sqlite_safe_read unavailable; opening %s untracked "
-                     "(byte-probe guard inactive in this install)", db_path)
-        conn = sqlite3.connect(str(db_path), timeout=timeout, isolation_level=None)
-    else:
-        # Open through THIS module's sqlite3.connect so tests patching it keep control of the fd.
-        conn = connect_tracked(db_path, tracking_path=db_path, connect_fn=sqlite3.connect,
-                               timeout=timeout, isolation_level=None)
+    from hermes_cli.sqlite_safe_read import connect_tracked
+
+    # Through THIS module's sqlite3.connect so tests patching it keep control of the fd.
+    conn = connect_tracked(db_path, tracking_path=db_path, connect_fn=sqlite3.connect,
+                           timeout=timeout, isolation_level=None)
     _reapply_durability_barriers(conn)
     return conn
 

From 1c5798939a94ba2e56653865a3f3c9474aeadb96 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 02:43:03 +0530
Subject: [PATCH 118/190] test(state): the no-bare-connect guard covers the
 tracked helper

Gate review: `test_repair_path_has_no_bare_connects` pinned "the helper owns
exactly one sqlite3.connect(str(db_path))"; the helper now opens through
`connect_tracked`, so the guard is "no bare connect anywhere in the module".
Also drops the `connect_fn=sqlite3.connect` kwarg: `connect_tracked` late-binds
the same module attribute, so the kwarg (and its comment) said nothing true.
---
 hermes_state_repair.py                        |  4 +---
 .../test_state_db_write_durability.py         | 23 +++++--------------
 2 files changed, 7 insertions(+), 20 deletions(-)

diff --git a/hermes_state_repair.py b/hermes_state_repair.py
index bb83bffb06..81e1609543 100644
--- a/hermes_state_repair.py
+++ b/hermes_state_repair.py
@@ -589,9 +589,7 @@ def _connect_repair_durable(db_path: Path, *, timeout: float = 5.0) -> sqlite3.C
     """
     from hermes_cli.sqlite_safe_read import connect_tracked
 
-    # Through THIS module's sqlite3.connect so tests patching it keep control of the fd.
-    conn = connect_tracked(db_path, tracking_path=db_path, connect_fn=sqlite3.connect,
-                           timeout=timeout, isolation_level=None)
+    conn = connect_tracked(db_path, tracking_path=db_path, timeout=timeout, isolation_level=None)
     _reapply_durability_barriers(conn)
     return conn
 
diff --git a/tests/hermes_state/test_state_db_write_durability.py b/tests/hermes_state/test_state_db_write_durability.py
index 1385ddccf0..4ec9a1329c 100644
--- a/tests/hermes_state/test_state_db_write_durability.py
+++ b/tests/hermes_state/test_state_db_write_durability.py
@@ -130,23 +130,12 @@ def test_repair_path_has_no_bare_connects() -> None:
             and first.args[0].id == "db_path"
         )
 
-    helper = next(
-        node
-        for node in tree.body
-        if isinstance(node, ast.FunctionDef)
-        and node.name == "_connect_repair_durable"
-    )
-    helper_calls = [node for node in ast.walk(helper) if is_db_path_connect(node)]
-    assert len(helper_calls) == 1, (
-        "_connect_repair_durable must own exactly one sqlite3.connect(str(db_path), ...)"
-    )
-
-    all_calls = [node for node in ast.walk(tree) if is_db_path_connect(node)]
-    elsewhere = [node for node in all_calls if node not in helper_calls]
-    assert elsewhere == [], (
-        f"{len(elsewhere)} repair/probe connection(s) still bypass "
-        "_connect_repair_durable() and write state.db without the macOS "
-        "fsync barriers"
+    # The helper itself opens through ``connect_tracked`` (byte-probe registry, #63386), so no
+    # ``sqlite3.connect(str(db_path), ...)`` may remain anywhere in the module.
+    bare = [node for node in ast.walk(tree) if is_db_path_connect(node)]
+    assert bare == [], (
+        f"{len(bare)} repair/probe connection(s) bypass _connect_repair_durable() and write "
+        "state.db without the macOS fsync barriers or the live-connection registry"
     )
 
 

From 13d5b6516810c3d86890c6b85636c460c93c0e8f Mon Sep 17 00:00:00 2001
From: Felix Wunderlich <felix@opper.ai>
Date: Wed, 16 Sep 2026 23:33:00 +0200
Subject: [PATCH 119/190] feat(plugin-catalog): add hermes-opper (Opper model
 provider)

Owner-submitted entry for https://github.com/opper-ai/hermes-opper, pinned
to the v1.0.0 release commit. Category models; requires OPPER_API_KEY; no
tools, hooks or middleware.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 plugin-catalog/hermes-opper.yaml | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
 create mode 100644 plugin-catalog/hermes-opper.yaml

diff --git a/plugin-catalog/hermes-opper.yaml b/plugin-catalog/hermes-opper.yaml
new file mode 100644
index 0000000000..8e13243f1c
--- /dev/null
+++ b/plugin-catalog/hermes-opper.yaml
@@ -0,0 +1,15 @@
+name: hermes-opper
+repo: https://github.com/opper-ai/hermes-opper
+sha: 2e15f465b4c2a107fd0230611ebc1e5a7586a196
+description: Opper, the EU-hosted AI gateway (700+ models behind one OpenAI-compatible API), as a model provider
+maintainer: opper-ai
+tier: community
+category: models
+docs_url: https://github.com/opper-ai/hermes-opper#readme
+version: "1.0.0"
+capabilities:
+  provides_tools: []
+  provides_hooks: []
+  provides_middleware: []
+  requires_env:
+  - OPPER_API_KEY

From 93f108e49efa4618761c827c456884e21b04c374 Mon Sep 17 00:00:00 2001
From: teknium <teknium@nousresearch.com>
Date: Fri, 18 Sep 2026 14:06:36 -0700
Subject: [PATCH 120/190] chore: map contributor email for @Felixkw12

So check-attribution passes on the catalog PR.
---
 contributors/emails/felix@opper.ai | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 contributors/emails/felix@opper.ai

diff --git a/contributors/emails/felix@opper.ai b/contributors/emails/felix@opper.ai
new file mode 100644
index 0000000000..ac52d374a8
--- /dev/null
+++ b/contributors/emails/felix@opper.ai
@@ -0,0 +1 @@
+Felixkw12

From afbc17a716310716f9a96af113e70805c9fefc64 Mon Sep 17 00:00:00 2001
From: EMAD ALSEBAA <emad.alsaba@gmail.com>
Date: Thu, 17 Sep 2026 15:11:48 +0300
Subject: [PATCH 121/190] plugin-catalog: add session-styler (desktop)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Pins emadalsaba/hermes-session-styler at the commit that passes the pinned-source gate.
Capabilities declared empty: the plugin contributes no agent tools, hooks, middleware or env vars —
the whole implementation is the desktop half.
---
 plugin-catalog/session-styler.yaml | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)
 create mode 100644 plugin-catalog/session-styler.yaml

diff --git a/plugin-catalog/session-styler.yaml b/plugin-catalog/session-styler.yaml
new file mode 100644
index 0000000000..e42911ce2a
--- /dev/null
+++ b/plugin-catalog/session-styler.yaml
@@ -0,0 +1,21 @@
+name: session-styler
+repo: https://github.com/emadalsaba/hermes-session-styler
+sha: 1991d65b8bd70573acecba950ff0b4c248bfda11
+description: Style the Hermes Desktop session list — per-conversation icons from a ✦ menu on every row,
+  a status mark beside them, colors, sizes and match rules, with branch children inheriting their
+  parent's icon. Settings are mirrored into the active profile so a new machine restores them on load,
+  and every load reports itself to the profile under a per-machine key. Arabic + English, follows the
+  app's language.
+maintainer: emadalsaba
+tier: community
+category: desktop
+requires_hermes: ">=0.21.0"
+docs_url: https://github.com/emadalsaba/hermes-session-styler#readme
+version: "1.3.1"
+image: https://raw.githubusercontent.com/emadalsaba/hermes-session-styler/1991d65b8bd70573acecba950ff0b4c248bfda11/docs/banner.png
+platforms: []
+capabilities:
+  provides_tools: []
+  provides_hooks: []
+  provides_middleware: []
+  requires_env: []

From 745668c46e94ea29d89e4a433cc5c467f503a0d4 Mon Sep 17 00:00:00 2001
From: teknium <teknium@nousresearch.com>
Date: Fri, 18 Sep 2026 14:06:07 -0700
Subject: [PATCH 122/190] chore: map contributor email for @emadalsaba

So check-attribution passes on the catalog PR.
---
 contributors/emails/emad.alsaba@gmail.com | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 contributors/emails/emad.alsaba@gmail.com

diff --git a/contributors/emails/emad.alsaba@gmail.com b/contributors/emails/emad.alsaba@gmail.com
new file mode 100644
index 0000000000..37a5214505
--- /dev/null
+++ b/contributors/emails/emad.alsaba@gmail.com
@@ -0,0 +1 @@
+emadalsaba

From 2775bf736766e0ae532ac02f759d84164f97065f Mon Sep 17 00:00:00 2001
From: Quang-Phuc Phung <quangphucqp@gmail.com>
Date: Thu, 17 Sep 2026 06:35:48 -0400
Subject: [PATCH 123/190] catalog: add epistemic-harness

---
 plugin-catalog/epistemic-harness.yaml | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)
 create mode 100644 plugin-catalog/epistemic-harness.yaml

diff --git a/plugin-catalog/epistemic-harness.yaml b/plugin-catalog/epistemic-harness.yaml
new file mode 100644
index 0000000000..199e9db709
--- /dev/null
+++ b/plugin-catalog/epistemic-harness.yaml
@@ -0,0 +1,27 @@
+name: epistemic-harness
+repo: https://github.com/quangphucqp/epistemic-harness
+sha: eb45ca676df53cce0629a3cc5dcf8a7bdab1c806
+subdir: ""
+description: Record a provisional claim or uncertainty before an evidence-gathering step, then link the actual observation to it.
+maintainer: quangphucqp
+tier: community
+category: general
+requires_hermes: ">=0.21,<1.0"
+platforms:
+  - linux
+  - macos
+docs_url: https://github.com/quangphucqp/epistemic-harness#readme
+capabilities:
+  provides_tools:
+    - epistemic_model
+    - epistemic_probe
+  provides_hooks:
+    - pre_llm_call
+    - post_tool_call
+    - transform_tool_result
+    - subagent_stop
+    - on_session_reset
+    - on_session_finalize
+  provides_middleware:
+    - tool_execution
+  requires_env: []

From 1918700064c021123441bf3a1e48e1e5355585f3 Mon Sep 17 00:00:00 2001
From: teknium <teknium@nousresearch.com>
Date: Fri, 18 Sep 2026 14:05:59 -0700
Subject: [PATCH 124/190] chore: map contributor email for @quangphucqp

So check-attribution passes on the catalog PR.
---
 contributors/emails/quangphucqp@gmail.com | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 contributors/emails/quangphucqp@gmail.com

diff --git a/contributors/emails/quangphucqp@gmail.com b/contributors/emails/quangphucqp@gmail.com
new file mode 100644
index 0000000000..5d3d6117d0
--- /dev/null
+++ b/contributors/emails/quangphucqp@gmail.com
@@ -0,0 +1 @@
+quangphucqp

From 328503b5628bfa2837f29e7b54fdc7921643ff90 Mon Sep 17 00:00:00 2001
From: Ricard <ricardpons@me.com>
Date: Thu, 17 Sep 2026 08:43:54 +0200
Subject: [PATCH 125/190] feat(catalog): add Replaid plugin

---
 plugin-catalog/replaid.yaml | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
 create mode 100644 plugin-catalog/replaid.yaml

diff --git a/plugin-catalog/replaid.yaml b/plugin-catalog/replaid.yaml
new file mode 100644
index 0000000000..2222d297b6
--- /dev/null
+++ b/plugin-catalog/replaid.yaml
@@ -0,0 +1,17 @@
+name: replaid
+repo: https://github.com/replaid-pro/replaid-hermes
+sha: 3f8881f2f9f6ee27b59515ff9fef0afee33b87e0
+description: Connect Replaid with OAuth to read, triage, and draft replies in your social inbox.
+maintainer: replaid-pro
+tier: community
+category: tools
+requires_hermes: ">=0.21.3"
+docs_url: https://github.com/replaid-pro/replaid-hermes#readme
+version: "0.2.1"
+capabilities:
+  provides_tools:
+    - replaid_connection_status
+  provides_hooks:
+    - pre_llm_call
+  provides_middleware: []
+  requires_env: []

From d9b43a7ac6b3a36ab594d73d5c9eedd9b2883f1e Mon Sep 17 00:00:00 2001
From: teknium <teknium@nousresearch.com>
Date: Fri, 18 Sep 2026 14:05:51 -0700
Subject: [PATCH 126/190] chore: map contributor email for @ricki-io

So check-attribution passes on the catalog PR.
---
 contributors/emails/ricardpons@me.com | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 contributors/emails/ricardpons@me.com

diff --git a/contributors/emails/ricardpons@me.com b/contributors/emails/ricardpons@me.com
new file mode 100644
index 0000000000..b79e0100dc
--- /dev/null
+++ b/contributors/emails/ricardpons@me.com
@@ -0,0 +1 @@
+ricki-io

From b9cf6bf794f2b461fb4bca9b320418ef08e7a4de Mon Sep 17 00:00:00 2001
From: tobenwarrior <lucasyee999@gmail.com>
Date: Thu, 17 Sep 2026 13:40:48 +0800
Subject: [PATCH 127/190] feat(plugin-catalog): add kiro-acp community plugin
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Kiro CLI (AWS) as a Hermes model provider via the external-process (ACP)
seam — a ProviderProfile spawning `kiro-cli acp` over stdio, extending the
in-tree copilot-acp shim. Pinned to v0.1.0 (fe95ccba), which is
E2E-verified: discovery via both install paths, live completion through
kiro-cli 2.22.0, plugin test suite 5/5 green at that commit.
---
 plugin-catalog/kiro-acp.yaml | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
 create mode 100644 plugin-catalog/kiro-acp.yaml

diff --git a/plugin-catalog/kiro-acp.yaml b/plugin-catalog/kiro-acp.yaml
new file mode 100644
index 0000000000..d984ead6c1
--- /dev/null
+++ b/plugin-catalog/kiro-acp.yaml
@@ -0,0 +1,14 @@
+name: kiro-acp
+repo: https://github.com/tobenwarrior/hermes-kiro-provider
+sha: fe95ccba1d72ca5d09b581c350b2a44e4c061a6f
+description: Kiro CLI (AWS) as a Hermes model provider, driven over ACP stdio.
+maintainer: tobenwarrior
+tier: community
+category: models
+docs_url: https://github.com/tobenwarrior/hermes-kiro-provider#readme
+version: "0.1.0"
+capabilities:
+  provides_tools: []
+  provides_hooks: []
+  provides_middleware: []
+  requires_env: []

From 7d360ef8e3f4c2d8d095257ca4cfcc98a28a6b93 Mon Sep 17 00:00:00 2001
From: tobenwarrior <lucasyee999@gmail.com>
Date: Thu, 17 Sep 2026 14:01:39 +0800
Subject: [PATCH 128/190] plugin-catalog: bump kiro-acp pin to v0.1.1
 (lazy-import registration fix)

---
 plugin-catalog/kiro-acp.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/plugin-catalog/kiro-acp.yaml b/plugin-catalog/kiro-acp.yaml
index d984ead6c1..52641f282e 100644
--- a/plugin-catalog/kiro-acp.yaml
+++ b/plugin-catalog/kiro-acp.yaml
@@ -1,12 +1,12 @@
 name: kiro-acp
 repo: https://github.com/tobenwarrior/hermes-kiro-provider
-sha: fe95ccba1d72ca5d09b581c350b2a44e4c061a6f
+sha: db387b4f82e13c9d3fc1034f47d4bf4187d9ebbf
 description: Kiro CLI (AWS) as a Hermes model provider, driven over ACP stdio.
 maintainer: tobenwarrior
 tier: community
 category: models
 docs_url: https://github.com/tobenwarrior/hermes-kiro-provider#readme
-version: "0.1.0"
+version: "0.1.1"
 capabilities:
   provides_tools: []
   provides_hooks: []

From 4c6c2cbf56edd0323a1194bb01460598ef4fa87b Mon Sep 17 00:00:00 2001
From: tobenwarrior <lucasyee999@gmail.com>
Date: Thu, 17 Sep 2026 15:05:33 +0800
Subject: [PATCH 129/190] plugin-catalog: bump kiro-acp pin to v0.1.2 (live
 model catalog)

---
 plugin-catalog/kiro-acp.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/plugin-catalog/kiro-acp.yaml b/plugin-catalog/kiro-acp.yaml
index 52641f282e..53fe821cb5 100644
--- a/plugin-catalog/kiro-acp.yaml
+++ b/plugin-catalog/kiro-acp.yaml
@@ -1,12 +1,12 @@
 name: kiro-acp
 repo: https://github.com/tobenwarrior/hermes-kiro-provider
-sha: db387b4f82e13c9d3fc1034f47d4bf4187d9ebbf
+sha: 88e5b023b8ecca9dcc6059676c14f49a940d3f4a
 description: Kiro CLI (AWS) as a Hermes model provider, driven over ACP stdio.
 maintainer: tobenwarrior
 tier: community
 category: models
 docs_url: https://github.com/tobenwarrior/hermes-kiro-provider#readme
-version: "0.1.1"
+version: "0.1.2"
 capabilities:
   provides_tools: []
   provides_hooks: []

From 6c02e39a5a32f8d4ab5214845220a592d9766a36 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 00:59:32 -0700
Subject: [PATCH 130/190] docs(website): tell GitHub readers the docs are
 authored for the rendered site; record the link convention

Cross-page links under website/docs are Docusaurus doc-root routes
(1,338 across 250 EN files, 898 in the zh-Hans mirror) and 404 in GitHub's
file viewer, which resolves them as repository paths. Converting the tree
(~2,200 links, anchors in cross-section links, two locales) is a maintainer
call; until then the README at the top of website/ says where the rendered
docs live and how links are written, so new pages stay consistent with
their neighbours.
---
 website/README.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/website/README.md b/website/README.md
index d5a39ea50a..b22ff47a88 100644
--- a/website/README.md
+++ b/website/README.md
@@ -2,6 +2,21 @@
 
 This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
+> **Reading the docs on GitHub?** The Markdown under `docs/` is authored for the rendered site at
+> <https://hermes-agent.nousresearch.com/docs/>. Most cross-page links are Docusaurus site routes
+> (`/getting-started/installation`), which GitHub's file viewer resolves as repository paths and 404s.
+> Every page has an **Edit this page** link on the site that opens the source file here.
+
+## Authoring links in `docs/`
+
+- Link to another page with a doc-root route (`[Profiles](/user-guide/profiles)`) or a relative
+  Markdown path (`[Profiles](../user-guide/profiles.md)`). Both render on the site; only the
+  relative form also resolves on GitHub.
+- Never write `/docs/...` in a link: `baseUrl` is already `/docs/`, so the zh-Hans build emits
+  `/docs/zh-Hans/docs/...` 404s.
+- Cross-section links with an anchor use the route form (`/section/page#anchor`); pin `{#anchor}`
+  on the target heading so the zh-Hans mirror keeps the same id.
+
 ## Installation
 
 ```bash

From 36fb2be9267c7155a5451292d8af250e5dcba0f4 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 04:55:40 -0700
Subject: [PATCH 131/190] fix(website): cross-page doc links resolve on GitHub
 as well as on the site

Docs under website/docs were linked with Docusaurus site routes
(`](/getting-started/installation)`, `](/docs/user-guide/x)`), which GitHub's
file viewer resolves as repository paths and 404s (#114428). Relative Markdown
file links (`](../user-guide/x.md#anchor)`) are followed by both GitHub and
Docusaurus, so that becomes the authoring convention:

- website/scripts/check_doc_links.py lints hand-authored EN + zh-Hans pages
  for route-style links (`--fix` rewrites them, refusing any route that maps
  to no doc file); wired into the Docs Site Checks workflow and
  tests/website/test_check_doc_links.py.
- generate-skill-docs.py emits the same relative form for related-skill and
  catalog links instead of `/docs/user-guide/skills/...`.
- src/remark/relativeDocLinks.js rewrites `./x.md`/`../x.md` to
  content-root-absolute `/x.md` before Docusaurus resolves links, so a
  relative link still resolves in the zh-Hans build when source and target
  sit on different sides of the translation fallback (Docusaurus resolves
  `./`/`../` only against the source file's own directory).
- website/README.md states the convention and points at the checker.
---
 .github/workflows/docs-site-checks.yml |   3 +
 tests/website/test_check_doc_links.py  |  61 +++++++
 website/README.md                      |  24 +--
 website/docusaurus.config.ts           |   4 +
 website/scripts/check_doc_links.py     | 217 +++++++++++++++++++++++++
 website/scripts/generate-skill-docs.py |   9 +-
 website/src/remark/relativeDocLinks.js |  66 ++++++++
 7 files changed, 370 insertions(+), 14 deletions(-)
 create mode 100644 tests/website/test_check_doc_links.py
 create mode 100644 website/scripts/check_doc_links.py
 create mode 100644 website/src/remark/relativeDocLinks.js

diff --git a/.github/workflows/docs-site-checks.yml b/.github/workflows/docs-site-checks.yml
index 1e82698218..8a3e71ef2a 100644
--- a/.github/workflows/docs-site-checks.yml
+++ b/.github/workflows/docs-site-checks.yml
@@ -44,6 +44,9 @@ jobs:
       - name: Regenerate per-skill docs pages + catalogs
         run: python3 website/scripts/generate-skill-docs.py
 
+      - name: Check cross-page links resolve on GitHub and on the site
+        run: python3 website/scripts/check_doc_links.py
+
       - name: Lint docs diagrams
         run: npm run lint:diagrams
         working-directory: website
diff --git a/tests/website/test_check_doc_links.py b/tests/website/test_check_doc_links.py
new file mode 100644
index 0000000000..21face2e0d
--- /dev/null
+++ b/tests/website/test_check_doc_links.py
@@ -0,0 +1,61 @@
+"""Tests for website/scripts/check_doc_links.py.
+
+Cross-page links in hand-authored docs must be relative Markdown paths so they
+resolve on GitHub's file viewer as well as on the rendered site (#114428).
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+CHECKER = REPO_ROOT / "website" / "scripts" / "check_doc_links.py"
+
+
+@pytest.fixture(scope="module")
+def checker():
+    spec = importlib.util.spec_from_file_location("check_doc_links", CHECKER)
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def test_hand_authored_docs_have_no_route_style_links(checker):
+    """The live tree stays clean: every route-style link 404s on GitHub."""
+    assert checker.main(["--en-only"]) == 0
+
+
+def test_fix_rewrites_route_to_relative_path_keeping_anchor(checker, tmp_path, monkeypatch):
+    docs = tmp_path / "docs"
+    (docs / "getting-started").mkdir(parents=True)
+    (docs / "user-guide" / "features").mkdir(parents=True)
+    (docs / "user-guide" / "features" / "skills.md").write_text("# Skills\n", encoding="utf-8")
+    (docs / "user-guide" / "features" / "index.md").write_text("# Features\n", encoding="utf-8")
+    src = docs / "getting-started" / "learning-path.md"
+    src.write_text(
+        "[Skills](/user-guide/features/skills#bundles) [Docs](/docs/user-guide/features)\n"
+        "[Site page](/skills) [Same](./quickstart.md)\n"
+        "```\n[example](/user-guide/features/skills)\n```\n",
+        encoding="utf-8",
+    )
+    monkeypatch.setattr(checker, "EN_DOCS", docs)
+    monkeypatch.setattr(checker, "ZH_DOCS", tmp_path / "missing")
+
+    assert checker.main([]) == 1
+    assert checker.main(["--fix"]) == 0
+    text = src.read_text(encoding="utf-8")
+    assert "[Skills](../user-guide/features/skills.md#bundles)" in text
+    assert "[Docs](../user-guide/features/index.md)" in text
+    # Non-doc routes and fenced examples are left alone.
+    assert "[Site page](/skills)" in text
+    assert "```\n[example](/user-guide/features/skills)\n```" in text
+    assert checker.main([]) == 0
+
+    # A route that maps to no file is an error, not a silent rewrite.
+    src.write_text("[Gone](/user-guide/nope)\n", encoding="utf-8")
+    assert checker.main(["--fix"]) == 1
+    assert src.read_text(encoding="utf-8") == "[Gone](/user-guide/nope)\n"
diff --git a/website/README.md b/website/README.md
index b22ff47a88..cd07410922 100644
--- a/website/README.md
+++ b/website/README.md
@@ -3,19 +3,23 @@
 This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
 > **Reading the docs on GitHub?** The Markdown under `docs/` is authored for the rendered site at
-> <https://hermes-agent.nousresearch.com/docs/>. Most cross-page links are Docusaurus site routes
-> (`/getting-started/installation`), which GitHub's file viewer resolves as repository paths and 404s.
-> Every page has an **Edit this page** link on the site that opens the source file here.
+> <https://hermes-agent.nousresearch.com/docs/>. Cross-page links are relative Markdown paths, so they
+> follow through on GitHub's file viewer too. Every page on the site has an **Edit this page** link
+> that opens the source file here.
 
 ## Authoring links in `docs/`
 
-- Link to another page with a doc-root route (`[Profiles](/user-guide/profiles)`) or a relative
-  Markdown path (`[Profiles](../user-guide/profiles.md)`). Both render on the site; only the
-  relative form also resolves on GitHub.
-- Never write `/docs/...` in a link: `baseUrl` is already `/docs/`, so the zh-Hans build emits
-  `/docs/zh-Hans/docs/...` 404s.
-- Cross-section links with an anchor use the route form (`/section/page#anchor`); pin `{#anchor}`
-  on the target heading so the zh-Hans mirror keeps the same id.
+- Link to another page with a relative Markdown path, anchors included:
+  `[Profiles](../user-guide/profiles.md)`, `[Bundles](../user-guide/features/skills.md#skill-bundles)`.
+  Docusaurus turns the file path into the page route; GitHub follows the same path. Site routes
+  (`/user-guide/profiles`, `/docs/user-guide/profiles`) only work on the rendered site — GitHub
+  resolves them as repository paths and 404s, and the `/docs/` form also emits
+  `/docs/zh-Hans/docs/...` 404s in the zh-Hans build because `baseUrl` is already `/docs/`.
+- `python3 website/scripts/check_doc_links.py` fails on any route-style link in hand-authored pages
+  (EN and the zh-Hans mirror); `--fix` rewrites them. It runs in the `Docs Site Checks` workflow.
+  Generated pages (`user-guide/skills/{bundled,optional}`, `reference/*skills-catalog.md`) are
+  produced by `scripts/generate-skill-docs.py`, which emits the same relative form.
+- Pin `{#anchor}` on cross-linked headings so the zh-Hans mirror keeps the same id.
 
 ## Installation
 
diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts
index 4963c54870..cb82b8e85e 100644
--- a/website/docusaurus.config.ts
+++ b/website/docusaurus.config.ts
@@ -1,6 +1,7 @@
 import {themes as prismThemes} from 'prism-react-renderer';
 import type {Config} from '@docusaurus/types';
 import type * as Preset from '@docusaurus/preset-classic';
+import relativeDocLinks from './src/remark/relativeDocLinks';
 
 const config: Config = {
   title: 'Hermes Agent',
@@ -81,6 +82,9 @@ const config: Config = {
           routeBasePath: '/',  // Docs at the root of /docs/
           sidebarPath: './sidebars.ts',
           editUrl: 'https://github.com/NousResearch/hermes-agent/edit/main/website/',
+          // Relative `.md` links (readable on GitHub, #114428) must also resolve
+          // across the zh-Hans fallback boundary; see src/remark/relativeDocLinks.js.
+          beforeDefaultRemarkPlugins: [[relativeDocLinks, {siteDir: __dirname}]],
         },
         blog: false,
         theme: {
diff --git a/website/scripts/check_doc_links.py b/website/scripts/check_doc_links.py
new file mode 100644
index 0000000000..9c5dc5df4a
--- /dev/null
+++ b/website/scripts/check_doc_links.py
@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""Keep cross-page links in website/docs resolvable on GitHub AND on the site.
+
+Docusaurus turns a relative Markdown file link (`../user-guide/profiles.md#anchor`)
+into the page route, and GitHub's file viewer follows the same path. A site
+route written as a link (`/user-guide/profiles`, `/docs/user-guide/profiles`)
+only works on the rendered site: GitHub resolves it as a repository path and
+404s (issue #114428).
+
+Check mode (default) lists every route-style link in hand-authored pages and
+exits 1 when any exist. `--fix` rewrites them in place to relative file links,
+preserving `#anchor`, and fails on a route that does not map to a doc file.
+
+Exempt, in both modes:
+- generated pages (per-skill pages and the skills catalogs produced by
+  generate-skill-docs.py; the generator itself emits relative links);
+- routes that are not docs: `/skills`, `/plugins` (React pages), `/img/...`,
+  `/llms*.txt`, `/api/...` (static assets).
+
+Usage:
+    python3 website/scripts/check_doc_links.py            # lint EN + zh-Hans
+    python3 website/scripts/check_doc_links.py --fix      # rewrite in place
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import sys
+from pathlib import Path
+
+WEBSITE = Path(__file__).resolve().parents[1]
+EN_DOCS = WEBSITE / "docs"
+ZH_DOCS = WEBSITE / "i18n" / "zh-Hans" / "docusaurus-plugin-content-docs" / "current"
+
+# Written by generate-skill-docs.py; edit the generator, never these outputs.
+GENERATED_PREFIXES = ("user-guide/skills/bundled/", "user-guide/skills/optional/")
+GENERATED_FILES = {"reference/skills-catalog.md", "reference/optional-skills-catalog.md"}
+
+# Site routes that are not documents: React pages and static assets.
+NON_DOC_ROUTE_PREFIXES = ("/skills", "/plugins", "/img/", "/llms", "/api/")
+
+LINK_RE = re.compile(r"\]\((/[^)\s]*)\)")
+FENCE_RE = re.compile(r"^\s*(```|~~~)")
+
+
+def is_generated(rel: str) -> bool:
+    return rel.startswith(GENERATED_PREFIXES) or rel in GENERATED_FILES
+
+
+def frontmatter_slug(text: str) -> str | None:
+    if not text.startswith("---"):
+        return None
+    end = text.find("\n---", 3)
+    if end < 0:
+        return None
+    m = re.search(r"^slug:\s*(\S+)\s*$", text[3:end], re.MULTILINE)
+    return m.group(1).strip("'\"") if m else None
+
+
+def route_for(rel: str, text: str) -> str:
+    """Docusaurus route (relative to the docs root) for a source file."""
+    slug = frontmatter_slug(text)
+    if slug and slug.startswith("/"):
+        return slug.rstrip("/") or "/"
+    stem = re.sub(r"\.mdx?$", "", rel)
+    if stem == "index":
+        return "/"
+    if stem.endswith("/index"):
+        stem = stem[: -len("/index")]
+    return "/" + stem
+
+
+def route_map(docs_root: Path) -> dict[str, Path]:
+    routes: dict[str, Path] = {}
+    for path in sorted(docs_root.rglob("*.md*")):
+        if path.suffix not in (".md", ".mdx"):
+            continue
+        rel = path.relative_to(docs_root).as_posix()
+        routes[route_for(rel, path.read_text(encoding="utf-8"))] = path
+    return routes
+
+
+def normalize_route(target: str) -> tuple[str, str]:
+    """Split a link target into (route, suffix) where suffix is `#anchor`/`?q`."""
+    suffix = ""
+    cut = min((i for i in (target.find("#"), target.find("?")) if i >= 0), default=-1)
+    if cut >= 0:
+        target, suffix = target[:cut], target[cut:]
+    if target.startswith("/docs/"):
+        target = target[len("/docs") :]
+    elif target == "/docs":
+        target = "/"
+    if len(target) > 1:
+        target = target.rstrip("/")
+    return target, suffix
+
+
+def relative_link(source: Path, source_root: Path, target: Path, target_root: Path) -> str:
+    """Path from `source` to `target`, expressed inside the source's own tree.
+
+    zh-Hans pages fall back to the EN file when no translation exists; the
+    relative path is computed as if the target sat in the same tree, which is
+    how both Docusaurus (locale content paths) and GitHub (EN files) resolve it.
+    """
+    target_rel = target.relative_to(target_root)
+    virtual_target = source_root / target_rel
+    rel = Path(os.path.relpath(virtual_target, source.parent)).as_posix()
+    return rel if rel.startswith(".") else "./" + rel
+
+
+def iter_links(text: str):
+    """Yield (line_no, match) for markdown links outside fenced code blocks."""
+    in_fence = False
+    for line_no, line in enumerate(text.splitlines(), 1):
+        if FENCE_RE.match(line):
+            in_fence = not in_fence
+            continue
+        if in_fence:
+            continue
+        for m in LINK_RE.finditer(line):
+            # Skip links quoted inside inline code (`[x](/y)` examples).
+            if line[: m.start()].count("`") % 2 == 1:
+                continue
+            yield line_no, m
+
+
+def process_tree(
+    docs_root: Path,
+    en_routes: dict[str, Path],
+    fix: bool,
+    include_generated: bool,
+) -> tuple[list[str], list[str], int]:
+    """Return (route_style_findings, unresolved_findings, files_rewritten)."""
+    local_routes = route_map(docs_root) if docs_root != EN_DOCS else en_routes
+    findings: list[str] = []
+    unresolved: list[str] = []
+    rewritten = 0
+    for path in sorted(docs_root.rglob("*.md*")):
+        if path.suffix not in (".md", ".mdx"):
+            continue
+        rel = path.relative_to(docs_root).as_posix()
+        if is_generated(rel) and not include_generated:
+            continue
+        text = path.read_text(encoding="utf-8")
+        replacements: dict[str, str] = {}
+        for line_no, m in iter_links(text):
+            target = m.group(1)
+            route, suffix = normalize_route(target)
+            if route.startswith(NON_DOC_ROUTE_PREFIXES):
+                continue
+            shown = path.relative_to(WEBSITE) if path.is_relative_to(WEBSITE) else path
+            where = f"{shown}:{line_no}: {target}"
+            hit = local_routes.get(route) or en_routes.get(route)
+            if hit is None:
+                unresolved.append(where)
+                continue
+            findings.append(where)
+            if fix:
+                root = docs_root if hit.is_relative_to(docs_root) else EN_DOCS
+                replacements[m.group(0)] = "](" + relative_link(path, docs_root, hit, root) + suffix + ")"
+        if fix and replacements and not unresolved:
+            new_text = text
+            for old, new in replacements.items():
+                new_text = new_text.replace(old, new)
+            path.write_text(new_text, encoding="utf-8")
+            rewritten += 1
+    return findings, unresolved, rewritten
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--fix", action="store_true", help="rewrite route-style links to relative file links")
+    parser.add_argument(
+        "--include-generated",
+        action="store_true",
+        help="also process generator outputs (only for a one-off migration; the generator owns them)",
+    )
+    parser.add_argument("--en-only", action="store_true", help="skip the zh-Hans mirror")
+    args = parser.parse_args(argv)
+
+    en_routes = route_map(EN_DOCS)
+    trees = [EN_DOCS] if args.en_only or not ZH_DOCS.exists() else [EN_DOCS, ZH_DOCS]
+    all_findings: list[str] = []
+    all_unresolved: list[str] = []
+    rewritten = 0
+    for tree in trees:
+        f, u, r = process_tree(tree, en_routes, args.fix, args.include_generated)
+        all_findings += f
+        all_unresolved += u
+        rewritten += r
+
+    if all_unresolved:
+        print("Route-style links that match no doc file (fix the target first):", file=sys.stderr)
+        for line in all_unresolved:
+            print(f"  {line}", file=sys.stderr)
+        return 1
+    if args.fix:
+        print(f"Rewrote {len(all_findings)} route-style links in {rewritten} files.")
+        return 0
+    if all_findings:
+        print(
+            "Route-style links found in hand-authored docs. They 404 on GitHub; write a relative\n"
+            "Markdown path instead (`../user-guide/profiles.md#anchor`) or run\n"
+            "`python3 website/scripts/check_doc_links.py --fix`:",
+            file=sys.stderr,
+        )
+        for line in all_findings:
+            print(f"  {line}", file=sys.stderr)
+        return 1
+    print("OK: no route-style links in hand-authored docs.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/website/scripts/generate-skill-docs.py b/website/scripts/generate-skill-docs.py
index 7e10e858b6..0cd510998f 100755
--- a/website/scripts/generate-skill-docs.py
+++ b/website/scripts/generate-skill-docs.py
@@ -395,9 +395,10 @@ def render_skill_page(
             if skill_index is not None:
                 target_meta = skill_index.get(r)
             if target_meta is not None:
+                # Relative file link: resolves on the site and on GitHub (#114428).
                 href = (
-                    f"/docs/user-guide/skills/{target_meta['source_kind']}"
-                    f"/{target_meta['category']}/{page_id(target_meta)}"
+                    f"../../{target_meta['source_kind']}"
+                    f"/{target_meta['category']}/{page_id(target_meta)}.md"
                 )
                 link_parts.append(f"[`{r}`]({href})")
             else:
@@ -495,7 +496,7 @@ def build_catalog_md_bundled(entries: list[tuple[dict[str, Any], dict[str, Any]]
             desc = (fm.get("description") or "").strip()
             if len(desc) > 240:
                 desc = desc[:237].rstrip() + "..."
-            link_target = f"/docs/user-guide/skills/bundled/{meta['category']}/{page_id(meta)}"
+            link_target = f"../user-guide/skills/bundled/{meta['category']}/{page_id(meta)}.md"
             path = f"`{meta['rel_path']}`"
             desc_esc = mdx_escape_body(desc).replace("|", "\\|").replace("\n", " ")
             lines.append(
@@ -556,7 +557,7 @@ def build_catalog_md_optional(entries: list[tuple[dict[str, Any], dict[str, Any]
             desc = (fm.get("description") or "").strip()
             if len(desc) > 240:
                 desc = desc[:237].rstrip() + "..."
-            link_target = f"/docs/user-guide/skills/optional/{meta['category']}/{page_id(meta)}"
+            link_target = f"../user-guide/skills/optional/{meta['category']}/{page_id(meta)}.md"
             desc_esc = mdx_escape_body(desc).replace("|", "\\|").replace("\n", " ")
             lines.append(f"| [**{name}**]({link_target}) | {desc_esc} |")
         lines.append("")
diff --git a/website/src/remark/relativeDocLinks.js b/website/src/remark/relativeDocLinks.js
new file mode 100644
index 0000000000..4d2c478200
--- /dev/null
+++ b/website/src/remark/relativeDocLinks.js
@@ -0,0 +1,66 @@
+// Remark plugin: make relative Markdown file links resolve across the zh-Hans
+// fallback boundary.
+//
+// Docs are authored with relative file links (`../user-guide/profiles.md`) so
+// they also open on GitHub (#114428). Docusaurus resolves `./x.md` and
+// `../x.md` only against the *source file's own directory*. In a localized
+// build, an untranslated EN page (served as fallback) linking to a translated
+// page — or the reverse — then fails to resolve, because the target's source
+// lives in the other content root. A content-root-absolute file link
+// (`/user-guide/profiles.md`) is resolved against every content path
+// (i18n/<locale>/.../current first, then docs/), so this plugin rewrites the
+// relative form to that form before Docusaurus's own link resolution runs.
+//
+// Only links with a Markdown extension are touched; anything else (routes,
+// assets, external URLs) passes through untouched.
+
+const path = require('path');
+
+const MARKDOWN_LINK = /^(\.\.?\/[^?#]*\.mdx?)([?#].*)?$/i;
+const LOCALIZED_ROOT = /^(.*\/i18n\/[^/]+\/docusaurus-plugin-content-docs\/[^/]+)\//;
+
+function contentRoot(sourceFilePath, siteDir) {
+  const posixPath = sourceFilePath.split(path.sep).join('/');
+  const localized = LOCALIZED_ROOT.exec(posixPath);
+  if (localized) {
+    return localized[1];
+  }
+  return path.posix.join(siteDir.split(path.sep).join('/'), 'docs');
+}
+
+function walk(node, visitor) {
+  if (!node || typeof node !== 'object') {
+    return;
+  }
+  if (node.type === 'link' || node.type === 'definition') {
+    visitor(node);
+  }
+  if (Array.isArray(node.children)) {
+    node.children.forEach((child) => walk(child, visitor));
+  }
+}
+
+function plugin(options = {}) {
+  const siteDir = options.siteDir || process.cwd();
+  return (root, file) => {
+    if (!file.path) {
+      return;
+    }
+    const sourceDir = path.posix.dirname(file.path.split(path.sep).join('/'));
+    const root_ = contentRoot(file.path, siteDir);
+    walk(root, (node) => {
+      const match = MARKDOWN_LINK.exec(node.url || '');
+      if (!match) {
+        return;
+      }
+      const resolved = path.posix.normalize(path.posix.join(sourceDir, match[1]));
+      const relToRoot = path.posix.relative(root_, resolved);
+      if (relToRoot.startsWith('../')) {
+        return; // points outside the docs tree; leave it to Docusaurus
+      }
+      node.url = '/' + relToRoot + (match[2] || '');
+    });
+  };
+}
+
+module.exports = plugin;

From 2fbcd8b0eac804ec60dccd9d24b67feadc6c65cd Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 04:55:40 -0700
Subject: [PATCH 132/190] docs(website): link pages by relative Markdown path
 so they open on GitHub (#114428)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Mechanical `check_doc_links.py --fix` pass over website/docs (hand-authored
and generated pages) and the zh-Hans mirror: 1,868 route-style links
(`](/section/page#anchor)`, `](/docs/...)`) become `](../section/page.md#anchor)`.
Every target was asserted to exist on disk; anchors and query strings are
preserved; fenced code blocks and inline-code examples are untouched.

Two dead targets found by the converter were fixed by hand first:
memory-providers.md linked `/user-guide/plugins` (page is
`user-guide/features/plugins`), and the zh-Hans learning-path still linked the
removed `rl-training` page — ported the EN treatment (external Atropos link).

Docusaurus build after: EN locale 0 unresolved Markdown links, 0 broken links,
0 broken anchors.
---
 .../docs/developer-guide/adding-providers.md  |   2 +-
 website/docs/developer-guide/adding-tools.md  |   4 +-
 website/docs/developer-guide/architecture.md  |   2 +-
 .../browser-provider-plugin.md                |   2 +-
 .../context-compression-and-caching.md        |   2 +-
 .../developer-guide/context-engine-plugin.md  |   6 +-
 .../docs/developer-guide/creating-skills.md   |   2 +-
 .../docs/developer-guide/cron-internals.md    |   2 +-
 .../developer-guide/desktop-plugin-sdk.md     |  10 +-
 .../docs/developer-guide/gateway-internals.md |   6 +-
 .../image-gen-provider-plugin.md              |  10 +-
 .../developer-guide/memory-provider-plugin.md |   4 +-
 .../developer-guide/model-provider-plugin.md  |  14 +-
 .../docs/developer-guide/plugin-llm-access.md |   2 +-
 website/docs/developer-guide/plugins/index.md |  88 +++---
 .../relay-connector-contract.md               |   2 +-
 .../developer-guide/secret-source-plugin.md   |   4 +-
 .../terminal-environment-plugin.md            |   2 +-
 .../video-gen-provider-plugin.md              |   2 +-
 .../web-search-provider-plugin.md             |  14 +-
 website/docs/getting-started/installation.md  |   6 +-
 website/docs/getting-started/learning-path.md | 138 ++++----
 website/docs/getting-started/quickstart.md    |   6 +-
 website/docs/getting-started/updating.md      |   4 +-
 website/docs/guides/automate-with-cron.md     |  10 +-
 website/docs/guides/automation-blueprints.md  |   4 +-
 website/docs/guides/azure-foundry.md          |   6 +-
 website/docs/guides/cron-script-only.md       |  12 +-
 website/docs/guides/cron-troubleshooting.md   |   2 +-
 website/docs/guides/daily-briefing-bot.md     |  20 +-
 website/docs/guides/delegation-patterns.md    |   4 +-
 website/docs/guides/github-pr-review-agent.md |  12 +-
 website/docs/guides/google-gemini.md          |   8 +-
 website/docs/guides/google-vertex.md          |  10 +-
 website/docs/guides/local-llm-on-mac.md       |   2 +-
 website/docs/guides/local-ollama-setup.md     |   4 +-
 .../guides/manage-hermes-cloud-with-mcp.md    |  20 +-
 website/docs/guides/migrate-from-openclaw.md  |   4 +-
 .../guides/operate-teams-meeting-pipeline.md  |   6 +-
 website/docs/guides/pipe-script-output.md     |   6 +-
 .../docs/guides/run-nemotron-3-ultra-free.md  |  10 +-
 .../guides/secure-hermes-on-a-work-machine.md |  26 +-
 .../docs/guides/team-telegram-assistant.md    |  18 +-
 website/docs/guides/tips.md                   |   6 +-
 .../guides/troubleshooting-agent-quality.md   |  10 +-
 website/docs/guides/use-mcp-with-hermes.md    |   6 +-
 website/docs/guides/use-soul-with-hermes.md   |   8 +-
 .../docs/guides/use-voice-mode-with-hermes.md |  14 +-
 .../docs/guides/webhook-github-pr-review.md   |  12 +-
 website/docs/guides/work-with-skills.md       |   6 +-
 website/docs/index.mdx                        |  46 +--
 website/docs/integrations/buzz.md             |   6 +-
 website/docs/integrations/index.md            |  36 +--
 website/docs/integrations/providers.md        |  30 +-
 website/docs/reference/cli-commands.md        |  20 +-
 .../docs/reference/environment-variables.md   |  34 +-
 website/docs/reference/faq.md                 |  14 +-
 .../docs/reference/mcp-config-reference.md    |   6 +-
 .../docs/reference/optional-skills-catalog.md | 298 +++++++++---------
 website/docs/reference/skills-catalog.md      | 118 +++----
 website/docs/reference/tools-reference.md     |   6 +-
 website/docs/user-guide/bot-mode.md           |   2 +-
 website/docs/user-guide/cli.md                |  10 +-
 website/docs/user-guide/configuring-models.md |   6 +-
 website/docs/user-guide/desktop.md            |   4 +-
 website/docs/user-guide/docker.md             |   4 +-
 .../user-guide/egress/network-isolation.md    |   2 +-
 .../docs/user-guide/features/api-server.md    |  16 +-
 .../user-guide/features/batch-processing.md   |   2 +-
 .../user-guide/features/built-in-plugins.md   |   4 +-
 .../user-guide/features/code-execution.md     |   4 +-
 .../features/codex-app-server-runtime.md      |   2 +-
 .../docs/user-guide/features/context-files.md |   2 +-
 .../user-guide/features/credential-pools.md   |   2 +-
 website/docs/user-guide/features/cron.md      |   8 +-
 website/docs/user-guide/features/curator.md   |   8 +-
 .../docs/user-guide/features/delegation.md    |   4 +-
 .../features/extending-the-dashboard.md       |   2 +-
 .../user-guide/features/fallback-providers.md |   6 +-
 website/docs/user-guide/features/goals.md     |   2 +-
 website/docs/user-guide/features/hooks.md     |  16 +-
 website/docs/user-guide/features/kanban.md    |   4 +-
 website/docs/user-guide/features/mcp.md       |  10 +-
 .../user-guide/features/memory-providers.md   |   6 +-
 website/docs/user-guide/features/memory.md    |   8 +-
 website/docs/user-guide/features/overview.md  |   2 +-
 .../docs/user-guide/features/personality.md   |   8 +-
 website/docs/user-guide/features/pets.md      |   2 +-
 .../user-guide/features/plugin-catalog.md     |   2 +-
 website/docs/user-guide/features/plugins.md   |  70 ++--
 .../user-guide/features/provider-routing.md   |   4 +-
 website/docs/user-guide/features/skills.md    |  14 +-
 website/docs/user-guide/features/skins.md     |   2 +-
 website/docs/user-guide/features/tools.md     |   4 +-
 website/docs/user-guide/features/vision.md    |   4 +-
 .../docs/user-guide/features/voice-mode.md    |   8 +-
 website/docs/user-guide/features/wake-word.md |   4 +-
 .../docs/user-guide/features/web-dashboard.md |   6 +-
 website/docs/user-guide/features/x-search.md  |   2 +-
 website/docs/user-guide/local-models.md       |   4 +-
 website/docs/user-guide/messaging/discord.md  |   4 +-
 website/docs/user-guide/messaging/email.md    |   2 +-
 website/docs/user-guide/messaging/index.md    |   8 +-
 .../user-guide/messaging/msgraph-webhook.md   |  10 +-
 website/docs/user-guide/messaging/ntfy.md     |   2 +-
 .../docs/user-guide/messaging/open-webui.md   |   2 +-
 website/docs/user-guide/messaging/relay.md    |   4 +-
 website/docs/user-guide/messaging/simplex.md  |   2 +-
 website/docs/user-guide/messaging/sms.md      |   2 +-
 .../user-guide/messaging/teams-meetings.md    |  12 +-
 website/docs/user-guide/messaging/teams.md    |  10 +-
 website/docs/user-guide/messaging/telegram.md |   2 +-
 website/docs/user-guide/messaging/whatsapp.md |   4 +-
 website/docs/user-guide/messaging/yuanbao.md  |   6 +-
 website/docs/user-guide/profiles.md           |   6 +-
 website/docs/user-guide/secrets/command.md    |   2 +-
 website/docs/user-guide/secrets/index.md      |   2 +-
 website/docs/user-guide/security.md           |   2 +-
 website/docs/user-guide/sessions.md           |   2 +-
 .../skills/bundled/apple/apple-apple-notes.md |   2 +-
 .../autonomous-ai-agents-claude-code.md       |   2 +-
 .../autonomous-ai-agents-codex.md             |   2 +-
 .../autonomous-ai-agents-hermes-agent.md      |   2 +-
 .../autonomous-ai-agents-merge-reconciler.md  |   2 +-
 .../autonomous-ai-agents-opencode.md          |   2 +-
 .../creative/creative-architecture-diagram.md |   2 +-
 .../bundled/creative/creative-ascii-art.md    |   2 +-
 .../creative/creative-claude-design.md        |   2 +-
 .../bundled/creative/creative-comfyui.md      |   2 +-
 .../bundled/creative/creative-design-md.md    |   2 +-
 .../bundled/creative/creative-humanizer.md    |   2 +-
 .../skills/bundled/creative/creative-p5js.md  |   2 +-
 .../bundled/creative/creative-pretext.md      |   2 +-
 .../bundled/creative/creative-sketch.md       |   2 +-
 .../bundled/email/email-email-inbox-triage.md |   2 +-
 .../github/github-codebase-inspection.md      |   2 +-
 .../bundled/github/github-github-auth.md      |   2 +-
 .../github/github-github-code-review.md       |   2 +-
 .../github/github-github-issue-to-pr.md       |   2 +-
 .../bundled/github/github-github-issues.md    |   2 +-
 .../github/github-github-pr-workflow.md       |   2 +-
 .../github/github-github-repo-management.md   |   2 +-
 .../bundled/productivity/productivity-box.md  |   2 +-
 .../productivity-document-to-action-items.md  |   2 +-
 .../bundled/productivity/productivity-docx.md |   2 +-
 .../productivity-google-workspace.md          |   2 +-
 .../productivity-meeting-action-items.md      |   2 +-
 .../productivity/productivity-nano-pdf.md     |   2 +-
 .../productivity-ocr-and-documents.md         |   2 +-
 .../bundled/productivity/productivity-pdf.md  |   2 +-
 .../productivity/productivity-powerpoint.md   |   2 +-
 .../productivity-product-price-monitor.md     |   2 +-
 .../productivity-session-librarian.md         |   2 +-
 .../productivity-weekly-review-planning.md    |   2 +-
 .../bundled/productivity/productivity-xlsx.md |   2 +-
 .../research-blocked-page-recovery.md         |   2 +-
 .../research-competitor-news-monitor.md       |   2 +-
 .../research/research-grounded-citations.md   |   2 +-
 .../bundled/research/research-llm-wiki.md     |   2 +-
 .../research-research-paper-writing.md        |   2 +-
 ...oftware-development-codebase-inspection.md |   2 +-
 .../software-development-github.md            |   2 +-
 ...evelopment-hermes-agent-skill-authoring.md |   2 +-
 ...velopment-inspecting-hermes-desktop-dom.md |   2 +-
 ...tware-development-node-inspect-debugger.md |   2 +-
 .../software-development-python-debugpy.md    |   2 +-
 ...ware-development-requesting-code-review.md |   2 +-
 .../software-development-simplify-code.md     |   2 +-
 .../software-development-spike.md             |   2 +-
 ...ftware-development-systematic-debugging.md |   2 +-
 ...are-development-test-driven-development.md |   2 +-
 .../bundled/web/web-blocked-page-recovery.md  |   2 +-
 .../autonomous-ai-agents-antigravity-cli.md   |   2 +-
 .../autonomous-ai-agents-blackbox.md          |   2 +-
 .../autonomous-ai-agents-dynamic-workflow.md  |   2 +-
 .../autonomous-ai-agents-grok.md              |   2 +-
 .../autonomous-ai-agents-honcho.md            |   2 +-
 .../autonomous-ai-agents-openhands.md         |   2 +-
 .../optional/blockchain/blockchain-evm.md     |   2 +-
 .../creative/creative-ai-presenter-video.md   |   2 +-
 .../optional/creative/creative-archify.md     |   2 +-
 .../optional/creative/creative-ascii-art.md   |   2 +-
 .../creative-audiocraft-audio-generation.md   |   2 +-
 .../optional/creative/creative-auteur.md      |   2 +-
 .../optional/creative/creative-comfyui.md     |   2 +-
 .../creative/creative-concept-diagrams.md     |   2 +-
 .../creative/creative-draw-your-font.md       |   2 +-
 .../optional/creative/creative-dream-loop.md  |   2 +-
 .../optional/creative/creative-heartmula.md   |   2 +-
 .../optional/creative/creative-hyperframes.md |   2 +-
 .../optional/creative/creative-impeccable.md  |   2 +-
 .../optional/creative/creative-ip-as-logo.md  |   2 +-
 .../creative-kanban-video-orchestrator.md     |   2 +-
 .../creative/creative-meme-generation.md      |   2 +-
 .../optional/creative/creative-mono-color.md  |   2 +-
 .../optional/creative/creative-pretext.md     |   2 +-
 .../creative/creative-simple-english.md       |   2 +-
 .../optional/creative/creative-sketch.md      |   2 +-
 .../creative-social-media-content-calendar.md |   2 +-
 .../creative/creative-system-atlas.md         |   2 +-
 .../devops-hermes-s6-container-supervision.md |   2 +-
 .../dogfood/dogfood-adversarial-ux-test.md    |   2 +-
 .../finance/finance-3-statement-model.md      |   2 +-
 .../finance/finance-comps-analysis.md         |   2 +-
 .../optional/finance/finance-dcf-model.md     |   2 +-
 .../optional/finance/finance-excel-author.md  |   2 +-
 .../optional/finance/finance-lbo-model.md     |   2 +-
 .../optional/finance/finance-merger-model.md  |   2 +-
 .../optional/finance/finance-pptx-author.md   |   2 +-
 .../skills/optional/finance/finance-stocks.md |   2 +-
 .../skills/optional/mcp/mcp-fastmcp.md        |   2 +-
 .../mcp/mcp-mcp-oauth-remote-gateway.md       |   2 +-
 .../migration/migration-openclaw-migration.md |   2 +-
 .../optional/mlops/mlops-obliteratus.md       |   2 +-
 .../optional/payments/payments-mpp-agent.md   |   2 +-
 .../payments/payments-stripe-link-cli.md      |   2 +-
 .../payments/payments-stripe-projects.md      |   2 +-
 .../productivity-decision-questionnaire.md    |   2 +-
 .../productivity-live-dashboard.md            |   2 +-
 .../productivity/productivity-shop.md         |   2 +-
 .../productivity/productivity-shopify.md      |   2 +-
 .../productivity/productivity-siyuan.md       |   2 +-
 .../productivity/productivity-telephony.md    |   2 +-
 .../research/research-darwinian-evolver.md    |   2 +-
 .../research/research-duckduckgo-search.md    |   2 +-
 .../research/research-gitnexus-explorer.md    |   2 +-
 .../research/research-osint-investigation.md  |   2 +-
 .../research/research-parallel-cli.md         |   2 +-
 .../skills/optional/research/research-qmd.md  |   2 +-
 .../research-research-paper-writing.md        |   2 +-
 .../optional/research/research-rss-feeds.md   |   2 +-
 .../optional/research/research-scrapling.md   |   2 +-
 .../research/research-searxng-search.md       |   2 +-
 .../optional/security/security-godmode.md     |   2 +-
 .../optional/security/security-unbroker.md    |   2 +-
 .../social-media-reddit-reading.md            |   2 +-
 .../software-development-ast-grep.md          |   2 +-
 .../software-development-code-wiki.md         |   2 +-
 .../software-development-grill-me.md          |   2 +-
 ...software-development-rest-graphql-debug.md |   2 +-
 ...development-subagent-driven-development.md |   2 +-
 website/docs/user-guide/tui.md                |   2 +-
 .../docs/user-guide/which-file-does-what.md   |  20 +-
 website/docs/user-guide/windows-native.md     |   4 +-
 .../docs/user-guide/windows-wsl-quickstart.md |  24 +-
 .../developer-guide/adding-providers.md       |   2 +-
 .../current/developer-guide/adding-tools.md   |   4 +-
 .../current/developer-guide/architecture.md   |   2 +-
 .../context-compression-and-caching.md        |   2 +-
 .../developer-guide/context-engine-plugin.md  |   6 +-
 .../developer-guide/creating-skills.md        |   2 +-
 .../current/developer-guide/cron-internals.md |   2 +-
 .../developer-guide/gateway-internals.md      |   4 +-
 .../image-gen-provider-plugin.md              |  10 +-
 .../developer-guide/memory-provider-plugin.md |   2 +-
 .../developer-guide/model-provider-plugin.md  |  14 +-
 .../developer-guide/plugin-llm-access.md      |   2 +-
 .../current/developer-guide/plugins/index.md  |  80 ++---
 .../video-gen-provider-plugin.md              |   2 +-
 .../web-search-provider-plugin.md             |  14 +-
 .../current/getting-started/installation.md   |   2 +-
 .../current/getting-started/learning-path.md  | 128 ++++----
 .../current/getting-started/quickstart.md     |   2 +-
 .../current/guides/automate-with-cron.md      |  10 +-
 .../current/guides/automation-blueprints.md   |   4 +-
 .../current/guides/azure-foundry.md           |   6 +-
 .../current/guides/cron-script-only.md        |  12 +-
 .../current/guides/cron-troubleshooting.md    |   2 +-
 .../current/guides/daily-briefing-bot.md      |  18 +-
 .../current/guides/delegation-patterns.md     |   4 +-
 .../current/guides/github-pr-review-agent.md  |  12 +-
 .../current/guides/google-gemini.md           |   8 +-
 .../current/guides/migrate-from-openclaw.md   |   2 +-
 .../guides/operate-teams-meeting-pipeline.md  |   6 +-
 .../current/guides/pipe-script-output.md      |   6 +-
 .../current/guides/team-telegram-assistant.md |  18 +-
 .../current/guides/tips.md                    |   2 +-
 .../current/guides/use-mcp-with-hermes.md     |   6 +-
 .../current/guides/use-soul-with-hermes.md    |   8 +-
 .../guides/use-voice-mode-with-hermes.md      |  12 +-
 .../guides/webhook-github-pr-review.md        |  10 +-
 .../current/guides/work-with-skills.md        |   6 +-
 .../current/index.mdx                         |  40 +--
 .../current/integrations/buzz.md              |   6 +-
 .../current/integrations/index.md             |  32 +-
 .../current/integrations/providers.md         |  24 +-
 .../current/reference/cli-commands.md         |  14 +-
 .../reference/environment-variables.md        |  20 +-
 .../current/reference/faq.md                  |   6 +-
 .../current/reference/mcp-config-reference.md |   4 +-
 .../current/reference/slash-commands.md       |  24 +-
 .../current/reference/tools-reference.md      |   6 +-
 .../current/user-guide/bot-mode.md            |   2 +-
 .../current/user-guide/cli.md                 |   4 +-
 .../current/user-guide/configuration.md       |  40 +--
 .../current/user-guide/configuring-models.md  |   4 +-
 .../current/user-guide/docker.md              |   2 +-
 .../current/user-guide/features/api-server.md |  14 +-
 .../user-guide/features/batch-processing.md   |   2 +-
 .../user-guide/features/built-in-plugins.md   |   4 +-
 .../user-guide/features/code-execution.md     |   4 +-
 .../user-guide/features/context-files.md      |   2 +-
 .../current/user-guide/features/cron.md       |   6 +-
 .../current/user-guide/features/curator.md    |   8 +-
 .../current/user-guide/features/delegation.md |   2 +-
 .../user-guide/features/fallback-providers.md |   6 +-
 .../current/user-guide/features/goals.md      |   2 +-
 .../current/user-guide/features/hooks.md      |   6 +-
 .../current/user-guide/features/kanban.md     |   2 +-
 .../current/user-guide/features/mcp.md        |   8 +-
 .../user-guide/features/memory-providers.md   |   4 +-
 .../current/user-guide/features/memory.md     |   2 +-
 .../user-guide/features/personality.md        |   8 +-
 .../current/user-guide/features/plugins.md    |  62 ++--
 .../user-guide/features/provider-routing.md   |   2 +-
 .../current/user-guide/features/skills.md     |   8 +-
 .../current/user-guide/features/skins.md      |   2 +-
 .../current/user-guide/features/tools.md      |   4 +-
 .../current/user-guide/features/vision.md     |   2 +-
 .../current/user-guide/features/voice-mode.md |   6 +-
 .../current/user-guide/messaging/discord.md   |   4 +-
 .../current/user-guide/messaging/index.md     |   4 +-
 .../user-guide/messaging/msgraph-webhook.md   |  10 +-
 .../user-guide/messaging/open-webui.md        |   2 +-
 .../current/user-guide/messaging/sms.md       |   2 +-
 .../user-guide/messaging/teams-meetings.md    |  12 +-
 .../current/user-guide/messaging/teams.md     |  10 +-
 .../current/user-guide/messaging/telegram.md  |   2 +-
 .../current/user-guide/messaging/whatsapp.md  |   4 +-
 .../current/user-guide/messaging/yuanbao.md   |   6 +-
 .../current/user-guide/profiles.md            |   2 +-
 .../current/user-guide/security.md            |   2 +-
 .../current/user-guide/sessions.md            |   2 +-
 .../current/user-guide/windows-native.md      |   4 +-
 .../user-guide/windows-wsl-quickstart.md      |  24 +-
 335 files changed, 1379 insertions(+), 1379 deletions(-)

diff --git a/website/docs/developer-guide/adding-providers.md b/website/docs/developer-guide/adding-providers.md
index ba8e276bd5..105081d33d 100644
--- a/website/docs/developer-guide/adding-providers.md
+++ b/website/docs/developer-guide/adding-providers.md
@@ -126,7 +126,7 @@ When you add a plugin and it calls `register_provider()`, the following wire up
 
 User plugins at `$HERMES_HOME/plugins/model-providers/<name>/` override bundled plugins of the same name (last-writer-wins in `register_provider()`) — so third parties can monkey-patch or replace any built-in profile without editing the repo.
 
-See `plugins/model-providers/nvidia/` or `plugins/model-providers/gmi/` as a template, and the full [Model Provider Plugin guide](/developer-guide/model-provider-plugin) for field reference, hook idioms, and end-to-end examples.
+See `plugins/model-providers/nvidia/` or `plugins/model-providers/gmi/` as a template, and the full [Model Provider Plugin guide](./model-provider-plugin.md) for field reference, hook idioms, and end-to-end examples.
 
 ## Full path: OAuth and complex providers
 
diff --git a/website/docs/developer-guide/adding-tools.md b/website/docs/developer-guide/adding-tools.md
index 2219d73801..13bf774f2a 100644
--- a/website/docs/developer-guide/adding-tools.md
+++ b/website/docs/developer-guide/adding-tools.md
@@ -13,8 +13,8 @@ This page is for adding a **built-in Hermes tool** to the repository itself.
 If you want a personal, project-local, or otherwise custom tool without
 modifying Hermes core, use the plugin route instead:
 
-- [Plugins](/user-guide/features/plugins)
-- [Build a Hermes Plugin](/developer-guide/plugins)
+- [Plugins](../user-guide/features/plugins.md)
+- [Build a Hermes Plugin](./plugins/index.md)
 
 Default to plugins for most custom tool creation. Only follow this page when
 you explicitly want to ship a new built-in tool in `tools/` and `toolsets.py`.
diff --git a/website/docs/developer-guide/architecture.md b/website/docs/developer-guide/architecture.md
index 8b826980e7..85fc06e391 100644
--- a/website/docs/developer-guide/architecture.md
+++ b/website/docs/developer-guide/architecture.md
@@ -233,7 +233,7 @@ Long-running process with 25+ platform adapters (built-in + bundled plugins), un
 
 Three discovery sources: `~/.hermes/plugins/` (user), `.hermes/plugins/` (project), and pip entry points. Plugins register tools, hooks, and CLI commands through a context API. Two specialized plugin types exist: memory providers (`plugins/memory/`) and context engines (`plugins/context_engine/`). Both are single-select — only one of each can be active at a time, configured via `hermes plugins` or `config.yaml`.
 
-→ [Plugin Guide](/developer-guide/plugins), [Memory Provider Plugin](./memory-provider-plugin.md)
+→ [Plugin Guide](./plugins/index.md), [Memory Provider Plugin](./memory-provider-plugin.md)
 
 ### Cron
 
diff --git a/website/docs/developer-guide/browser-provider-plugin.md b/website/docs/developer-guide/browser-provider-plugin.md
index 0f71b1684f..465e43e61f 100644
--- a/website/docs/developer-guide/browser-provider-plugin.md
+++ b/website/docs/developer-guide/browser-provider-plugin.md
@@ -9,7 +9,7 @@ description: "How to build a cloud browser backend plugin for Hermes Agent"
 Browser provider plugins register a **cloud browser backend** that services cloud-mode `browser_*` tool calls (navigate, click, screenshot, …). Built-in providers — Browserbase, Browser Use, and Firecrawl — all ship as plugins under `plugins/browser/<name>/`. You can add a new one, or override a bundled one, by dropping a directory next to them.
 
 :::tip
-Browser backends are one of several **backend plugins** Hermes supports. The others (with their own ABCs) are [Web Search Provider Plugins](/developer-guide/web-search-provider-plugin) (which this ABC deliberately mirrors), [Image Generation](/developer-guide/image-gen-provider-plugin), [Video Generation](/developer-guide/video-gen-provider-plugin), [Memory Providers](/developer-guide/memory-provider-plugin), [Context Engines](/developer-guide/context-engine-plugin), [Secret Sources](/developer-guide/secret-source-plugin), and [Model Providers](/developer-guide/model-provider-plugin). General tool/hook/CLI plugins live in [Build a Hermes Plugin](/developer-guide/plugins).
+Browser backends are one of several **backend plugins** Hermes supports. The others (with their own ABCs) are [Web Search Provider Plugins](./web-search-provider-plugin.md) (which this ABC deliberately mirrors), [Image Generation](./image-gen-provider-plugin.md), [Video Generation](./video-gen-provider-plugin.md), [Memory Providers](./memory-provider-plugin.md), [Context Engines](./context-engine-plugin.md), [Secret Sources](./secret-source-plugin.md), and [Model Providers](./model-provider-plugin.md). General tool/hook/CLI plugins live in [Build a Hermes Plugin](./plugins/index.md).
 :::
 
 ## How it fits together
diff --git a/website/docs/developer-guide/context-compression-and-caching.md b/website/docs/developer-guide/context-compression-and-caching.md
index 7b395cab68..193d06a9f4 100644
--- a/website/docs/developer-guide/context-compression-and-caching.md
+++ b/website/docs/developer-guide/context-compression-and-caching.md
@@ -61,7 +61,7 @@ Plugin engines are **never auto-activated** — the user must explicitly set `co
 
 Configure via `hermes plugins` → Provider Plugins → Context Engine, or edit `config.yaml` directly.
 
-For building a context engine plugin, see [Context Engine Plugins](/developer-guide/context-engine-plugin).
+For building a context engine plugin, see [Context Engine Plugins](./context-engine-plugin.md).
 
 ## Dual Compression System
 
diff --git a/website/docs/developer-guide/context-engine-plugin.md b/website/docs/developer-guide/context-engine-plugin.md
index 6d33638ddb..0768f6ef45 100644
--- a/website/docs/developer-guide/context-engine-plugin.md
+++ b/website/docs/developer-guide/context-engine-plugin.md
@@ -267,6 +267,6 @@ Your engine must therefore assume:
 
 ## See also
 
-- [Context Compression and Caching](/developer-guide/context-compression-and-caching) — how the built-in compressor works
-- [Memory Provider Plugins](/developer-guide/memory-provider-plugin) — analogous single-select plugin system for memory
-- [Plugins](/user-guide/features/plugins) — general plugin system overview
+- [Context Compression and Caching](./context-compression-and-caching.md) — how the built-in compressor works
+- [Memory Provider Plugins](./memory-provider-plugin.md) — analogous single-select plugin system for memory
+- [Plugins](../user-guide/features/plugins.md) — general plugin system overview
diff --git a/website/docs/developer-guide/creating-skills.md b/website/docs/developer-guide/creating-skills.md
index 25d023ed57..6533ae6b8b 100644
--- a/website/docs/developer-guide/creating-skills.md
+++ b/website/docs/developer-guide/creating-skills.md
@@ -178,7 +178,7 @@ required_environment_variables:
 The user can skip setup and keep loading the skill. Hermes never exposes the raw secret value to the model. Gateway and messaging sessions show local setup guidance instead of collecting secrets in-band.
 
 :::tip Sandbox Passthrough
-When your skill is loaded, any declared `required_environment_variables` that are set are **automatically passed through** to `execute_code` and `terminal` sandboxes — including remote backends like Docker and Modal. Your skill's scripts can access `$TENOR_API_KEY` (or `os.environ["TENOR_API_KEY"]` in Python) without the user needing to configure anything extra. See [Environment Variable Passthrough](/user-guide/security#environment-variable-passthrough) for details.
+When your skill is loaded, any declared `required_environment_variables` that are set are **automatically passed through** to `execute_code` and `terminal` sandboxes — including remote backends like Docker and Modal. Your skill's scripts can access `$TENOR_API_KEY` (or `os.environ["TENOR_API_KEY"]` in Python) without the user needing to configure anything extra. See [Environment Variable Passthrough](../user-guide/security.md#environment-variable-passthrough) for details.
 :::
 
 Legacy `prerequisites.env_vars` remains supported as a backward-compatible alias.
diff --git a/website/docs/developer-guide/cron-internals.md b/website/docs/developer-guide/cron-internals.md
index 9f32478013..08db620c00 100644
--- a/website/docs/developer-guide/cron-internals.md
+++ b/website/docs/developer-guide/cron-internals.md
@@ -391,6 +391,6 @@ hermes cron remove <job_id>         # Delete a job
 
 ## Related Docs
 
-- [Cron Feature Guide](/user-guide/features/cron)
+- [Cron Feature Guide](../user-guide/features/cron.md)
 - [Gateway Internals](./gateway-internals.md)
 - [Agent Loop Internals](./agent-loop.md)
diff --git a/website/docs/developer-guide/desktop-plugin-sdk.md b/website/docs/developer-guide/desktop-plugin-sdk.md
index bb98069657..45b3308ce0 100644
--- a/website/docs/developer-guide/desktop-plugin-sdk.md
+++ b/website/docs/developer-guide/desktop-plugin-sdk.md
@@ -6,7 +6,7 @@ description: "Extend the native Hermes Desktop app — panes, pages, sidebar nav
 
 # Desktop Plugin SDK
 
-The native [Hermes Desktop](/user-guide/desktop) app is contribution-driven: every
+The native [Hermes Desktop](../user-guide/desktop.md) app is contribution-driven: every
 surface in the window — panes, routes, sidebar nav, status-bar items, palette
 entries, keybinds, themes — registers into one central registry. Core registers
 its surfaces exactly the way a plugin does, so the plugin story is the real one,
@@ -26,8 +26,8 @@ desktop app** (`hermes desktop`) SDK — the `@hermes/plugin-sdk` module and
 `$HERMES_HOME/desktop-plugins/`. The **web dashboard** (`hermes dashboard`) has
 its own, unrelated plugin system on `window.__HERMES_PLUGIN_SDK__` with a
 `manifest.json` — documented at
-[Extending the Dashboard](/user-guide/features/extending-the-dashboard). Python
-CLI/gateway plugins are documented at [Build a Hermes Plugin](/developer-guide/plugins).
+[Extending the Dashboard](../user-guide/features/extending-the-dashboard.md). Python
+CLI/gateway plugins are documented at [Build a Hermes Plugin](./plugins/index.md).
 The three do not share code, APIs, or delivery. Only the backend `plugin_api.py`
 namespace (`/api/plugins/<id>`) is shared between the desktop and dashboard SDKs.
 :::
@@ -781,7 +781,7 @@ The user gets a confirmation dialog (repo id, source links, a probe of what
 the repo ships) and picks components before anything is installed — deep links
 never auto-install. `force=1` replaces an existing install; dev builds use
 `hermes-dev://`. Full link reference:
-[One-click install links](/user-guide/features/plugins#one-click-install-links-desktop).
+[One-click install links](../user-guide/features/plugins.md#one-click-install-links-desktop).
 
 ### The Python side
 
@@ -814,7 +814,7 @@ async def action(body: dict):
 Routes mount under `/api/plugins/<id>/` (`GET /api/plugins/<id>/board`, …).
 Backend code runs inside the gateway process, so it can import from the
 hermes-agent codebase directly (`hermes_state`, `hermes_cli.config`, …). See
-[Extending the Dashboard → Backend API routes](/user-guide/features/extending-the-dashboard#backend-api-routes)
+[Extending the Dashboard → Backend API routes](../user-guide/features/extending-the-dashboard.md#backend-api-routes)
 for the full backend reference — the mount is identical.
 
 :::caution The Python backend is gated separately
diff --git a/website/docs/developer-guide/gateway-internals.md b/website/docs/developer-guide/gateway-internals.md
index 11d98af4e6..078de91b7d 100644
--- a/website/docs/developer-guide/gateway-internals.md
+++ b/website/docs/developer-guide/gateway-internals.md
@@ -207,7 +207,7 @@ Outgoing deliveries (`gateway/delivery.py`) handle:
 
 - **Direct reply** — send response back to the originating chat
 - **Home channel delivery** — route cron job outputs and background results to a configured home channel
-- **Explicit target delivery** — the send engine specifying `telegram:-1001234567890`, exposed via the [`hermes send` CLI](/guides/pipe-script-output) for shell scripts and via cron `deliver:` targets
+- **Explicit target delivery** — the send engine specifying `telegram:-1001234567890`, exposed via the [`hermes send` CLI](../guides/pipe-script-output.md) for shell scripts and via cron `deliver:` targets
 - **Cross-platform delivery** — deliver to a different platform than the originating message
 
 Cron job deliveries are NOT mirrored into gateway session history — they live in their own cron session only. This is a deliberate design choice to avoid message alternation violations.
@@ -286,7 +286,7 @@ With `gateway.multiplex_profiles: true` one process serves the default profile p
 | Child processes (`hermes -p X` workers, relay turns, browser drivers) | `tools/environments/local.py::served_profile_child_env` |
 | Background threads | `agent/memory_provider.py::spawn_context_thread` |
 
-Secret reads fail closed (`agent.secret_scope.get_secret` raises `UnscopedSecretError`) only after `set_multiplex_active(True)`, which the gateway, cron, `gateway migrate` and the Desktop/dashboard `serve` backend set. Adapter YAML never reaches `os.environ` under multiplex: `gateway/platforms/_shared.py::apply_yaml_bridge` seeds `PlatformConfig.extra` and skips the environ write under a secondary's scope; gates read through `platform_gate_env`. Shared-ingress platforms (WhatsApp bridge, Relay) run on the default profile only; a secondary that enables one is logged once and stamped into runtime status (`run_adapters.py::_note_unserved_secondary_platform`). Per-profile isolation as the user sees it: [Multi-profile gateways § What is isolated per profile](/user-guide/multi-profile-gateways#what-is-isolated-per-profile).
+Secret reads fail closed (`agent.secret_scope.get_secret` raises `UnscopedSecretError`) only after `set_multiplex_active(True)`, which the gateway, cron, `gateway migrate` and the Desktop/dashboard `serve` backend set. Adapter YAML never reaches `os.environ` under multiplex: `gateway/platforms/_shared.py::apply_yaml_bridge` seeds `PlatformConfig.extra` and skips the environ write under a secondary's scope; gates read through `platform_gate_env`. Shared-ingress platforms (WhatsApp bridge, Relay) run on the default profile only; a secondary that enables one is logged once and stamped into runtime status (`run_adapters.py::_note_unserved_secondary_platform`). Per-profile isolation as the user sees it: [Multi-profile gateways § What is isolated per profile](../user-guide/multi-profile-gateways.md#what-is-isolated-per-profile).
 
 ## Related Docs
 
@@ -294,4 +294,4 @@ Secret reads fail closed (`agent.secret_scope.get_secret` raises `UnscopedSecret
 - [Cron Internals](./cron-internals.md)
 - [ACP Internals](./acp-internals.md)
 - [Agent Loop Internals](./agent-loop.md)
-- [Messaging Gateway (User Guide)](/user-guide/messaging)
+- [Messaging Gateway (User Guide)](../user-guide/messaging/index.md)
diff --git a/website/docs/developer-guide/image-gen-provider-plugin.md b/website/docs/developer-guide/image-gen-provider-plugin.md
index ea4dc70516..41ae4fb38b 100644
--- a/website/docs/developer-guide/image-gen-provider-plugin.md
+++ b/website/docs/developer-guide/image-gen-provider-plugin.md
@@ -9,7 +9,7 @@ description: "How to build an image-generation backend plugin for Hermes Agent"
 Image-gen provider plugins register a backend that services every `image_generate` tool call — DALL·E, gpt-image, Grok, Flux, Imagen, Stable Diffusion, fal, Replicate, a local ComfyUI rig, anything. Built-in providers (OpenAI, OpenAI-Codex, xAI, FAL, Krea, DeepInfra, OpenRouter, Meta Model API) all ship as plugins. You can add a new one, or override a bundled one, by dropping a directory into `plugins/image_gen/<name>/`.
 
 :::tip
-Image-gen is one of several **backend plugins** Hermes supports. The others (with more specialized ABCs) are [Memory Provider Plugins](/developer-guide/memory-provider-plugin), [Context Engine Plugins](/developer-guide/context-engine-plugin), and [Model Provider Plugins](/developer-guide/model-provider-plugin). General tool/hook/CLI plugins live in [Build a Hermes Plugin](/developer-guide/plugins).
+Image-gen is one of several **backend plugins** Hermes supports. The others (with more specialized ABCs) are [Memory Provider Plugins](./memory-provider-plugin.md), [Context Engine Plugins](./context-engine-plugin.md), and [Model Provider Plugins](./model-provider-plugin.md). General tool/hook/CLI plugins live in [Build a Hermes Plugin](./plugins/index.md).
 :::
 
 ## How discovery works
@@ -307,10 +307,10 @@ Or interactively: `hermes tools` → "Image Generation" → select `my-backend`
 my-backend-imggen = "my_backend_imggen_package"
 ```
 
-`my_backend_imggen_package` must expose a top-level `register` function. See [Distribute via pip](/developer-guide/plugins#distribute-via-pip) in the general plugin guide for the full setup.
+`my_backend_imggen_package` must expose a top-level `register` function. See [Distribute via pip](./plugins/index.md#distribute-via-pip) in the general plugin guide for the full setup.
 
 ## Related pages
 
-- [Image Generation](/user-guide/features/image-generation) — user-facing feature documentation
-- [Plugins overview](/user-guide/features/plugins) — all plugin types at a glance
-- [Build a Hermes Plugin](/developer-guide/plugins) — general tools/hooks/slash commands guide
+- [Image Generation](../user-guide/features/image-generation.md) — user-facing feature documentation
+- [Plugins overview](../user-guide/features/plugins.md) — all plugin types at a glance
+- [Build a Hermes Plugin](./plugins/index.md) — general tools/hooks/slash commands guide
diff --git a/website/docs/developer-guide/memory-provider-plugin.md b/website/docs/developer-guide/memory-provider-plugin.md
index 7b4610406e..d4ca52f5b9 100644
--- a/website/docs/developer-guide/memory-provider-plugin.md
+++ b/website/docs/developer-guide/memory-provider-plugin.md
@@ -9,7 +9,7 @@ description: "How to build a memory provider plugin for Hermes Agent"
 Memory provider plugins give Hermes Agent persistent, cross-session knowledge beyond the built-in MEMORY.md and USER.md. This guide covers how to build one.
 
 :::tip
-Memory providers are one of two **provider plugin** types. The other is [Context Engine Plugins](/developer-guide/context-engine-plugin), which replace the built-in context compressor. Both follow the same pattern: single-select, config-driven, managed via `hermes plugins`.
+Memory providers are one of two **provider plugin** types. The other is [Context Engine Plugins](./context-engine-plugin.md), which replace the built-in context compressor. Both follow the same pattern: single-select, config-driven, managed via `hermes plugins`.
 :::
 
 ## Installation Layouts
@@ -172,7 +172,7 @@ The preview includes the path so the agent can read the full result when it is
 actually needed. Results at or below the threshold are returned unchanged.
 
 This uses the shared `hooks.output_spill` settings (`10,000` characters by
-default); see [Plugins — oversized-context spill](/developer-guide/plugins/#oversized-context-spill).
+default); see [Plugins — oversized-context spill](./plugins/index.md#oversized-context-spill).
 
 ## Pre-Compress Checkpoints (fail-closed)
 
diff --git a/website/docs/developer-guide/model-provider-plugin.md b/website/docs/developer-guide/model-provider-plugin.md
index 3b97c05798..fed6b37c54 100644
--- a/website/docs/developer-guide/model-provider-plugin.md
+++ b/website/docs/developer-guide/model-provider-plugin.md
@@ -9,7 +9,7 @@ description: "How to build a model provider (inference backend) plugin for Herme
 Model provider plugins declare an inference backend — an OpenAI-compatible endpoint, an Anthropic Messages server, a Codex-style Responses API, or a Bedrock-native surface — that Hermes can route `AIAgent` calls through. Every built-in provider (OpenRouter, Anthropic, GMI, DeepSeek, Nvidia, …) ships as one of these plugins. Third parties can add their own by dropping a directory under `$HERMES_HOME/plugins/model-providers/` with zero changes to the repo.
 
 :::tip
-Model provider plugins are the third kind of **provider plugin**. The others are [Memory Provider Plugins](/developer-guide/memory-provider-plugin) (cross-session knowledge) and [Context Engine Plugins](/developer-guide/context-engine-plugin) (context compression strategies). All three follow the same "drop a directory, declare a profile, no repo edits" pattern.
+Model provider plugins are the third kind of **provider plugin**. The others are [Memory Provider Plugins](./memory-provider-plugin.md) (cross-session knowledge) and [Context Engine Plugins](./context-engine-plugin.md) (context compression strategies). All three follow the same "drop a directory, declare a profile, no repo edits" pattern.
 :::
 
 ## How discovery works
@@ -317,12 +317,12 @@ skipped by the provider scan — they belong to the `PluginManager`. A broken
 entry point is isolated — it is logged at warning level and skipped, and never
 blocks discovery of the other providers.
 
-See [Building a Hermes Plugin](/developer-guide/plugins#distribute-via-pip) for the full entry-points setup.
+See [Building a Hermes Plugin](./plugins/index.md#distribute-via-pip) for the full entry-points setup.
 
 ## Related pages
 
-- [Provider Runtime](/developer-guide/provider-runtime) — resolution precedence + where each layer reads the profile
-- [Adding Providers](/developer-guide/adding-providers) — end-to-end checklist for new inference backends (covers both the fast plugin path and the full CLI/auth integration)
-- [Memory Provider Plugins](/developer-guide/memory-provider-plugin)
-- [Context Engine Plugins](/developer-guide/context-engine-plugin)
-- [Building a Hermes Plugin](/developer-guide/plugins) — general plugin authoring
+- [Provider Runtime](./provider-runtime.md) — resolution precedence + where each layer reads the profile
+- [Adding Providers](./adding-providers.md) — end-to-end checklist for new inference backends (covers both the fast plugin path and the full CLI/auth integration)
+- [Memory Provider Plugins](./memory-provider-plugin.md)
+- [Context Engine Plugins](./context-engine-plugin.md)
+- [Building a Hermes Plugin](./plugins/index.md) — general plugin authoring
diff --git a/website/docs/developer-guide/plugin-llm-access.md b/website/docs/developer-guide/plugin-llm-access.md
index f6eeee09cd..5cb0f9e08c 100644
--- a/website/docs/developer-guide/plugin-llm-access.md
+++ b/website/docs/developer-guide/plugin-llm-access.md
@@ -503,4 +503,4 @@ own model call — for any reason, structured or not — `ctx.llm`.
   * [`plugin-llm-example`](https://github.com/NousResearch/hermes-example-plugins/tree/main/plugin-llm-example) — sync structured extraction with image input
   * [`plugin-llm-async-example`](https://github.com/NousResearch/hermes-example-plugins/tree/main/plugin-llm-async-example) — async with `asyncio.gather()`
 * Auxiliary client (the engine under the hood): see
-  [Provider Runtime](/developer-guide/provider-runtime).
+  [Provider Runtime](./provider-runtime.md).
diff --git a/website/docs/developer-guide/plugins/index.md b/website/docs/developer-guide/plugins/index.md
index 88dbbc325f..0e4d6fa8d3 100644
--- a/website/docs/developer-guide/plugins/index.md
+++ b/website/docs/developer-guide/plugins/index.md
@@ -15,27 +15,27 @@ Hermes has several distinct pluggable interfaces — some use Python `register_*
 | If you want to add… | Read |
 |---|---|
 | Custom tools, hooks, slash commands, skills, or CLI subcommands | **This guide** (the general plugin surface) |
-| A **native desktop app** extension (panes, pages, status bar, palette, themes) | [Desktop Plugin SDK](/developer-guide/desktop-plugin-sdk) |
-| A **web dashboard** extension (tabs, shell slots, themes) | [Extending the Dashboard](/user-guide/features/extending-the-dashboard) |
-| An **LLM / inference backend** (new provider) | [Model Provider Plugins](/developer-guide/model-provider-plugin) |
-| A **gateway channel** (Discord/Telegram/IRC/Teams/etc.) | [Adding Platform Adapters](/developer-guide/adding-platform-adapters) |
-| A **memory backend** (Honcho/Mem0/Supermemory/etc.) | [Memory Provider Plugins](/developer-guide/memory-provider-plugin) |
-| A **context-compression engine** | [Context Engine Plugins](/developer-guide/context-engine-plugin) |
-| An **image-generation backend** | [Image Generation Provider Plugins](/developer-guide/image-gen-provider-plugin) |
-| A **video-generation backend** | [Video Generation Provider Plugins](/developer-guide/video-gen-provider-plugin) |
-| A **web-search / extract backend** | [Web Search Provider Plugins](/developer-guide/web-search-provider-plugin) |
-| A **cloud browser backend** (Browserbase-style CDP session provider) | [Browser Provider Plugins](/developer-guide/browser-provider-plugin) |
-| A **secret-manager backend** (vault / password manager / OS keystore) | [Secret Source Plugins](/developer-guide/secret-source-plugin) |
-| A **dashboard OIDC/auth provider** | [Web Dashboard — custom providers](/user-guide/features/web-dashboard#custom-providers) — `ctx.register_dashboard_auth_provider()` |
-| A **TTS backend** (any CLI — Piper, VoxCPM, Kokoro, voice cloning, …) | [TTS custom command providers](/user-guide/features/tts#custom-command-providers) — config-driven, no Python needed |
-| An **STT backend** (custom whisper / ASR CLI) | [Voice Message Transcription](/user-guide/features/tts#voice-message-transcription-stt) — set `HERMES_LOCAL_STT_COMMAND` to an argv-tokenized template |
-| **External tools via MCP** (filesystem, GitHub, Linear, any MCP server) | [MCP](/user-guide/features/mcp) — declare `mcp_servers.<name>` in `config.yaml` |
-| **Gateway event hooks** (fire on startup, session events, commands) | [Event Hooks](/user-guide/features/hooks#gateway-event-hooks) — drop `HOOK.yaml` + `handler.py` into `~/.hermes/hooks/<name>/` |
-| **Shell hooks** (run a shell command on events) | [Shell Hooks](/user-guide/features/hooks#shell-hooks) — declare under `hooks:` in `config.yaml` |
-| **Additional skill sources** (custom GitHub repos, private skill indexes) | [Skills](/user-guide/features/skills) — `hermes skills tap add <repo>` · [Publishing a tap](/user-guide/features/skills#publishing-a-custom-skill-tap) |
-| A first-class **core** inference provider (not a plugin) | [Adding Providers](/developer-guide/adding-providers) |
+| A **native desktop app** extension (panes, pages, status bar, palette, themes) | [Desktop Plugin SDK](../desktop-plugin-sdk.md) |
+| A **web dashboard** extension (tabs, shell slots, themes) | [Extending the Dashboard](../../user-guide/features/extending-the-dashboard.md) |
+| An **LLM / inference backend** (new provider) | [Model Provider Plugins](../model-provider-plugin.md) |
+| A **gateway channel** (Discord/Telegram/IRC/Teams/etc.) | [Adding Platform Adapters](../adding-platform-adapters.md) |
+| A **memory backend** (Honcho/Mem0/Supermemory/etc.) | [Memory Provider Plugins](../memory-provider-plugin.md) |
+| A **context-compression engine** | [Context Engine Plugins](../context-engine-plugin.md) |
+| An **image-generation backend** | [Image Generation Provider Plugins](../image-gen-provider-plugin.md) |
+| A **video-generation backend** | [Video Generation Provider Plugins](../video-gen-provider-plugin.md) |
+| A **web-search / extract backend** | [Web Search Provider Plugins](../web-search-provider-plugin.md) |
+| A **cloud browser backend** (Browserbase-style CDP session provider) | [Browser Provider Plugins](../browser-provider-plugin.md) |
+| A **secret-manager backend** (vault / password manager / OS keystore) | [Secret Source Plugins](../secret-source-plugin.md) |
+| A **dashboard OIDC/auth provider** | [Web Dashboard — custom providers](../../user-guide/features/web-dashboard.md#custom-providers) — `ctx.register_dashboard_auth_provider()` |
+| A **TTS backend** (any CLI — Piper, VoxCPM, Kokoro, voice cloning, …) | [TTS custom command providers](../../user-guide/features/tts.md#custom-command-providers) — config-driven, no Python needed |
+| An **STT backend** (custom whisper / ASR CLI) | [Voice Message Transcription](../../user-guide/features/tts.md#voice-message-transcription-stt) — set `HERMES_LOCAL_STT_COMMAND` to an argv-tokenized template |
+| **External tools via MCP** (filesystem, GitHub, Linear, any MCP server) | [MCP](../../user-guide/features/mcp.md) — declare `mcp_servers.<name>` in `config.yaml` |
+| **Gateway event hooks** (fire on startup, session events, commands) | [Event Hooks](../../user-guide/features/hooks.md#gateway-event-hooks) — drop `HOOK.yaml` + `handler.py` into `~/.hermes/hooks/<name>/` |
+| **Shell hooks** (run a shell command on events) | [Shell Hooks](../../user-guide/features/hooks.md#shell-hooks) — declare under `hooks:` in `config.yaml` |
+| **Additional skill sources** (custom GitHub repos, private skill indexes) | [Skills](../../user-guide/features/skills.md) — `hermes skills tap add <repo>` · [Publishing a tap](../../user-guide/features/skills.md#publishing-a-custom-skill-tap) |
+| A first-class **core** inference provider (not a plugin) | [Adding Providers](../adding-providers.md) |
 
-See the full [Pluggable interfaces table](/user-guide/features/plugins#pluggable-interfaces--where-to-go-for-each) for a consolidated view of every extension surface including config-driven (TTS, STT, MCP, shell hooks) and drop-in directory (gateway hooks) styles.
+See the full [Pluggable interfaces table](../../user-guide/features/plugins.md#pluggable-interfaces--where-to-go-for-each) for a consolidated view of every extension surface including config-driven (TTS, STT, MCP, shell hooks) and drop-in directory (gateway hooks) styles.
 :::
 
 :::caution Third-party-product plugins ship standalone — not into the core tree
@@ -973,22 +973,22 @@ def register(ctx):
 
 ### Hook reference
 
-Each hook is documented in full on the **[Event Hooks reference](/user-guide/features/hooks#plugin-hooks)** — callback signatures, parameter tables, exactly when each fires, and examples. Here's the summary:
+Each hook is documented in full on the **[Event Hooks reference](../../user-guide/features/hooks.md#plugin-hooks)** — callback signatures, parameter tables, exactly when each fires, and examples. Here's the summary:
 
 | Hook | Fires when | Callback signature | Returns |
 |------|-----------|-------------------|---------|
-| [`pre_tool_call`](/user-guide/features/hooks#pre_tool_call) | Before any tool executes | `tool_name: str, args: dict, task_id: str` | optional directive: `{"action": "block", "message": ...}` vetoes the call; `{"action": "approve", "message": ...}` escalates to the human-approval gate |
-| [`post_tool_call`](/user-guide/features/hooks#post_tool_call) | After any tool returns | `tool_name: str, args: dict, result: str, task_id: str, duration_ms: int` | ignored |
-| [`pre_llm_call`](/user-guide/features/hooks#pre_llm_call) | Once per turn, before the tool-calling loop | `session_id: str, user_message: str, conversation_history: list, is_first_turn: bool, model: str, platform: str` | [context injection](#pre_llm_call-context-injection) |
-| [`post_llm_call`](/user-guide/features/hooks#post_llm_call) | Once per turn, after the tool-calling loop (successful turns only) | `session_id: str, user_message: str, assistant_response: str, conversation_history: list, model: str, platform: str` | ignored |
+| [`pre_tool_call`](../../user-guide/features/hooks.md#pre_tool_call) | Before any tool executes | `tool_name: str, args: dict, task_id: str` | optional directive: `{"action": "block", "message": ...}` vetoes the call; `{"action": "approve", "message": ...}` escalates to the human-approval gate |
+| [`post_tool_call`](../../user-guide/features/hooks.md#post_tool_call) | After any tool returns | `tool_name: str, args: dict, result: str, task_id: str, duration_ms: int` | ignored |
+| [`pre_llm_call`](../../user-guide/features/hooks.md#pre_llm_call) | Once per turn, before the tool-calling loop | `session_id: str, user_message: str, conversation_history: list, is_first_turn: bool, model: str, platform: str` | [context injection](#pre_llm_call-context-injection) |
+| [`post_llm_call`](../../user-guide/features/hooks.md#post_llm_call) | Once per turn, after the tool-calling loop (successful turns only) | `session_id: str, user_message: str, assistant_response: str, conversation_history: list, model: str, platform: str` | ignored |
 | `pre_api_request` | Before each raw provider API request (several per turn when the model calls tools) | `session_id: str, model: str, provider: str, base_url: str, api_mode: str, api_call_count: int, message_count: int, tool_count: int, approx_input_tokens: int, max_tokens: int, request: dict` | ignored |
 | `post_api_request` | After each raw provider API request returns | `pre_api_request` fields plus `api_duration: float, finish_reason: str, response_model: str \| None, usage: dict, response: dict, assistant_content_chars: int, assistant_tool_call_count: int` | ignored |
 | `api_request_error` | A provider API call raised | correlation fields plus `status_code: int \| None, retry_count: int \| None, max_retries: int \| None, retryable: bool \| None, reason: str \| None, error: dict, request: dict` | ignored |
-| [`on_session_start`](/user-guide/features/hooks#on_session_start) | New session created (first turn only) | `session_id: str, model: str, platform: str` | ignored |
-| [`on_session_end`](/user-guide/features/hooks#on_session_end) | End of every `run_conversation` call + CLI exit | `session_id: str, completed: bool, interrupted: bool, model: str, platform: str` | ignored |
-| [`on_session_finalize`](/user-guide/features/hooks#on_session_finalize) | CLI/gateway tears down an active session | `session_id: str \| None, platform: str` | ignored |
-| [`on_session_reset`](/user-guide/features/hooks#on_session_reset) | Gateway swaps in a new session key (`/new`, `/reset`) | `session_id: str, platform: str` | ignored |
-| [`gateway_platform_event`](/user-guide/features/hooks#gateway_platform_event) | An authorized platform-native event is normalized at the gateway boundary (Telegram reactions currently) | `platform: str, event_type: str, payload: dict` | ignored |
+| [`on_session_start`](../../user-guide/features/hooks.md#on_session_start) | New session created (first turn only) | `session_id: str, model: str, platform: str` | ignored |
+| [`on_session_end`](../../user-guide/features/hooks.md#on_session_end) | End of every `run_conversation` call + CLI exit | `session_id: str, completed: bool, interrupted: bool, model: str, platform: str` | ignored |
+| [`on_session_finalize`](../../user-guide/features/hooks.md#on_session_finalize) | CLI/gateway tears down an active session | `session_id: str \| None, platform: str` | ignored |
+| [`on_session_reset`](../../user-guide/features/hooks.md#on_session_reset) | Gateway swaps in a new session key (`/new`, `/reset`) | `session_id: str, platform: str` | ignored |
+| [`gateway_platform_event`](../../user-guide/features/hooks.md#gateway_platform_event) | An authorized platform-native event is normalized at the gateway boundary (Telegram reactions currently) | `platform: str, event_type: str, payload: dict` | ignored |
 | `kanban_task_claimed` | A kanban task is claimed (dispatcher process, before the worker spawns) | `task_id: str, board: str \| None, assignee: str \| None, run_id: int \| None, profile_name: str` | ignored |
 | `kanban_task_completed` | A kanban task completes (worker process) | `task_id, board, assignee, run_id, profile_name, summary: str \| None` | ignored |
 | `kanban_task_blocked` | A kanban task is blocked (worker process) | `task_id, board, assignee, run_id, profile_name, reason: str \| None` | ignored |
@@ -1184,7 +1184,7 @@ def register(ctx):
 
 After registration, users can run `hermes my-plugin status`, `hermes my-plugin config`, etc.
 
-**Memory provider plugins** use a convention-based approach instead: add a `register_cli(subparser)` function to your plugin's `cli.py` file. The memory plugin discovery system finds it automatically — no `ctx.register_cli_command()` call needed. See the [Memory Provider Plugin guide](/developer-guide/memory-provider-plugin#adding-cli-commands) for details.
+**Memory provider plugins** use a convention-based approach instead: add a `register_cli(subparser)` function to your plugin's `cli.py` file. The memory plugin discovery system finds it automatically — no `ctx.register_cli_command()` call needed. See the [Memory Provider Plugin guide](../memory-provider-plugin.md#adding-cli-commands) for details.
 
 **Active-provider gating:** Memory plugin CLI commands only appear when their provider is the active `memory.provider` in config. If a user hasn't set up your provider, your CLI commands won't clutter the help output.
 
@@ -1450,7 +1450,7 @@ description: Acme Inference — OpenAI-compatible direct API
 
 Lazy-discovered the first time anything calls `get_provider_profile()` or `list_providers()` — `auth.py`, `config.py`, `doctor.py`, `models.py`, `runtime_provider.py`, and the chat_completions transport auto-wire to it. User plugins override bundled ones by name.
 
-**Full guide:** [Model Provider Plugins](/developer-guide/model-provider-plugin) — field reference, overridable hooks (`prepare_messages`, `build_extra_body`, `build_api_kwargs_extras`, `fetch_models`), api_mode selection, auth types, testing.
+**Full guide:** [Model Provider Plugins](../model-provider-plugin.md) — field reference, overridable hooks (`prepare_messages`, `build_extra_body`, `build_api_kwargs_extras`, `fetch_models`), api_mode selection, auth types, testing.
 
 ### Platform plugins — add a gateway channel
 
@@ -1510,7 +1510,7 @@ optional_env:
     password: false
 ```
 
-**Full guide:** [Adding Platform Adapters](/developer-guide/adding-platform-adapters) — complete `BasePlatformAdapter` contract, message routing, auth gating, setup wizard integration. Look at `plugins/platforms/irc/` for a stdlib-only working example.
+**Full guide:** [Adding Platform Adapters](../adding-platform-adapters.md) — complete `BasePlatformAdapter` contract, message routing, auth gating, setup wizard integration. Look at `plugins/platforms/irc/` for a stdlib-only working example.
 
 ### Memory provider plugins — add a cross-session knowledge backend
 
@@ -1550,7 +1550,7 @@ Memory providers are single-select — only one is active at a time, chosen via
 
 If a provider also loads as a general plugin, general discovery owns its lifecycle hooks. The memory loader supplies hooks only as a fallback until that same plugin source loads successfully through general discovery. Repeated provider loads replace the fallback hook group; distinct callbacks within the group are preserved. This does not deduplicate hooks from different plugin sources or change provider activation.
 
-**Full guide:** [Memory Provider Plugins](/developer-guide/memory-provider-plugin) — full `MemoryProvider` ABC, threading contract, profile isolation, CLI command registration via `cli.py`.
+**Full guide:** [Memory Provider Plugins](../memory-provider-plugin.md) — full `MemoryProvider` ABC, threading contract, profile isolation, CLI command registration via `cli.py`.
 
 ### Context engine plugins — replace the context compressor
 
@@ -1574,7 +1574,7 @@ def register(ctx):
 
 Context engines are single-select — chosen via `context.engine` in `config.yaml`.
 
-**Full guide:** [Context Engine Plugins](/developer-guide/context-engine-plugin).
+**Full guide:** [Context Engine Plugins](../context-engine-plugin.md).
 
 ### Image-generation backends
 
@@ -1606,13 +1606,13 @@ version: 1.0.0
 description: Custom image generation backend
 ```
 
-**Full guide:** [Image Generation Provider Plugins](/developer-guide/image-gen-provider-plugin) — full `ImageGenProvider` ABC, `list_models()` / `get_setup_schema()` metadata, `success_response()`/`error_response()` helpers, base64 vs URL output, user overrides, pip distribution.
+**Full guide:** [Image Generation Provider Plugins](../image-gen-provider-plugin.md) — full `ImageGenProvider` ABC, `list_models()` / `get_setup_schema()` metadata, `success_response()`/`error_response()` helpers, base64 vs URL output, user overrides, pip distribution.
 
 **Reference examples:** `plugins/image_gen/openai/` (DALL-E / GPT-Image via OpenAI SDK), `plugins/image_gen/openai-codex/`, `plugins/image_gen/xai/` (Grok image gen).
 
 ## Non-Python extension surfaces
 
-Hermes also accepts extensions that aren't Python plugins at all. These are shown in the [Pluggable interfaces table](/user-guide/features/plugins#pluggable-interfaces--where-to-go-for-each); the sections below sketch each authoring style briefly.
+Hermes also accepts extensions that aren't Python plugins at all. These are shown in the [Pluggable interfaces table](../../user-guide/features/plugins.md#pluggable-interfaces--where-to-go-for-each); the sections below sketch each authoring style briefly.
 
 ### MCP servers — register external tools
 
@@ -1631,7 +1631,7 @@ mcp_servers:
       type: "oauth"
 ```
 
-Hermes connects to each server at startup, lists its tools, and registers them alongside built-ins. The LLM sees them exactly like any other tool. **Full guide:** [MCP](/user-guide/features/mcp).
+Hermes connects to each server at startup, lists its tools, and registers them alongside built-ins. The LLM sees them exactly like any other tool. **Full guide:** [MCP](../../user-guide/features/mcp.md).
 
 ### Gateway event hooks — fire on lifecycle events
 
@@ -1655,7 +1655,7 @@ async def handle(event_type: str, context: dict) -> None:
 
 Events include `gateway:startup`, `session:start`, `session:end`, `session:reset`, `agent:start`, `agent:step`, `agent:end`, and wildcard `command:*`. Errors in hooks are caught and logged — they never block the main pipeline.
 
-**Full guide:** [Gateway Event Hooks](/user-guide/features/hooks#gateway-event-hooks).
+**Full guide:** [Gateway Event Hooks](../../user-guide/features/hooks.md#gateway-event-hooks).
 
 ### Shell hooks — run a shell command on tool calls
 
@@ -1671,7 +1671,7 @@ hooks:
 
 Supports all the same events as Python plugin hooks (`pre_tool_call`, `post_tool_call`, `pre_llm_call`, `post_llm_call`, `on_session_start`, `on_session_end`, `pre_gateway_dispatch`) plus structured JSON output for `pre_tool_call` blocking decisions.
 
-**Full guide:** [Shell Hooks](/user-guide/features/hooks#shell-hooks).
+**Full guide:** [Shell Hooks](../../user-guide/features/hooks.md#shell-hooks).
 
 ### Skill sources — add a custom skill registry
 
@@ -1685,7 +1685,7 @@ hermes skills install myorg/skills-repo/my-workflow
 
 Publishing your own tap is just a GitHub repo with `skills/<skill-name>/SKILL.md` directories — no server or registry signup needed.
 
-**Full guides:** [Skills Hub](/user-guide/features/skills#skills-hub) · [Publishing a custom tap](/user-guide/features/skills#publishing-a-custom-skill-tap) (repo layout, minimal example, non-default paths, trust levels).
+**Full guides:** [Skills Hub](../../user-guide/features/skills.md#skills-hub) · [Publishing a custom tap](../../user-guide/features/skills.md#publishing-a-custom-skill-tap) (repo layout, minimal example, non-default paths, trust levels).
 
 ### TTS / STT via command templates
 
@@ -1704,7 +1704,7 @@ tts:
 
 For STT, point `HERMES_LOCAL_STT_COMMAND` at an argv-tokenized template. It runs without implicit shell interpretation; wrap it in `sh -c`, `cmd /c`, or PowerShell explicitly if the trusted local command requires shell syntax. Supported placeholders: `{input_path}`, `{output_path}`, `{format}`, `{voice}`, `{model}`, `{speed}` (TTS); `{input_path}`, `{output_dir}`, `{language}`, `{model}` (STT). Any path-interacting CLI is automatically a plugin.
 
-**Full guides:** [TTS custom command providers](/user-guide/features/tts#custom-command-providers) · [STT](/user-guide/features/tts#voice-message-transcription-stt).
+**Full guides:** [TTS custom command providers](../../user-guide/features/tts.md#custom-command-providers) · [STT](../../user-guide/features/tts.md#voice-message-transcription-stt).
 
 ## Distribute via pip
 
@@ -1724,7 +1724,7 @@ pip install hermes-plugin-calculator
 ## Distribute for NixOS
 
 :::warning Nix is no longer explicitly supported
-Nix/NixOS is no longer an explicitly supported install path (best-effort only) — see [Nix Setup](/getting-started/nix-setup). This section is kept for users already deploying on NixOS.
+Nix/NixOS is no longer an explicitly supported install path (best-effort only) — see [Nix Setup](../../getting-started/nix-setup.md). This section is kept for users already deploying on NixOS.
 :::
 
 NixOS users can install your plugin declaratively if you provide a `pyproject.toml` with entry points:
@@ -1760,7 +1760,7 @@ services.hermes-agent.extraPlugins = [
 ];
 ```
 
-See the [Nix Setup guide](/getting-started/nix-setup#plugins) for complete documentation including overlay usage and collision checking.
+See the [Nix Setup guide](../../getting-started/nix-setup.md#plugins) for complete documentation including overlay usage and collision checking.
 
 ## Common mistakes
 
diff --git a/website/docs/developer-guide/relay-connector-contract.md b/website/docs/developer-guide/relay-connector-contract.md
index 2657def4cb..1a7552de68 100644
--- a/website/docs/developer-guide/relay-connector-contract.md
+++ b/website/docs/developer-guide/relay-connector-contract.md
@@ -776,7 +776,7 @@ Typing/status frames always carry the triggering-ts anchor when one is known
 (liveliness is unconditional, both modes): Slack's status line is
 thread-scoped, and in flat mode the send-side anchor strip guarantees the
 status anchor can never leak into reply placement. Semantics of the native
-key: see [Slack](/user-guide/messaging/slack).
+key: see [Slack](../user-guide/messaging/slack.md).
 
 Thread-anchor resolution applies to EVERY send lane — text (`send`) and media
 (`send_media`) alike — through one choke point
diff --git a/website/docs/developer-guide/secret-source-plugin.md b/website/docs/developer-guide/secret-source-plugin.md
index 666f709958..869db2fec3 100644
--- a/website/docs/developer-guide/secret-source-plugin.md
+++ b/website/docs/developer-guide/secret-source-plugin.md
@@ -9,7 +9,7 @@ description: "How to build a secret-manager backend plugin for Hermes Agent"
 Secret sources resolve provider credentials from an external secret manager (a vault, a password manager, an OS keystore, a custom script) into environment variables at process startup — after `~/.hermes/.env` loads, before Hermes reads credentials. Bitwarden, 1Password, and a generic command-helper source ship in-tree; **every other backend is a plugin**. This guide covers building one.
 
 :::tip
-The bundled set is deliberately closed, same policy as [memory providers](/developer-guide/memory-provider-plugin): PRs adding new vault backends under `agent/secret_sources/` are closed with a pointer to this guide. Publish your backend as a standalone plugin repo and share it in the Nous Research Discord (`#plugins-skills-and-skins`).
+The bundled set is deliberately closed, same policy as [memory providers](./memory-provider-plugin.md): PRs adding new vault backends under `agent/secret_sources/` are closed with a pointer to this guide. Publish your backend as a standalone plugin repo and share it in the Nous Research Discord (`#plugins-skills-and-skins`).
 :::
 
 ## First-process bootstrap timing
@@ -160,7 +160,7 @@ secrets:
     # ... your config_schema keys
 ```
 
-Multi-source precedence, conflict warnings, and `(from My Vault)` provenance labels all work automatically — see the [user-facing secrets docs](/user-guide/secrets/) for the precedence ladder.
+Multi-source precedence, conflict warnings, and `(from My Vault)` provenance labels all work automatically — see the [user-facing secrets docs](../user-guide/secrets/index.md) for the precedence ladder.
 
 ## Validate with the conformance kit
 
diff --git a/website/docs/developer-guide/terminal-environment-plugin.md b/website/docs/developer-guide/terminal-environment-plugin.md
index dd102de46c..aca7424bdd 100644
--- a/website/docs/developer-guide/terminal-environment-plugin.md
+++ b/website/docs/developer-guide/terminal-environment-plugin.md
@@ -7,7 +7,7 @@ sandbox vendors integrate as **plugins** instead — a standalone plugin repo
 installed under `~/.hermes/plugins/`, registering a backend the user selects
 exactly like a built-in one via `terminal.backend` in `config.yaml`.
 
-This page mirrors the [Browser Provider Plugins](/developer-guide/browser-provider-plugin)
+This page mirrors the [Browser Provider Plugins](./browser-provider-plugin.md)
 guide — same registration flow, same scope semantics.
 
 ## What a provider controls
diff --git a/website/docs/developer-guide/video-gen-provider-plugin.md b/website/docs/developer-guide/video-gen-provider-plugin.md
index ddb4a8aa31..0b564c1ced 100644
--- a/website/docs/developer-guide/video-gen-provider-plugin.md
+++ b/website/docs/developer-guide/video-gen-provider-plugin.md
@@ -9,7 +9,7 @@ description: "How to build a video-generation backend plugin for Hermes Agent"
 Video-gen provider plugins register a backend that services every `video_generate` tool call. Built-in providers (xAI, FAL, OpenRouter, DeepInfra) ship as plugins. Add a new one, or override a bundled one, by dropping a directory into `plugins/video_gen/<name>/`.
 
 :::tip
-Video-gen mirrors [Image Generation Provider Plugins](/developer-guide/image-gen-provider-plugin) almost line-for-line — if you've built an image-gen backend, you already know the shape. The main differences: a `capabilities()` method advertising modalities/aspect-ratios/durations, and a routing convention (pass `image_url` to use image-to-video, omit it to use text-to-video — the provider picks the right endpoint internally).
+Video-gen mirrors [Image Generation Provider Plugins](./image-gen-provider-plugin.md) almost line-for-line — if you've built an image-gen backend, you already know the shape. The main differences: a `capabilities()` method advertising modalities/aspect-ratios/durations, and a routing convention (pass `image_url` to use image-to-video, omit it to use text-to-video — the provider picks the right endpoint internally).
 :::
 
 ## The unified surface (one tool, two modalities)
diff --git a/website/docs/developer-guide/web-search-provider-plugin.md b/website/docs/developer-guide/web-search-provider-plugin.md
index 2cce42ac6c..2070c68740 100644
--- a/website/docs/developer-guide/web-search-provider-plugin.md
+++ b/website/docs/developer-guide/web-search-provider-plugin.md
@@ -9,7 +9,7 @@ description: "How to build a web-search/extract/crawl backend plugin for Hermes
 Web-search provider plugins register a backend that services `web_search`, `web_extract`, and (optionally) deep-crawl tool calls. Built-in providers — Firecrawl, SearXNG, Tavily, Perplexity, Exa, Parallel, Keenable, Brave Search (free tier), xAI, and DDGS — all ship as plugins under `plugins/web/<name>/`. You can add a new one, or override a bundled one, by dropping a directory next to them.
 
 :::tip
-Web search is one of several **backend plugins** Hermes supports. The others (with their own ABCs) are [Image Generation Provider Plugins](/developer-guide/image-gen-provider-plugin), [Video Generation Provider Plugins](/developer-guide/video-gen-provider-plugin), [Memory Provider Plugins](/developer-guide/memory-provider-plugin), [Context Engine Plugins](/developer-guide/context-engine-plugin), and [Model Provider Plugins](/developer-guide/model-provider-plugin). General tool/hook/CLI plugins live in [Build a Hermes Plugin](/developer-guide/plugins).
+Web search is one of several **backend plugins** Hermes supports. The others (with their own ABCs) are [Image Generation Provider Plugins](./image-gen-provider-plugin.md), [Video Generation Provider Plugins](./video-gen-provider-plugin.md), [Memory Provider Plugins](./memory-provider-plugin.md), [Context Engine Plugins](./context-engine-plugin.md), and [Model Provider Plugins](./model-provider-plugin.md). General tool/hook/CLI plugins live in [Build a Hermes Plugin](./plugins/index.md).
 :::
 
 ## How discovery works
@@ -141,7 +141,7 @@ requires_env:
 |---|---|
 | `kind: backend` | Routes the plugin through the backend-loading path |
 | `provides_web_providers` | List of provider `name`s this plugin registers — used by the loader to advertise the plugin in `hermes tools` even before `register()` runs |
-| `requires_env` | Interactive credential prompt during `hermes plugins install` (see [Build a Hermes Plugin](/developer-guide/plugins#gate-on-environment-variables) for the rich format) |
+| `requires_env` | Interactive credential prompt during `hermes plugins install` (see [Build a Hermes Plugin](./plugins/index.md#gate-on-environment-variables) for the rich format) |
 
 ## ABC reference
 
@@ -233,7 +233,7 @@ Errors surface as the tool result; the LLM decides how to explain them. If no pr
 
 ## Lazy-installing optional dependencies
 
-If your provider wraps a third-party SDK (like DDGS does with the `ddgs` package), don't `import` it at module top level. Use `tools.lazy_deps.ensure(...)` inside `is_available()` or `search()` — Hermes will install the package on first use, gated by `security.allow_lazy_installs`. See [Build a Hermes Plugin → Lazy-install](/developer-guide/plugins#lazy-install-optional-python-dependencies) for the security model.
+If your provider wraps a third-party SDK (like DDGS does with the `ddgs` package), don't `import` it at module top level. Use `tools.lazy_deps.ensure(...)` inside `is_available()` or `search()` — Hermes will install the package on first use, gated by `security.allow_lazy_installs`. See [Build a Hermes Plugin → Lazy-install](./plugins/index.md#lazy-install-optional-python-dependencies) for the security model.
 
 ## Reference implementations
 
@@ -251,10 +251,10 @@ If your provider wraps a third-party SDK (like DDGS does with the `ddgs` package
 my-backend-web = "my_backend_web_package"
 ```
 
-`my_backend_web_package` must expose a top-level `register` function. See [Distribute via pip](/developer-guide/plugins#distribute-via-pip) in the general plugin guide for the full setup.
+`my_backend_web_package` must expose a top-level `register` function. See [Distribute via pip](./plugins/index.md#distribute-via-pip) in the general plugin guide for the full setup.
 
 ## Related pages
 
-- [Web Search](/user-guide/features/web-search) — user-facing feature documentation and per-backend configuration
-- [Plugins overview](/user-guide/features/plugins) — all plugin types at a glance
-- [Build a Hermes Plugin](/developer-guide/plugins) — general tools/hooks/slash commands guide
+- [Web Search](../user-guide/features/web-search.md) — user-facing feature documentation and per-backend configuration
+- [Plugins overview](../user-guide/features/plugins.md) — all plugin types at a glance
+- [Build a Hermes Plugin](./plugins/index.md) — general tools/hooks/slash commands guide
diff --git a/website/docs/getting-started/installation.md b/website/docs/getting-started/installation.md
index 91e6205623..9016377d10 100644
--- a/website/docs/getting-started/installation.md
+++ b/website/docs/getting-started/installation.md
@@ -77,7 +77,7 @@ hermes setup          # Or run the full setup wizard to configure everything at
 ```
 
 :::tip Fastest path: Nous Portal
-One subscription covers 300+ models plus the [Tool Gateway](/user-guide/features/tool-gateway) (web search, image generation, TTS, cloud browser). Skip the per-tool key juggling:
+One subscription covers 300+ models plus the [Tool Gateway](../user-guide/features/tool-gateway.md) (web search, image generation, TTS, cloud browser). Skip the per-tool key juggling:
 
 ```bash
 hermes setup --portal
@@ -87,7 +87,7 @@ That logs you in, sets Nous as your provider, and turns on the Tool Gateway in o
 :::
 
 :::tip Already running Hermes on another machine?
-You don't need to rebuild your setup from scratch. Restore a full backup with `hermes import` (see [Exporting Hermes to another machine](/reference/faq#exporting-hermes-to-another-machine)), or bring over a single agent with `hermes profile import` (see [Moving a single profile to another machine](/reference/faq#moving-a-single-profile-to-another-machine)). Note that a profile export excludes credentials by design, so an export alone is not a full backup — [`hermes backup` vs `hermes profile export`](/reference/faq#hermes-backup-vs-hermes-profile-export) explains which to use.
+You don't need to rebuild your setup from scratch. Restore a full backup with `hermes import` (see [Exporting Hermes to another machine](../reference/faq.md#exporting-hermes-to-another-machine)), or bring over a single agent with `hermes profile import` (see [Moving a single profile to another machine](../reference/faq.md#moving-a-single-profile-to-another-machine)). Note that a profile export excludes credentials by design, so an export alone is not a full backup — [`hermes backup` vs `hermes profile export`](../reference/faq.md#hermes-backup-vs-hermes-profile-export) explains which to use.
 :::
 
 ---
@@ -159,7 +159,7 @@ Running Hermes as a dedicated unprivileged user (e.g. a `hermes` systemd service
    sudo loginctl enable-linger <service-user>
    ```
 
-   See [Messaging Gateway](/user-guide/messaging/) for the service setup itself.
+   See [Messaging Gateway](../user-guide/messaging/index.md) for the service setup itself.
 
 The same pattern works on Arch (the installer uses pacman with the same sudo-detection logic), Fedora/RHEL, and openSUSE — those distros don't support `--with-deps` at all, so an administrator always installs the system libraries separately. The relevant `dnf`/`zypper` commands are printed by the installer.
 
diff --git a/website/docs/getting-started/learning-path.md b/website/docs/getting-started/learning-path.md
index 0f6e9d8510..6ddce59518 100644
--- a/website/docs/getting-started/learning-path.md
+++ b/website/docs/getting-started/learning-path.md
@@ -9,11 +9,11 @@ description: 'Choose your learning path through the Hermes Agent documentation b
 Hermes Agent can do a lot — CLI assistant, Telegram/Discord bot, task automation, RL training, and more. This page helps you figure out where to start and what to read based on your experience level and what you're trying to accomplish.
 
 :::tip Start Here
-If you haven't installed Hermes Agent yet, begin with the [Installation guide](/getting-started/installation) and then run through the [Quickstart](/getting-started/quickstart). Everything below assumes you have a working installation.
+If you haven't installed Hermes Agent yet, begin with the [Installation guide](./installation.md) and then run through the [Quickstart](./quickstart.md). Everything below assumes you have a working installation.
 :::
 
 :::tip First-time provider setup
-First-time users almost always want `hermes setup --portal` — one OAuth covers a model plus the four Tool Gateway tools (search/image/TTS/browser). See [Nous Portal](/integrations/nous-portal).
+First-time users almost always want `hermes setup --portal` — one OAuth covers a model plus the four Tool Gateway tools (search/image/TTS/browser). See [Nous Portal](../integrations/nous-portal.md).
 :::
 
 ## How to Use This Page
@@ -26,9 +26,9 @@ First-time users almost always want `hermes setup --portal` — one OAuth covers
 
 | Level | Goal | Recommended Reading | Time Estimate |
 |---|---|---|---|
-| **Beginner** | Get up and running, have basic conversations, use built-in tools | [Installation](/getting-started/installation) → [Quickstart](/getting-started/quickstart) → [CLI Usage](/user-guide/cli) → [Configuration](/user-guide/configuration) | ~1 hour |
-| **Intermediate** | Set up messaging bots, use advanced features like memory, cron jobs, and skills | [Sessions](/user-guide/sessions) → [Messaging](/user-guide/messaging) → [Tools](/user-guide/features/tools) → [Skills](/user-guide/features/skills) → [Memory](/user-guide/features/memory) → [Cron](/user-guide/features/cron) | ~2–3 hours |
-| **Advanced** | Build custom tools, create skills, train models with RL, contribute to the project | [Architecture](/developer-guide/architecture) → [Adding Tools](/developer-guide/adding-tools) → [Creating Skills](/developer-guide/creating-skills) → [Contributing](/developer-guide/contributing) | ~4–6 hours |
+| **Beginner** | Get up and running, have basic conversations, use built-in tools | [Installation](./installation.md) → [Quickstart](./quickstart.md) → [CLI Usage](../user-guide/cli.md) → [Configuration](../user-guide/configuration.md) | ~1 hour |
+| **Intermediate** | Set up messaging bots, use advanced features like memory, cron jobs, and skills | [Sessions](../user-guide/sessions.md) → [Messaging](../user-guide/messaging/index.md) → [Tools](../user-guide/features/tools.md) → [Skills](../user-guide/features/skills.md) → [Memory](../user-guide/features/memory.md) → [Cron](../user-guide/features/cron.md) | ~2–3 hours |
+| **Advanced** | Build custom tools, create skills, train models with RL, contribute to the project | [Architecture](../developer-guide/architecture.md) → [Adding Tools](../developer-guide/adding-tools.md) → [Creating Skills](../developer-guide/creating-skills.md) → [Contributing](../developer-guide/contributing.md) | ~4–6 hours |
 
 ## By Use Case
 
@@ -38,12 +38,12 @@ Pick the scenario that matches what you want to do. Each one links you to the re
 
 Use Hermes Agent as an interactive terminal assistant for writing, reviewing, and running code.
 
-1. [Installation](/getting-started/installation)
-2. [Quickstart](/getting-started/quickstart)
-3. [CLI Usage](/user-guide/cli)
-4. [Code Execution](/user-guide/features/code-execution)
-5. [Context Files](/user-guide/features/context-files)
-6. [Tips & Tricks](/guides/tips)
+1. [Installation](./installation.md)
+2. [Quickstart](./quickstart.md)
+3. [CLI Usage](../user-guide/cli.md)
+4. [Code Execution](../user-guide/features/code-execution.md)
+5. [Context Files](../user-guide/features/context-files.md)
+6. [Tips & Tricks](../guides/tips.md)
 
 :::tip
 Pass files directly into your conversation with context files. Hermes Agent can read, edit, and run code in your projects.
@@ -53,28 +53,28 @@ Pass files directly into your conversation with context files. Hermes Agent can
 
 Deploy Hermes Agent as a bot on your favorite messaging platform.
 
-1. [Installation](/getting-started/installation)
-2. [Configuration](/user-guide/configuration)
-3. [Messaging Overview](/user-guide/messaging)
-4. [Telegram Setup](/user-guide/messaging/telegram)
-5. [Discord Setup](/user-guide/messaging/discord)
-6. [Voice Mode](/user-guide/features/voice-mode)
-7. [Use Voice Mode with Hermes](/guides/use-voice-mode-with-hermes)
-8. [Security](/user-guide/security)
+1. [Installation](./installation.md)
+2. [Configuration](../user-guide/configuration.md)
+3. [Messaging Overview](../user-guide/messaging/index.md)
+4. [Telegram Setup](../user-guide/messaging/telegram.md)
+5. [Discord Setup](../user-guide/messaging/discord.md)
+6. [Voice Mode](../user-guide/features/voice-mode.md)
+7. [Use Voice Mode with Hermes](../guides/use-voice-mode-with-hermes.md)
+8. [Security](../user-guide/security.md)
 
 For full project examples, see:
-- [Daily Briefing Bot](/guides/daily-briefing-bot)
-- [Team Telegram Assistant](/guides/team-telegram-assistant)
+- [Daily Briefing Bot](../guides/daily-briefing-bot.md)
+- [Team Telegram Assistant](../guides/team-telegram-assistant.md)
 
 ### "I want to automate tasks"
 
 Schedule recurring tasks, run batch jobs, or chain agent actions together.
 
-1. [Quickstart](/getting-started/quickstart)
-2. [Cron Scheduling](/user-guide/features/cron)
-3. [Batch Processing](/user-guide/features/batch-processing)
-4. [Delegation](/user-guide/features/delegation)
-5. [Hooks](/user-guide/features/hooks)
+1. [Quickstart](./quickstart.md)
+2. [Cron Scheduling](../user-guide/features/cron.md)
+3. [Batch Processing](../user-guide/features/batch-processing.md)
+4. [Delegation](../user-guide/features/delegation.md)
+5. [Hooks](../user-guide/features/hooks.md)
 
 :::tip
 Cron jobs let Hermes Agent run tasks on a schedule — daily summaries, periodic checks, automated reports — without you being present.
@@ -84,27 +84,27 @@ Cron jobs let Hermes Agent run tasks on a schedule — daily summaries, periodic
 
 Create named Bots with their own model, memory, skills, routines, and chats, then bring them together in group chats or through `@mentions`.
 
-1. [Desktop](/user-guide/desktop)
-2. [Profiles](/user-guide/profiles)
-3. [Bot Mode](/user-guide/bot-mode)
-4. [Cron Scheduling](/user-guide/features/cron)
-5. [Multi-connection Desktop](/user-guide/multi-connection-desktop)
+1. [Desktop](../user-guide/desktop.md)
+2. [Profiles](../user-guide/profiles.md)
+3. [Bot Mode](../user-guide/bot-mode.md)
+4. [Cron Scheduling](../user-guide/features/cron.md)
+5. [Multi-connection Desktop](../user-guide/multi-connection-desktop.md)
 
 ### "I want to build custom tools/skills"
 
 Extend Hermes Agent with your own tools and reusable skill packages.
 
-1. [Plugins](/user-guide/features/plugins)
-2. [Build a Hermes Plugin](/developer-guide/plugins)
-3. [Tools Overview](/user-guide/features/tools)
-4. [Skills Overview](/user-guide/features/skills)
-5. [MCP (Model Context Protocol)](/user-guide/features/mcp)
-6. [Architecture](/developer-guide/architecture)
-7. [Adding Tools](/developer-guide/adding-tools)
-8. [Creating Skills](/developer-guide/creating-skills)
+1. [Plugins](../user-guide/features/plugins.md)
+2. [Build a Hermes Plugin](../developer-guide/plugins/index.md)
+3. [Tools Overview](../user-guide/features/tools.md)
+4. [Skills Overview](../user-guide/features/skills.md)
+5. [MCP (Model Context Protocol)](../user-guide/features/mcp.md)
+6. [Architecture](../developer-guide/architecture.md)
+7. [Adding Tools](../developer-guide/adding-tools.md)
+8. [Creating Skills](../developer-guide/creating-skills.md)
 
 :::tip
-For most custom tool creation, start with plugins. The [Adding Tools](/developer-guide/adding-tools)
+For most custom tool creation, start with plugins. The [Adding Tools](../developer-guide/adding-tools.md)
 page is for built-in Hermes core development, not the usual user/custom-tool path.
 :::
 
@@ -112,11 +112,11 @@ page is for built-in Hermes core development, not the usual user/custom-tool pat
 
 Use reinforcement learning to fine-tune model behavior with Hermes Agent's RL training pipeline (powered by [Atropos](https://github.com/NousResearch/atropos)).
 
-1. [Quickstart](/getting-started/quickstart)
-2. [Configuration](/user-guide/configuration)
+1. [Quickstart](./quickstart.md)
+2. [Configuration](../user-guide/configuration.md)
 3. [Atropos RL Environments](https://github.com/NousResearch/atropos) (external)
-4. [Provider Routing](/user-guide/features/provider-routing)
-5. [Architecture](/developer-guide/architecture)
+4. [Provider Routing](../user-guide/features/provider-routing.md)
+5. [Architecture](../developer-guide/architecture.md)
 
 :::tip
 RL training works best when you already understand the basics of how Hermes Agent handles conversations and tool calls. Run through the Beginner path first if you're new.
@@ -126,12 +126,12 @@ RL training works best when you already understand the basics of how Hermes Agen
 
 Integrate Hermes Agent into your own Python applications programmatically.
 
-1. [Installation](/getting-started/installation)
-2. [Quickstart](/getting-started/quickstart)
-3. [Python Library Guide](/guides/python-library)
-4. [Architecture](/developer-guide/architecture)
-5. [Tools](/user-guide/features/tools)
-6. [Sessions](/user-guide/sessions)
+1. [Installation](./installation.md)
+2. [Quickstart](./quickstart.md)
+3. [Python Library Guide](../guides/python-library.md)
+4. [Architecture](../developer-guide/architecture.md)
+5. [Tools](../user-guide/features/tools.md)
+6. [Sessions](../user-guide/sessions.md)
 
 ## Key Features at a Glance
 
@@ -139,30 +139,30 @@ Not sure what's available? Here's a quick directory of major features:
 
 | Feature | What It Does | Link |
 |---|---|---|
-| **Tools** | Built-in tools the agent can call (file I/O, search, shell, etc.) | [Tools](/user-guide/features/tools) |
-| **Skills** | Installable plugin packages that add new capabilities | [Skills](/user-guide/features/skills) |
-| **Memory** | Persistent memory across sessions | [Memory](/user-guide/features/memory) |
-| **Bot Mode** | Named specialist Bots with persistent chats, routines, group chats, and `@mentions` | [Bot Mode](/user-guide/bot-mode) |
-| **Context Files** | Feed files and directories into conversations | [Context Files](/user-guide/features/context-files) |
-| **MCP** | Connect to external tool servers via Model Context Protocol | [MCP](/user-guide/features/mcp) |
-| **Cron** | Schedule recurring agent tasks | [Cron](/user-guide/features/cron) |
-| **Delegation** | Spawn sub-agents for parallel work | [Delegation](/user-guide/features/delegation) |
-| **Code Execution** | Run Python scripts that call Hermes tools programmatically | [Code Execution](/user-guide/features/code-execution) |
-| **Browser** | Web browsing and scraping | [Browser](/user-guide/features/browser) |
-| **Hooks** | Event-driven callbacks and middleware | [Hooks](/user-guide/features/hooks) |
-| **Batch Processing** | Process multiple inputs in bulk | [Batch Processing](/user-guide/features/batch-processing) |
-| **Provider Routing** | Route requests across multiple LLM providers | [Provider Routing](/user-guide/features/provider-routing) |
+| **Tools** | Built-in tools the agent can call (file I/O, search, shell, etc.) | [Tools](../user-guide/features/tools.md) |
+| **Skills** | Installable plugin packages that add new capabilities | [Skills](../user-guide/features/skills.md) |
+| **Memory** | Persistent memory across sessions | [Memory](../user-guide/features/memory.md) |
+| **Bot Mode** | Named specialist Bots with persistent chats, routines, group chats, and `@mentions` | [Bot Mode](../user-guide/bot-mode.md) |
+| **Context Files** | Feed files and directories into conversations | [Context Files](../user-guide/features/context-files.md) |
+| **MCP** | Connect to external tool servers via Model Context Protocol | [MCP](../user-guide/features/mcp.md) |
+| **Cron** | Schedule recurring agent tasks | [Cron](../user-guide/features/cron.md) |
+| **Delegation** | Spawn sub-agents for parallel work | [Delegation](../user-guide/features/delegation.md) |
+| **Code Execution** | Run Python scripts that call Hermes tools programmatically | [Code Execution](../user-guide/features/code-execution.md) |
+| **Browser** | Web browsing and scraping | [Browser](../user-guide/features/browser.md) |
+| **Hooks** | Event-driven callbacks and middleware | [Hooks](../user-guide/features/hooks.md) |
+| **Batch Processing** | Process multiple inputs in bulk | [Batch Processing](../user-guide/features/batch-processing.md) |
+| **Provider Routing** | Route requests across multiple LLM providers | [Provider Routing](../user-guide/features/provider-routing.md) |
 
 ## What to Read Next
 
 Based on where you are right now:
 
-- **Just finished installing?** → Head to the [Quickstart](/getting-started/quickstart) to run your first conversation.
-- **Completed the Quickstart?** → Read [CLI Usage](/user-guide/cli) and [Configuration](/user-guide/configuration) to customize your setup.
-- **Comfortable with the basics?** → Explore [Tools](/user-guide/features/tools), [Skills](/user-guide/features/skills), and [Memory](/user-guide/features/memory) to unlock the full power of the agent.
-- **Setting up for a team?** → Read [Security](/user-guide/security) and [Sessions](/user-guide/sessions) to understand access control and conversation management.
-- **Ready to build?** → Jump into the [Developer Guide](/developer-guide/architecture) to understand the internals and start contributing.
-- **Want practical examples?** → Check out the [Guides](/guides/tips) section for real-world projects and tips.
+- **Just finished installing?** → Head to the [Quickstart](./quickstart.md) to run your first conversation.
+- **Completed the Quickstart?** → Read [CLI Usage](../user-guide/cli.md) and [Configuration](../user-guide/configuration.md) to customize your setup.
+- **Comfortable with the basics?** → Explore [Tools](../user-guide/features/tools.md), [Skills](../user-guide/features/skills.md), and [Memory](../user-guide/features/memory.md) to unlock the full power of the agent.
+- **Setting up for a team?** → Read [Security](../user-guide/security.md) and [Sessions](../user-guide/sessions.md) to understand access control and conversation management.
+- **Ready to build?** → Jump into the [Developer Guide](../developer-guide/architecture.md) to understand the internals and start contributing.
+- **Want practical examples?** → Check out the [Guides](../guides/tips.md) section for real-world projects and tips.
 
 :::tip
 You don't need to read everything. Pick the path that matches your goal, follow the links in order, and you'll be productive quickly. You can always come back to this page to find your next step.
diff --git a/website/docs/getting-started/quickstart.md b/website/docs/getting-started/quickstart.md
index 3d424f0ae7..364a6a9868 100644
--- a/website/docs/getting-started/quickstart.md
+++ b/website/docs/getting-started/quickstart.md
@@ -98,7 +98,7 @@ That logs you in, sets Nous as your provider, and turns on the Tool Gateway in o
 :::info Setup modes
 On a fresh install, `hermes setup` offers three modes:
 
-- **Quick Setup (Nous Portal)** — OAuth login, no API keys to manage; sets up a model plus the Tool Gateway tools, billed to your [Nous Portal subscription](/integrations/nous-portal). The recommended fast path.
+- **Quick Setup (Nous Portal)** — OAuth login, no API keys to manage; sets up a model plus the Tool Gateway tools, billed to your [Nous Portal subscription](../integrations/nous-portal.md). The recommended fast path.
 - **Full Setup** — walk through every provider, tool, and option yourself (bring your own keys).
 - **Blank Slate** — everything starts **off** except the bare minimum needed to run an agent: **provider & model, the File Operations toolset, and the Terminal toolset**. No web, browser, code execution, vision, memory, delegation, cron, skills, plugins, or MCP servers — and compression, checkpoints, smart routing, and memory capture are all disabled. After the minimal baseline is applied, you choose one of two paths: **start with everything disabled** (finish now with the minimal agent), or **walk through all configurations** (opt in to tools, skills, plugins, MCP, and messaging). Pick this when you want a minimal, fully-controlled agent and intend to enable only exactly what you need.
 
@@ -262,7 +262,7 @@ Only after the base chat works. Pick what you need:
 hermes gateway setup    # Interactive platform configuration
 ```
 
-Connect [Telegram](/user-guide/messaging/telegram), [Discord](/user-guide/messaging/discord), [Slack](/user-guide/messaging/slack), [WhatsApp](/user-guide/messaging/whatsapp), [Signal](/user-guide/messaging/signal), [Email](/user-guide/messaging/email), or [Home Assistant](/user-guide/messaging/homeassistant), or [Microsoft Teams](/user-guide/messaging/teams).
+Connect [Telegram](../user-guide/messaging/telegram.md), [Discord](../user-guide/messaging/discord.md), [Slack](../user-guide/messaging/slack.md), [WhatsApp](../user-guide/messaging/whatsapp.md), [Signal](../user-guide/messaging/signal.md), [Email](../user-guide/messaging/email.md), or [Home Assistant](../user-guide/messaging/homeassistant.md), or [Microsoft Teams](../user-guide/messaging/teams.md).
 
 ### Automation and tools
 
@@ -396,4 +396,4 @@ That sequence gets you from "broken vibes" back to a known state fast.
 - **[AI Providers](../integrations/providers.md)** — Full provider list and setup details
 - **[Skills System](../user-guide/features/skills.md)** — Reusable workflows and knowledge
 - **[Tips & Best Practices](../guides/tips.md)** — Power user tips
-- **[Moving to another machine](/reference/faq#exporting-hermes-to-another-machine)** — `hermes backup` migrates your whole setup (or [a single profile](/reference/faq#moving-a-single-profile-to-another-machine)); no need to rebuild from scratch
+- **[Moving to another machine](../reference/faq.md#exporting-hermes-to-another-machine)** — `hermes backup` migrates your whole setup (or [a single profile](../reference/faq.md#moving-a-single-profile-to-another-machine)); no need to rebuild from scratch
diff --git a/website/docs/getting-started/updating.md b/website/docs/getting-started/updating.md
index 02fe14630a..9173aabb34 100644
--- a/website/docs/getting-started/updating.md
+++ b/website/docs/getting-started/updating.md
@@ -183,7 +183,7 @@ updates:
 `updates.pre_update_backup` is a single knob with three modes: `quick` (default — the lightweight state snapshot described above), `full` (the quick snapshot plus a complete `HERMES_HOME` zip; can add minutes on large homes), and `off` (no pre-update backup at all — `--no-backup` does the same for a single run). Legacy boolean values still work: `true` means `full`, `false` means `off`.
 
 :::tip Moving to a new machine instead?
-Update backups protect an in-place update. If you're migrating your whole setup to different hardware, use `hermes backup` + `hermes import` instead — see [Exporting Hermes to another machine](/reference/faq#exporting-hermes-to-another-machine) and [`hermes backup` vs `hermes profile export`](/reference/faq#hermes-backup-vs-hermes-profile-export).
+Update backups protect an in-place update. If you're migrating your whole setup to different hardware, use `hermes backup` + `hermes import` instead — see [Exporting Hermes to another machine](../reference/faq.md#exporting-hermes-to-another-machine) and [`hermes backup` vs `hermes profile export`](../reference/faq.md#hermes-backup-vs-hermes-profile-export).
 :::
 
 ### Windows: another `hermes.exe` is running
@@ -366,7 +366,7 @@ hermes uninstall
 The uninstaller gives you the option to keep your configuration files (`~/.hermes/`) for a future reinstall.
 
 :::tip Moving to a new machine rather than leaving?
-Take your setup with you before removing anything: `hermes backup` captures the entire `~/.hermes` directory including credentials, while `hermes profile export` packs a single profile with credentials excluded by design (so an export alone is not a full backup). See [`hermes backup` vs `hermes profile export`](/reference/faq#hermes-backup-vs-hermes-profile-export).
+Take your setup with you before removing anything: `hermes backup` captures the entire `~/.hermes` directory including credentials, while `hermes profile export` packs a single profile with credentials excluded by design (so an export alone is not a full backup). See [`hermes backup` vs `hermes profile export`](../reference/faq.md#hermes-backup-vs-hermes-profile-export).
 :::
 
 ### Manual Uninstall
diff --git a/website/docs/guides/automate-with-cron.md b/website/docs/guides/automate-with-cron.md
index c73d9b39ea..0d261cac57 100644
--- a/website/docs/guides/automate-with-cron.md
+++ b/website/docs/guides/automate-with-cron.md
@@ -6,17 +6,17 @@ description: "Real-world automation patterns using Hermes cron — monitoring, r
 
 # Automate Anything with Cron
 
-The [daily briefing bot tutorial](/guides/daily-briefing-bot) covers the basics. This guide goes further — five real-world automation patterns you can adapt for your own workflows.
+The [daily briefing bot tutorial](./daily-briefing-bot.md) covers the basics. This guide goes further — five real-world automation patterns you can adapt for your own workflows.
 
-For the full feature reference, see [Scheduled Tasks (Cron)](/user-guide/features/cron).
+For the full feature reference, see [Scheduled Tasks (Cron)](../user-guide/features/cron.md).
 
 :::info Key Concept
 Cron jobs run in fresh agent sessions with no memory of your current chat. Prompts must be **completely self-contained** — include everything the agent needs to know.
 :::
 
 :::tip Don't need the LLM? You have two zero-token options.
-- **Recurring watchdog** where the script already produces the exact message (memory alerts, disk alerts, heartbeats): use [script-only cron jobs](/guides/cron-script-only). Same scheduler, no LLM. You can ask Hermes to set one up for you in chat — the `cronjob` tool knows when to pick `no_agent=True` and writes the script for you.
-- **One-shot from a script that's already running** (CI step, post-commit hook, deploy script, externally-scheduled monitor): use [`hermes send`](/guides/pipe-script-output) to pipe stdout or a file straight to Telegram / Discord / Slack / etc. without setting up a cron entry.
+- **Recurring watchdog** where the script already produces the exact message (memory alerts, disk alerts, heartbeats): use [script-only cron jobs](./cron-script-only.md). Same scheduler, no LLM. You can ask Hermes to set one up for you in chat — the `cronjob` tool knows when to pick `no_agent=True` and writes the script for you.
+- **One-shot from a script that's already running** (CI step, post-commit hook, deploy script, externally-scheduled monitor): use [`hermes send`](./pipe-script-output.md) to pipe stdout or a file straight to Telegram / Discord / Slack / etc. without setting up a cron entry.
 :::
 
 ---
@@ -289,4 +289,4 @@ Things to know:
 
 ---
 
-*For the complete cron reference — all parameters, edge cases, and internals — see [Scheduled Tasks (Cron)](/user-guide/features/cron).*
+*For the complete cron reference — all parameters, edge cases, and internals — see [Scheduled Tasks (Cron)](../user-guide/features/cron.md).*
diff --git a/website/docs/guides/automation-blueprints.md b/website/docs/guides/automation-blueprints.md
index 7bf861e8e2..2451298467 100644
--- a/website/docs/guides/automation-blueprints.md
+++ b/website/docs/guides/automation-blueprints.md
@@ -6,11 +6,11 @@ description: "Ready-to-use automation blueprints — scheduled tasks, GitHub eve
 
 # Automation Blueprints
 
-Copy-paste blueprints for common automation patterns. Each blueprint uses Hermes's built-in [cron scheduler](/user-guide/features/cron) for time-based triggers and [webhook platform](/user-guide/messaging/webhooks) for event-driven triggers.
+Copy-paste blueprints for common automation patterns. Each blueprint uses Hermes's built-in [cron scheduler](../user-guide/features/cron.md) for time-based triggers and [webhook platform](../user-guide/messaging/webhooks.md) for event-driven triggers.
 
 Every blueprint works with **any model** — not locked to a single provider.
 
-For parameterized blueprints with forms instead of cron syntax, see the [Automation Blueprints Catalog](/reference/automation-blueprints-catalog).
+For parameterized blueprints with forms instead of cron syntax, see the [Automation Blueprints Catalog](../reference/automation-blueprints-catalog.mdx).
 
 :::tip Three Trigger Types
 | Trigger | How | Tool |
diff --git a/website/docs/guides/azure-foundry.md b/website/docs/guides/azure-foundry.md
index 76412937b0..6276e72884 100644
--- a/website/docs/guides/azure-foundry.md
+++ b/website/docs/guides/azure-foundry.md
@@ -328,7 +328,7 @@ Verify the same `Azure AI User` (or `Foundry User`) role is assigned on the Foun
 
 ## Related
 
-- [Environment variables](/reference/environment-variables)
-- [Configuration](/user-guide/configuration)
-- [AWS Bedrock](/guides/aws-bedrock) — the other major cloud provider integration
+- [Environment variables](../reference/environment-variables.md)
+- [Configuration](../user-guide/configuration.md)
+- [AWS Bedrock](./aws-bedrock.md) — the other major cloud provider integration
 - [Microsoft: Configure Entra ID for Foundry](https://learn.microsoft.com/azure/ai-foundry/foundry-models/how-to/configure-entra-id) — upstream documentation for the keyless path
diff --git a/website/docs/guides/cron-script-only.md b/website/docs/guides/cron-script-only.md
index ae3f1f0ae0..c53fa1c668 100644
--- a/website/docs/guides/cron-script-only.md
+++ b/website/docs/guides/cron-script-only.md
@@ -173,7 +173,7 @@ hermes cron create "0 9 * * *"       # standard cron: 9am daily
 hermes cron create "30m"             # one-shot: run once in 30 minutes
 ```
 
-See the [cron feature reference](/user-guide/features/cron) for the full syntax.
+See the [cron feature reference](../user-guide/features/cron.md) for the full syntax.
 
 ## Delivery Targets
 
@@ -235,13 +235,13 @@ Silent when both filesystems are under 90%; fires exactly one line per over-thre
 |----------|-----------|-------------|
 | `cronjob --no-agent` (this page) | Your script on Hermes' schedule | Recurring watchdogs / alerts / metrics that don't need reasoning |
 | `cronjob` (default, LLM) | Agent with optional pre-check script | When the message content requires reasoning over data |
-| OS cron + `curl` to a [webhook subscription](/user-guide/messaging/webhooks) | Your script on the OS schedule | When Hermes might be unhealthy (the thing you're monitoring) |
+| OS cron + `curl` to a [webhook subscription](../user-guide/messaging/webhooks.md) | Your script on the OS schedule | When Hermes might be unhealthy (the thing you're monitoring) |
 
 For critical system-health watchdogs that must fire *even when the gateway is down*, use OS-level cron with a plain `curl` to a Hermes webhook subscription (or any external alerting endpoint) — those run as independent OS processes and don't depend on Hermes being up. The in-gateway scheduler is the right choice when the thing being monitored is external.
 
 ## Related
 
-- [Automate Anything with Cron](/guides/automate-with-cron) — LLM-driven cron patterns.
-- [Scheduled Tasks (Cron) reference](/user-guide/features/cron) — full schedule syntax, lifecycle, delivery routing.
-- [Webhook Subscriptions](/user-guide/messaging/webhooks) — fire-and-forget HTTP entry points for external schedulers.
-- [Gateway Internals](/developer-guide/gateway-internals) — delivery-router internals.
+- [Automate Anything with Cron](./automate-with-cron.md) — LLM-driven cron patterns.
+- [Scheduled Tasks (Cron) reference](../user-guide/features/cron.md) — full schedule syntax, lifecycle, delivery routing.
+- [Webhook Subscriptions](../user-guide/messaging/webhooks.md) — fire-and-forget HTTP entry points for external schedulers.
+- [Gateway Internals](../developer-guide/gateway-internals.md) — delivery-router internals.
diff --git a/website/docs/guides/cron-troubleshooting.md b/website/docs/guides/cron-troubleshooting.md
index b58d60d67d..fbb96320da 100644
--- a/website/docs/guides/cron-troubleshooting.md
+++ b/website/docs/guides/cron-troubleshooting.md
@@ -232,4 +232,4 @@ If you've worked through this guide and the issue persists:
 
 ---
 
-*For the complete cron reference, see [Automate Anything with Cron](/guides/automate-with-cron) and [Scheduled Tasks (Cron)](/user-guide/features/cron).*
+*For the complete cron reference, see [Automate Anything with Cron](./automate-with-cron.md) and [Scheduled Tasks (Cron)](../user-guide/features/cron.md).*
diff --git a/website/docs/guides/daily-briefing-bot.md b/website/docs/guides/daily-briefing-bot.md
index a4fda461be..781acaff8a 100644
--- a/website/docs/guides/daily-briefing-bot.md
+++ b/website/docs/guides/daily-briefing-bot.md
@@ -11,7 +11,7 @@ In this tutorial, you'll build a personal briefing bot that wakes up every morni
 By the end, you'll have a fully automated workflow combining **web search**, **cron scheduling**, **delegation**, and **messaging delivery** — no code required.
 
 :::tip
-This recipe hits web search, summarization, and optional TTS — all bundled in a Portal subscription. The fastest setup is `hermes setup --portal`. See [Nous Portal](/integrations/nous-portal).
+This recipe hits web search, summarization, and optional TTS — all bundled in a Portal subscription. The fastest setup is `hermes setup --portal`. See [Nous Portal](../integrations/nous-portal.md).
 :::
 
 ## What We're Building
@@ -30,7 +30,7 @@ The whole thing runs hands-free. You just read your briefing with your morning c
 
 Before starting, make sure you have:
 
-- **Hermes Agent installed** — see the [Installation guide](/getting-started/installation)
+- **Hermes Agent installed** — see the [Installation guide](../getting-started/installation.md)
 - **Gateway running** — the gateway daemon handles cron execution:
   ```bash
   hermes gateway install   # Install as a user service
@@ -39,7 +39,7 @@ Before starting, make sure you have:
   hermes gateway           # Run in foreground
   ```
 - **Firecrawl API key** — set `FIRECRAWL_API_KEY` in your environment for web search
-- **Messaging configured** (optional but recommended) — [Telegram](/user-guide/messaging/telegram) or Discord set up with a home channel
+- **Messaging configured** (optional but recommended) — [Telegram](../user-guide/messaging/telegram.md) or Discord set up with a home channel
 
 :::tip No messaging? No problem
 You can still follow this tutorial using `deliver: "local"`. Briefings will be saved to `~/.hermes/cron/output/` and you can read them anytime.
@@ -171,7 +171,7 @@ For faster briefings, tell Hermes to delegate each topic to a sub-agent:
 Collect all results and combine them into a single clean briefing with section headers, emoji formatting, and source links. Add today's date as a header."
 ```
 
-Each sub-agent searches independently and in parallel, then the main agent combines everything into one polished briefing. See the [Delegation docs](/user-guide/features/delegation) for more on how this works.
+Each sub-agent searches independently and in parallel, then the main agent combines everything into one polished briefing. See the [Delegation docs](../user-guide/features/delegation.md) for more on how this works.
 
 ### Weekday-Only Schedule
 
@@ -192,7 +192,7 @@ Get a morning overview and an evening recap:
 
 ### Adding Personal Context with Memory
 
-If you have [memory](/user-guide/features/memory) enabled, you can store preferences that persist across sessions. But remember — cron jobs run in fresh sessions without conversational memory. To add personal context, bake it directly into the prompt:
+If you have [memory](../user-guide/features/memory.md) enabled, you can store preferences that persist across sessions. But remember — cron jobs run in fresh sessions without conversational memory. To add personal context, bake it directly into the prompt:
 
 ```
 /cron add "0 8 * * *" "You are creating a briefing for a senior ML engineer who cares about: PyTorch ecosystem, transformer architectures, open-weight models, and AI regulation in the EU. Skip stories about product launches or funding rounds unless they involve open source.
@@ -261,11 +261,11 @@ sudo hermes gateway install --system
 
 You've built a working daily briefing bot. Here are some directions to explore next:
 
-- **[Scheduled Tasks (Cron)](/user-guide/features/cron)** — Full reference for schedule formats, repeat limits, and delivery options
-- **[Delegation](/user-guide/features/delegation)** — Deep dive into parallel sub-agent workflows
-- **[Messaging Platforms](/user-guide/messaging)** — Set up Telegram, Discord, or other delivery targets
-- **[Memory](/user-guide/features/memory)** — Persistent context across sessions
-- **[Tips & Best Practices](/guides/tips)** — More prompt engineering advice
+- **[Scheduled Tasks (Cron)](../user-guide/features/cron.md)** — Full reference for schedule formats, repeat limits, and delivery options
+- **[Delegation](../user-guide/features/delegation.md)** — Deep dive into parallel sub-agent workflows
+- **[Messaging Platforms](../user-guide/messaging/index.md)** — Set up Telegram, Discord, or other delivery targets
+- **[Memory](../user-guide/features/memory.md)** — Persistent context across sessions
+- **[Tips & Best Practices](./tips.md)** — More prompt engineering advice
 
 :::tip What else can you schedule?
 The briefing bot pattern works for anything: competitor monitoring, GitHub repo summaries, weather forecasts, portfolio tracking, server health checks, or even a daily joke. If you can describe it in a prompt, you can schedule it.
diff --git a/website/docs/guides/delegation-patterns.md b/website/docs/guides/delegation-patterns.md
index 0b72b96d70..91436915a0 100644
--- a/website/docs/guides/delegation-patterns.md
+++ b/website/docs/guides/delegation-patterns.md
@@ -8,7 +8,7 @@ description: "When and how to use subagent delegation — patterns for parallel
 
 Hermes can spawn isolated child agents to work on tasks in parallel. Each subagent gets its own conversation, terminal session, and toolset. Only the final summary comes back — intermediate tool calls never enter your context window.
 
-For the full feature reference, see [Subagent Delegation](/user-guide/features/delegation).
+For the full feature reference, see [Subagent Delegation](../user-guide/features/delegation.md).
 
 ---
 
@@ -239,4 +239,4 @@ delegation:
 
 ---
 
-*For the complete delegation reference — all parameters, ACP integration, and advanced configuration — see [Subagent Delegation](/user-guide/features/delegation).*
+*For the complete delegation reference — all parameters, ACP integration, and advanced configuration — see [Subagent Delegation](../user-guide/features/delegation.md).*
diff --git a/website/docs/guides/github-pr-review-agent.md b/website/docs/guides/github-pr-review-agent.md
index f45684973b..1d426a1bcb 100644
--- a/website/docs/guides/github-pr-review-agent.md
+++ b/website/docs/guides/github-pr-review-agent.md
@@ -34,7 +34,7 @@ If you have a public endpoint available, check out [Automated GitHub PR Comments
 
 ## Prerequisites
 
-- **Hermes Agent installed** — see the [Installation guide](/getting-started/installation)
+- **Hermes Agent installed** — see the [Installation guide](../getting-started/installation.md)
 - **Gateway running** for cron jobs:
   ```bash
   hermes gateway install   # Install as a service
@@ -50,7 +50,7 @@ If you have a public endpoint available, check out [Automated GitHub PR Comments
   # Authenticate
   gh auth login
   ```
-- **Messaging configured** (optional) — [Telegram](/user-guide/messaging/telegram) or [Discord](/user-guide/messaging/discord)
+- **Messaging configured** (optional) — [Telegram](../user-guide/messaging/telegram.md) or [Discord](../user-guide/messaging/discord.md)
 
 :::tip No messaging? No problem
 Use `deliver: "local"` to save reviews to `~/.hermes/cron/output/`. Great for testing before wiring up notifications.
@@ -297,7 +297,7 @@ GitHub allows 5,000 API requests/hour for authenticated users. Each PR review us
 ## What's Next?
 
 - **[Webhook-Based PR Reviews](./webhook-github-pr-review.md)** — get instant reviews when PRs are opened (requires a public endpoint)
-- **[Daily Briefing Bot](/guides/daily-briefing-bot)** — combine PR reviews with your morning news digest
-- **[Build a Plugin](/developer-guide/plugins)** — wrap the review logic into a shareable plugin
-- **[Profiles](/user-guide/profiles)** — run a dedicated reviewer profile with its own memory and config
-- **[Fallback Providers](/user-guide/features/fallback-providers)** — ensure reviews run even when one provider is down
+- **[Daily Briefing Bot](./daily-briefing-bot.md)** — combine PR reviews with your morning news digest
+- **[Build a Plugin](../developer-guide/plugins/index.md)** — wrap the review logic into a shareable plugin
+- **[Profiles](../user-guide/profiles.md)** — run a dedicated reviewer profile with its own memory and config
+- **[Fallback Providers](../user-guide/features/fallback-providers.md)** — ensure reviews run even when one provider is down
diff --git a/website/docs/guides/google-gemini.md b/website/docs/guides/google-gemini.md
index 80c122b572..064e202033 100644
--- a/website/docs/guides/google-gemini.md
+++ b/website/docs/guides/google-gemini.md
@@ -278,7 +278,7 @@ Upgrade Hermes and rerun `hermes model`. The native Gemini adapter sanitizes too
 
 ## Related
 
-- [AI Providers](/integrations/providers)
-- [Configuration](/user-guide/configuration)
-- [Fallback Providers](/user-guide/features/fallback-providers)
-- [AWS Bedrock](/guides/aws-bedrock) — native cloud-provider integration using AWS credentials
+- [AI Providers](../integrations/providers.md)
+- [Configuration](../user-guide/configuration.md)
+- [Fallback Providers](../user-guide/features/fallback-providers.md)
+- [AWS Bedrock](./aws-bedrock.md) — native cloud-provider integration using AWS credentials
diff --git a/website/docs/guides/google-vertex.md b/website/docs/guides/google-vertex.md
index 33bde3653b..fd8f08e461 100644
--- a/website/docs/guides/google-vertex.md
+++ b/website/docs/guides/google-vertex.md
@@ -6,7 +6,7 @@ description: "Use Hermes Agent with Gemini on Google Cloud Vertex AI — OAuth2
 
 # Google Vertex AI
 
-Hermes Agent supports **Gemini models on Google Cloud Vertex AI** through Vertex's OpenAI-compatible endpoint. Unlike the [Google AI Studio provider](/guides/google-gemini) (which uses a static API key against `generativelanguage.googleapis.com`), Vertex gives you **enterprise-grade rate limits and GCP billing/credits**, and is the right choice when you want Gemini usage to draw on your Google Cloud account rather than an AI Studio key.
+Hermes Agent supports **Gemini models on Google Cloud Vertex AI** through Vertex's OpenAI-compatible endpoint. Unlike the [Google AI Studio provider](./google-gemini.md) (which uses a static API key against `generativelanguage.googleapis.com`), Vertex gives you **enterprise-grade rate limits and GCP billing/credits**, and is the right choice when you want Gemini usage to draw on your Google Cloud account rather than an AI Studio key.
 
 :::info Vertex authenticates with OAuth2, not an API key
 Vertex has **no static API key** for the standard endpoint. Every request needs a short-lived **OAuth2 access token** (≈1 hour TTL) minted from either a service-account JSON or Application Default Credentials (ADC). Hermes mints and **auto-refreshes** these tokens for you — you never paste a token by hand. This is why pasting a temporary token into a custom provider's `api_key` field does not work: it expires mid-session.
@@ -142,7 +142,7 @@ The service account (or your ADC identity) needs the `roles/aiplatform.user` rol
 
 ## Related
 
-- [Google Gemini (AI Studio)](/guides/google-gemini) — static-API-key Gemini without GCP
-- [AWS Bedrock](/guides/aws-bedrock) — another native cloud-provider integration
-- [AI Providers](/integrations/providers)
-- [Configuration](/user-guide/configuration)
+- [Google Gemini (AI Studio)](./google-gemini.md) — static-API-key Gemini without GCP
+- [AWS Bedrock](./aws-bedrock.md) — another native cloud-provider integration
+- [AI Providers](../integrations/providers.md)
+- [Configuration](../user-guide/configuration.md)
diff --git a/website/docs/guides/local-llm-on-mac.md b/website/docs/guides/local-llm-on-mac.md
index f35e8ef2cf..c2492651d6 100644
--- a/website/docs/guides/local-llm-on-mac.md
+++ b/website/docs/guides/local-llm-on-mac.md
@@ -9,7 +9,7 @@ description: "Set up a local OpenAI-compatible LLM server on macOS with llama.cp
 :::tip Desktop users: there's a one-click path
 On the Hermes desktop app, **Settings → Providers → Local Models** installs
 and manages a local llama.cpp server for you — model downloads, memory
-fitting, and context sizing included. See [Local Models](/user-guide/local-models).
+fitting, and context sizing included. See [Local Models](../user-guide/local-models.md).
 This guide is for manual setup: MLX, custom builds, or servers you want to
 run yourself.
 :::
diff --git a/website/docs/guides/local-ollama-setup.md b/website/docs/guides/local-ollama-setup.md
index 28dbf33f10..c3a46ed64d 100644
--- a/website/docs/guides/local-ollama-setup.md
+++ b/website/docs/guides/local-ollama-setup.md
@@ -9,7 +9,7 @@ description: "Step-by-step guide to running Hermes Agent entirely on your own ma
 :::tip Desktop users: there's a one-click path
 On the Hermes desktop app, **Settings → Providers → Local Models** installs
 and manages a local llama.cpp server for you — model downloads, memory
-fitting, and context sizing included. See [Local Models](/user-guide/local-models).
+fitting, and context sizing included. See [Local Models](../user-guide/local-models.md).
 This guide is for manual setup: Ollama specifically, CLI-first workflows,
 or servers you want to run yourself.
 :::
@@ -313,7 +313,7 @@ Models without tool-call support produce plain text instead of structured functi
 - **Hermes has auto-repair** — it detects malformed tool calls and attempts to fix them automatically.
 - **Set up a fallback** — if the local model fails 3 times, Hermes falls back to a cloud provider.
 
-If the model prints raw JSON like `{"name": "web_search", ...}` in its reply instead of actually running the tool, that's usually the *server*, not the model — tool calling isn't enabled or the tool-call format isn't parsed. See the per-server fix table in [Tool calls appear as text instead of executing](/integrations/providers#tool-calls-appear-as-text-instead-of-executing) (llama.cpp needs `--jinja`, vLLM needs `--enable-auto-tool-choice --tool-call-parser hermes`, and so on).
+If the model prints raw JSON like `{"name": "web_search", ...}` in its reply instead of actually running the tool, that's usually the *server*, not the model — tool calling isn't enabled or the tool-call format isn't parsed. See the per-server fix table in [Tool calls appear as text instead of executing](../integrations/providers.md#tool-calls-appear-as-text-instead-of-executing) (llama.cpp needs `--jinja`, vLLM needs `--enable-auto-tool-choice --tool-call-parser hermes`, and so on).
 
 ### Context window errors
 
diff --git a/website/docs/guides/manage-hermes-cloud-with-mcp.md b/website/docs/guides/manage-hermes-cloud-with-mcp.md
index e7906b19b5..c4eaab6401 100644
--- a/website/docs/guides/manage-hermes-cloud-with-mcp.md
+++ b/website/docs/guides/manage-hermes-cloud-with-mcp.md
@@ -6,9 +6,9 @@ description: "Connect Hermes Agent to the Nous Portal MCP server so your local a
 
 # Manage Hermes Cloud with MCP
 
-[Hermes Cloud](https://portal.nousresearch.com/cloud) runs hosted Hermes Agent instances for you. Normally you manage them from the `/agents` page in the [Nous Portal](/integrations/nous-portal). This guide connects your **local** Hermes Agent to the Portal's MCP server so you can manage those cloud instances by just asking — "list my cloud agents", "restart the stopped one", "what's it costing me" — without leaving your terminal.
+[Hermes Cloud](https://portal.nousresearch.com/cloud) runs hosted Hermes Agent instances for you. Normally you manage them from the `/agents` page in the [Nous Portal](../integrations/nous-portal.md). This guide connects your **local** Hermes Agent to the Portal's MCP server so you can manage those cloud instances by just asking — "list my cloud agents", "restart the stopped one", "what's it costing me" — without leaving your terminal.
 
-It's a standard [MCP](/user-guide/features/mcp) server hosted by Nous Research, gated by the same OAuth login you already use for the Portal. Once connected, Hermes gets two tools it can call on your behalf.
+It's a standard [MCP](../user-guide/features/mcp.md) server hosted by Nous Research, gated by the same OAuth login you already use for the Portal. Once connected, Hermes gets two tools it can call on your behalf.
 
 ## What you can do with it
 
@@ -28,7 +28,7 @@ Every call runs against **your** org with your Portal identity, and membership i
 
 ## Prerequisites
 
-- A [Nous Portal](/integrations/nous-portal) account with [Hermes Cloud](https://portal.nousresearch.com/cloud) access (at least one instance, or the ability to create one).
+- A [Nous Portal](../integrations/nous-portal.md) account with [Hermes Cloud](https://portal.nousresearch.com/cloud) access (at least one instance, or the ability to create one).
 - MCP support installed. If you used the standard install script it's already there; otherwise:
 
   ```bash
@@ -127,7 +127,7 @@ mcp_servers:
       include: [agents]
 ```
 
-Run `/reload-mcp` after changing the config. See [Use MCP with Hermes](/guides/use-mcp-with-hermes) for the full filtering model (`include`/`exclude`, `prompts`, `resources`).
+Run `/reload-mcp` after changing the config. See [Use MCP with Hermes](./use-mcp-with-hermes.md) for the full filtering model (`include`/`exclude`, `prompts`, `resources`).
 
 ## Troubleshooting
 
@@ -165,12 +165,12 @@ OAuth tokens refresh automatically, but if the Portal invalidates your session (
 
 ### Headless / SSH / remote host
 
-The OAuth browser callback runs on the machine where Hermes is running. On a remote host, forward the loopback port over SSH — the same pattern as any other OAuth login. See [OAuth over SSH / Remote Hosts](/guides/oauth-over-ssh).
+The OAuth browser callback runs on the machine where Hermes is running. On a remote host, forward the loopback port over SSH — the same pattern as any other OAuth login. See [OAuth over SSH / Remote Hosts](./oauth-over-ssh.md).
 
 ## See also
 
-- **[Nous Portal](/integrations/nous-portal)** — the subscription, models, and Tool Gateway behind the same login
-- **[Use MCP with Hermes](/guides/use-mcp-with-hermes)** — connecting and filtering MCP servers in general
-- **[MCP feature overview](/user-guide/features/mcp)** — what MCP is and how Hermes uses it
-- **[MCP configuration reference](/reference/mcp-config-reference)** — every `mcp_servers` field, including `auth: oauth`
-- **[OAuth over SSH](/guides/oauth-over-ssh)** — logging in from remote or browser-only environments
+- **[Nous Portal](../integrations/nous-portal.md)** — the subscription, models, and Tool Gateway behind the same login
+- **[Use MCP with Hermes](./use-mcp-with-hermes.md)** — connecting and filtering MCP servers in general
+- **[MCP feature overview](../user-guide/features/mcp.md)** — what MCP is and how Hermes uses it
+- **[MCP configuration reference](../reference/mcp-config-reference.md)** — every `mcp_servers` field, including `auth: oauth`
+- **[OAuth over SSH](./oauth-over-ssh.md)** — logging in from remote or browser-only environments
diff --git a/website/docs/guides/migrate-from-openclaw.md b/website/docs/guides/migrate-from-openclaw.md
index 3a729ee75f..d59080cc87 100644
--- a/website/docs/guides/migrate-from-openclaw.md
+++ b/website/docs/guides/migrate-from-openclaw.md
@@ -13,7 +13,7 @@ Coming from **Claude Code** or **OpenAI Codex CLI** instead? Use [`hermes import
 :::
 
 :::tip
-If your OpenClaw setup was multi-provider, `hermes setup --portal` collapses it to one OAuth — 300+ models plus the Tool Gateway in a single login. See [Nous Portal](/integrations/nous-portal).
+If your OpenClaw setup was multi-provider, `hermes setup --portal` collapses it to one OAuth — 300+ models plus the Tool Gateway in a single login. See [Nous Portal](../integrations/nous-portal.md).
 :::
 
 ## Quick start
@@ -171,7 +171,7 @@ These are saved to `~/.hermes/migration/openclaw/<timestamp>/archive/` for manua
 | `HEARTBEAT.md` | `archive/workspace/HEARTBEAT.md` | Use cron jobs for periodic tasks |
 | `BOOTSTRAP.md` | `archive/workspace/BOOTSTRAP.md` | Use context files or skills |
 | Cron jobs | `archive/cron-config.json` | Recreate with `hermes cron create` |
-| Plugins | `archive/plugins-config.json` | See [plugins guide](/user-guide/features/hooks) |
+| Plugins | `archive/plugins-config.json` | See [plugins guide](../user-guide/features/hooks.md) |
 | Hooks/webhooks | `archive/hooks-config.json` | Use `hermes webhook` or gateway hooks |
 | Memory backend | `archive/memory-backend-config.json` | Configure via `hermes honcho` |
 | Skills registry | `archive/skills-registry-config.json` | Use `hermes skills config` |
diff --git a/website/docs/guides/operate-teams-meeting-pipeline.md b/website/docs/guides/operate-teams-meeting-pipeline.md
index 93c259cc15..674a3c1c77 100644
--- a/website/docs/guides/operate-teams-meeting-pipeline.md
+++ b/website/docs/guides/operate-teams-meeting-pipeline.md
@@ -5,7 +5,7 @@ description: "Runbook, go-live checklist, and operator worksheet for the Microso
 
 # Operate the Teams Meeting Pipeline
 
-Use this guide after you have already enabled the feature from [Teams Meetings](/user-guide/messaging/teams-meetings).
+Use this guide after you have already enabled the feature from [Teams Meetings](../user-guide/messaging/teams-meetings.md).
 
 This page covers:
 - operator CLI flows
@@ -291,5 +291,5 @@ Use this before changing the deployment:
 
 ## Related Docs
 
-- [Teams Meetings setup](/user-guide/messaging/teams-meetings)
-- [Microsoft Teams bot setup](/user-guide/messaging/teams)
+- [Teams Meetings setup](../user-guide/messaging/teams-meetings.md)
+- [Microsoft Teams bot setup](../user-guide/messaging/teams.md)
diff --git a/website/docs/guides/pipe-script-output.md b/website/docs/guides/pipe-script-output.md
index 1e750a7dac..6df59eeb7d 100644
--- a/website/docs/guides/pipe-script-output.md
+++ b/website/docs/guides/pipe-script-output.md
@@ -255,9 +255,9 @@ If you just need to pipe a raw string, reach for `hermes send`.
 
 ## Related
 
-- [Automate Anything with Cron](/guides/automate-with-cron) —
+- [Automate Anything with Cron](./automate-with-cron.md) —
   scheduled jobs whose output auto-delivers to any platform.
-- [Gateway Internals](/developer-guide/gateway-internals) —
+- [Gateway Internals](../developer-guide/gateway-internals.md) —
   the delivery router that `hermes send` shares with cron delivery.
-- [Messaging Platform Setup](/user-guide/messaging/) —
+- [Messaging Platform Setup](../user-guide/messaging/index.md) —
   one-time configuration for each platform.
diff --git a/website/docs/guides/run-nemotron-3-ultra-free.md b/website/docs/guides/run-nemotron-3-ultra-free.md
index db613e79e9..4239e05e37 100644
--- a/website/docs/guides/run-nemotron-3-ultra-free.md
+++ b/website/docs/guides/run-nemotron-3-ultra-free.md
@@ -113,11 +113,11 @@ Already set up with another model?
 
 - **Don't see the model in the list?** Make sure you finished the Nous Portal connection and that you're on the **Free** plan. In the CLI, `hermes portal info` confirms you're logged in and routing through Nous.
 - **Picked the wrong variant?** Re-select `nvidia/nemotron-3-ultra:free` — the `:free` suffix is required to stay on the no-cost tier.
-- **Browser didn't open / you're on a remote host (CLI)?** See [OAuth over SSH / Remote Hosts](/guides/oauth-over-ssh) for port-forwarding workarounds.
+- **Browser didn't open / you're on a remote host (CLI)?** See [OAuth over SSH / Remote Hosts](./oauth-over-ssh.md) for port-forwarding workarounds.
 
 ## See also
 
-- **[Desktop App](/user-guide/desktop)** — The native one-click app (macOS, Windows, Linux)
-- **[Run Hermes Agent with Nous Portal](/guides/run-hermes-with-nous-portal)** — Full Portal walkthrough: models, Tool Gateway, and verification
-- **[Nous Portal integration](/integrations/nous-portal)** — What's in the subscription
-- **[Quickstart](/getting-started/quickstart)** — Install-to-chat in under 5 minutes
+- **[Desktop App](../user-guide/desktop.md)** — The native one-click app (macOS, Windows, Linux)
+- **[Run Hermes Agent with Nous Portal](./run-hermes-with-nous-portal.md)** — Full Portal walkthrough: models, Tool Gateway, and verification
+- **[Nous Portal integration](../integrations/nous-portal.md)** — What's in the subscription
+- **[Quickstart](../getting-started/quickstart.md)** — Install-to-chat in under 5 minutes
diff --git a/website/docs/guides/secure-hermes-on-a-work-machine.md b/website/docs/guides/secure-hermes-on-a-work-machine.md
index 280f26b4bd..2f8d230b0c 100644
--- a/website/docs/guides/secure-hermes-on-a-work-machine.md
+++ b/website/docs/guides/secure-hermes-on-a-work-machine.md
@@ -8,7 +8,7 @@ description: "A security-posture walkthrough for running Hermes Agent on the mac
 
 You're about to run an agent on the machine you live on — a personal laptop or an employer-managed workstation. What's the safe posture?
 
-Short answer: the defaults already do most of the work. Hermes ships secure-by-default, with a defense-in-depth model covering command approval, file-write safety, and credential handling. This page walks through what's on out of the box, which knobs to tighten for a shared or work machine, and how to undo mistakes when they happen. Every control here is covered in depth in the [Security](/user-guide/security) guide.
+Short answer: the defaults already do most of the work. Hermes ships secure-by-default, with a defense-in-depth model covering command approval, file-write safety, and credential handling. This page walks through what's on out of the box, which knobs to tighten for a shared or work machine, and how to undo mistakes when they happen. Every control here is covered in depth in the [Security](../user-guide/security.md) guide.
 
 ## What the Defaults Already Protect
 
@@ -24,10 +24,10 @@ Fresh install, no configuration — these protections are active:
 
 **Secrets are redacted from output.** `security.redact_secrets` is on by default: patterns that look like API keys, tokens, and passwords in tool output are redacted before they enter the conversation context and logs.
 
-**Your data goes only where you point it.** API calls go **only to the LLM provider you configure**. Hermes Agent does not collect telemetry, usage data, or analytics. Your conversations, memory, and skills are stored locally in `~/.hermes/`. See the [FAQ](/reference/faq#is-my-data-sent-anywhere).
+**Your data goes only where you point it.** API calls go **only to the LLM provider you configure**. Hermes Agent does not collect telemetry, usage data, or analytics. Your conversations, memory, and skills are stored locally in `~/.hermes/`. See the [FAQ](../reference/faq.md#is-my-data-sent-anywhere).
 
 :::info
-There's more below the surface — SSRF protection on all URL-capable tools, filtered environments for MCP subprocesses, prompt-injection scanning of context files. The [Security](/user-guide/security) page documents every layer.
+There's more below the surface — SSRF protection on all URL-capable tools, filtered environments for MCP subprocesses, prompt-injection scanning of context files. The [Security](../user-guide/security.md) page documents every layer.
 :::
 
 ## Tightening for a Shared or Work Machine
@@ -57,7 +57,7 @@ approvals:
     - "dd if=* of=/dev/*"
 ```
 
-Patterns are case-insensitive [fnmatch](https://docs.python.org/3/library/fnmatch.html) globs matched against the whole command text, and matching runs over the same normalized/deobfuscated variants the dangerous-pattern detector uses, so simple quoting tricks don't slip past a rule. Always quote patterns — a bare leading `*` is a YAML parse error. Changes take effect immediately, no restart needed. Details: [User-Defined Deny Rules](/user-guide/security#user-defined-deny-rules-approvalsdeny).
+Patterns are case-insensitive [fnmatch](https://docs.python.org/3/library/fnmatch.html) globs matched against the whole command text, and matching runs over the same normalized/deobfuscated variants the dangerous-pattern detector uses, so simple quoting tricks don't slip past a rule. Always quote patterns — a bare leading `*` is a YAML parse error. Changes take effect immediately, no restart needed. Details: [User-Defined Deny Rules](../user-guide/security.md#user-defined-deny-rules-approvalsdeny).
 
 ### Sandbox file writes
 
@@ -75,7 +75,7 @@ Don't add this to `~/.hermes/.env` casually. If you set it to a project director
 
 ### Move command execution off the host
 
-The strongest isolation is not running commands on your machine at all. The terminal tool supports multiple [backends](/user-guide/features/tools#terminal-backends):
+The strongest isolation is not running commands on your machine at all. The terminal tool supports multiple [backends](../user-guide/features/tools.md#terminal-backends):
 
 | Backend | Isolation |
 |---------|-----------|
@@ -92,11 +92,11 @@ terminal:
 
 Every Docker container runs with hardened settings — all Linux capabilities dropped (with a minimal add-back set), `no-new-privileges`, a process-count limit, and size-limited tmpfs mounts. With a container backend, destructive commands inside the container can't harm the host, which is why dangerous-command checks are skipped there.
 
-For `ssh`, set `terminal.backend: ssh` in `config.yaml` and provide host details via `TERMINAL_SSH_HOST`, `TERMINAL_SSH_USER`, and `TERMINAL_SSH_KEY` in `~/.hermes/.env`. See [Network Isolation](/user-guide/security#network-isolation).
+For `ssh`, set `terminal.backend: ssh` in `config.yaml` and provide host details via `TERMINAL_SSH_HOST`, `TERMINAL_SSH_USER`, and `TERMINAL_SSH_KEY` in `~/.hermes/.env`. See [Network Isolation](../user-guide/security.md#network-isolation).
 
 ### If messaging is on: allowlists and pairing
 
-Running the [gateway](/user-guide/security#user-authorization-gateway) on this machine? The default is already deny: if no allowlists are configured and `GATEWAY_ALLOW_ALL_USERS` is not set, **all users are denied**. Keep it explicit:
+Running the [gateway](../user-guide/security.md#user-authorization-gateway) on this machine? The default is already deny: if no allowlists are configured and `GATEWAY_ALLOW_ALL_USERS` is not set, **all users are denied**. Keep it explicit:
 
 ```bash
 # ~/.hermes/.env
@@ -108,7 +108,7 @@ Or use DM pairing instead of hardcoding IDs: unknown users receive a one-time pa
 
 ## The Undo Layer: Checkpoints and `/rollback`
 
-Approval gates prevent damage; [checkpoints](/user-guide/checkpoints-and-rollback) reverse it. When enabled, Hermes automatically snapshots your project before destructive operations — `write_file`, `patch`, and destructive terminal commands like `rm`, `mv`, `sed -i`, and `git reset` — into a shadow git store under `~/.hermes/checkpoints/store/`. Your real project `.git` is never touched.
+Approval gates prevent damage; [checkpoints](../user-guide/checkpoints-and-rollback.md) reverse it. When enabled, Hermes automatically snapshots your project before destructive operations — `write_file`, `patch`, and destructive terminal commands like `rm`, `mv`, `sed -i`, and `git reset` — into a shadow git store under `~/.hermes/checkpoints/store/`. Your real project `.git` is never touched.
 
 Checkpoints are opt-in. Enable per-session:
 
@@ -138,7 +138,7 @@ Preview with `/rollback diff <N>` before restoring, and combine checkpoints with
 
 ## What This Threat Model Is — and Isn't
 
-Be clear-eyed about what these controls defend against. As the [Security](/user-guide/security#user-defined-deny-rules-approvalsdeny) guide puts it:
+Be clear-eyed about what these controls defend against. As the [Security](../user-guide/security.md#user-defined-deny-rules-approvalsdeny) guide puts it:
 
 > Deny rules are a guardrail against an honest-but-wrong agent, the same threat model as the dangerous-pattern detector. They are not a sandbox against a deliberately adversarial process — for that, use an isolated backend (Docker, Modal) or an egress-restricted environment.
 
@@ -176,7 +176,7 @@ HERMES_WRITE_SAFE_ROOT=/path/to/project:/home/you/.hermes
 
 ## See Also
 
-- **[Security](/user-guide/security)** — the full defense-in-depth reference: every approval pattern, container hardening flags, gateway authorization, MCP credential filtering
-- **[Checkpoints & Rollback](/user-guide/checkpoints-and-rollback)** — configuration, store maintenance, and restore workflows
-- **[Tools & Toolsets](/user-guide/features/tools)** — all terminal backends and their configuration
-- **[Configuration](/user-guide/configuration)** — the complete `config.yaml` reference
+- **[Security](../user-guide/security.md)** — the full defense-in-depth reference: every approval pattern, container hardening flags, gateway authorization, MCP credential filtering
+- **[Checkpoints & Rollback](../user-guide/checkpoints-and-rollback.md)** — configuration, store maintenance, and restore workflows
+- **[Tools & Toolsets](../user-guide/features/tools.md)** — all terminal backends and their configuration
+- **[Configuration](../user-guide/configuration.md)** — the complete `config.yaml` reference
diff --git a/website/docs/guides/team-telegram-assistant.md b/website/docs/guides/team-telegram-assistant.md
index 3b168eb4ca..31218f3db3 100644
--- a/website/docs/guides/team-telegram-assistant.md
+++ b/website/docs/guides/team-telegram-assistant.md
@@ -24,7 +24,7 @@ A Telegram bot that:
 
 Before starting, make sure you have:
 
-- **Hermes Agent installed** on a server or VPS (not your laptop — the bot needs to stay running). Follow the [installation guide](/getting-started/installation) if you haven't yet.
+- **Hermes Agent installed** on a server or VPS (not your laptop — the bot needs to stay running). Follow the [installation guide](../getting-started/installation.md) if you haven't yet.
 - **A Telegram account** for yourself (the bot owner)
 - **An LLM provider configured** — at minimum, an API key for OpenAI, Anthropic, or another supported provider in `~/.hermes/.env`
 
@@ -291,7 +291,7 @@ Users can also change this per-session with the `/verbose` command in chat.
 
 Customize how the bot communicates by editing `~/.hermes/SOUL.md`:
 
-For a full guide, see [Use SOUL.md with Hermes](/guides/use-soul-with-hermes).
+For a full guide, see [Use SOUL.md with Hermes](./use-soul-with-hermes.md).
 
 ```markdown
 # Soul
@@ -428,13 +428,13 @@ hermes gateway stop && hermes gateway start
 
 You've got a working team Telegram assistant. Here are some next steps:
 
-- **[Security Guide](/user-guide/security)** — deep dive into authorization, container isolation, and command approval
-- **[Messaging Gateway](/user-guide/messaging)** — full reference for gateway architecture, session management, and chat commands
-- **[Telegram Setup](/user-guide/messaging/telegram)** — platform-specific details including voice messages and TTS
-- **[Scheduled Tasks](/user-guide/features/cron)** — advanced cron scheduling with delivery options and cron expressions
-- **[Context Files](/user-guide/features/context-files)** — AGENTS.md, SOUL.md, and .cursorrules for project knowledge
-- **[Personality](/user-guide/features/personality)** — built-in personality presets and custom persona definitions
-- **Add more platforms** — the same gateway can simultaneously run [Discord](/user-guide/messaging/discord), [Slack](/user-guide/messaging/slack), and [WhatsApp](/user-guide/messaging/whatsapp)
+- **[Security Guide](../user-guide/security.md)** — deep dive into authorization, container isolation, and command approval
+- **[Messaging Gateway](../user-guide/messaging/index.md)** — full reference for gateway architecture, session management, and chat commands
+- **[Telegram Setup](../user-guide/messaging/telegram.md)** — platform-specific details including voice messages and TTS
+- **[Scheduled Tasks](../user-guide/features/cron.md)** — advanced cron scheduling with delivery options and cron expressions
+- **[Context Files](../user-guide/features/context-files.md)** — AGENTS.md, SOUL.md, and .cursorrules for project knowledge
+- **[Personality](../user-guide/features/personality.md)** — built-in personality presets and custom persona definitions
+- **Add more platforms** — the same gateway can simultaneously run [Discord](../user-guide/messaging/discord.md), [Slack](../user-guide/messaging/slack.md), and [WhatsApp](../user-guide/messaging/whatsapp.md)
 
 ---
 
diff --git a/website/docs/guides/tips.md b/website/docs/guides/tips.md
index 03a8b55f19..5866aafdcc 100644
--- a/website/docs/guides/tips.md
+++ b/website/docs/guides/tips.md
@@ -9,7 +9,7 @@ description: "Practical advice to get the most out of Hermes Agent — prompt ti
 A quick-wins collection of practical tips that make you immediately more effective with Hermes Agent. Each section targets a different aspect — scan the headers and jump to what's relevant.
 
 :::tip Confused which model to pick?
-Run `hermes setup --portal` — you get 300+ models including Claude, GPT-5, and Gemini under one subscription. See [Nous Portal](/integrations/nous-portal).
+Run `hermes setup --portal` — you get 300+ models including Claude, GPT-5, and Gemini under one subscription. See [Nous Portal](../integrations/nous-portal.md).
 :::
 
 ---
@@ -84,7 +84,7 @@ Create an `AGENTS.md` in your project root with architecture decisions, coding c
 
 Want Hermes to have a stable default voice? Edit `~/.hermes/SOUL.md` (or `$HERMES_HOME/SOUL.md` if you use a custom Hermes home). Hermes now seeds a starter SOUL automatically and uses that global file as the instance-wide personality source.
 
-For a full walkthrough, see [Use SOUL.md with Hermes](/guides/use-soul-with-hermes).
+For a full walkthrough, see [Use SOUL.md with Hermes](./use-soul-with-hermes.md).
 
 ```markdown
 # Soul
@@ -152,7 +152,7 @@ Instead of running terminal commands one at a time, ask the agent to write a scr
 Use `/model` to switch models mid-session. Use a frontier model (Claude Sonnet/Opus, GPT-4o) for complex reasoning and architecture decisions. Switch to a faster model for simple tasks like formatting, renaming, or boilerplate generation. Keep in mind each switch resets the prompt cache (see above), so on long sessions it's often cheaper to start a fresh session on the other model than to bounce back and forth.
 
 :::tip
-Run `/usage` periodically to see your token consumption. Run `/insights` for a broader view of usage patterns over the last 30 days. To see what your *fixed* per-message cost is before any conversation — system prompt, skills index, memory, tool schemas — run [`hermes prompt-size`](/reference/cli-commands#hermes-prompt-size) (works offline).
+Run `/usage` periodically to see your token consumption. Run `/insights` for a broader view of usage patterns over the last 30 days. To see what your *fixed* per-message cost is before any conversation — system prompt, skills index, memory, tool schemas — run [`hermes prompt-size`](../reference/cli-commands.md#hermes-prompt-size) (works offline).
 :::
 
 ## Messaging Tips
diff --git a/website/docs/guides/troubleshooting-agent-quality.md b/website/docs/guides/troubleshooting-agent-quality.md
index 67a1095368..c102a49d96 100644
--- a/website/docs/guides/troubleshooting-agent-quality.md
+++ b/website/docs/guides/troubleshooting-agent-quality.md
@@ -18,7 +18,7 @@ Sometimes Hermes seems less sharp than it was yesterday, or forgets something yo
 
 - A plain `/model <name>` switch is **session-only** by default (unless `model.persist_switch_by_default: true` is set), so the model you're on may not match what's in `config.yaml`.
 - Changing the main model from the dashboard's Models page applies to **new sessions only** — an already-open chat keeps running whatever model it started with.
-- If you switched to a faster model for a simple task (a pattern [Tips & Best Practices](/guides/tips#choose-the-right-model) recommends), remember to switch back for complex reasoning work.
+- If you switched to a faster model for a simple task (a pattern [Tips & Best Practices](./tips.md#choose-the-right-model) recommends), remember to switch back for complex reasoning work.
 
 If the model is wrong, `/model <name>` fixes it for this session; add `--global` to persist the change to `config.yaml`. Note that a mid-session switch resets the prompt cache, so the next turn re-reads the conversation at full input price — on a long session it can be cheaper to start fresh on the right model.
 
@@ -72,7 +72,7 @@ providers:
 
 Ollama users: if you set a custom `num_ctx`, set the matching context length in Hermes — Ollama's `/api/show` reports the model's *maximum* context, not the effective `num_ctx` you configured. On a running gateway, edits to `model.context_length` or any `compression.*` key take effect on the next message — no restart needed.
 
-See [Context Length Detection](/integrations/providers#context-length-detection) for how auto-detection works and all override options.
+See [Context Length Detection](../integrations/providers.md#context-length-detection) for how auto-detection works and all override options.
 
 ## 4. "I told it something and it forgot" — the frozen memory snapshot
 
@@ -86,7 +86,7 @@ See [Context Length Detection](/integrations/providers#context-length-detection)
 Frozen snapshot in practice: "remember X" during a session means X is guaranteed available **next** session. Within the current session, the fact still exists in the conversation history itself — the agent forgets it only if that part of the conversation has since been compressed away (see step 7).
 :::
 
-See [Persistent Memory](/user-guide/features/memory#how-memory-appears-in-the-system-prompt) for the full mechanics.
+See [Persistent Memory](../user-guide/features/memory.md#how-memory-appears-in-the-system-prompt) for the full mechanics.
 
 ## 5. Memory is bounded and curated — not a transcript
 
@@ -98,7 +98,7 @@ See [Persistent Memory](/user-guide/features/memory#how-memory-appears-in-the-sy
 
 For "did we discuss X last week?" recall, the agent has a separate mechanism: `session_search` queries all past sessions (stored in SQLite with full-text search) and can find things discussed weeks ago even when they're not in active memory. Just ask — "search our past sessions for the deploy discussion."
 
-You can also help directly: say "remember this for next time" after a productive session, or "clean up your memory" when it's near capacity so the agent consolidates entries. See [Memory & Skills tips](/guides/tips#memory--skills) and [Capacity Management](/user-guide/features/memory#capacity-management).
+You can also help directly: say "remember this for next time" after a productive session, or "clean up your memory" when it's near capacity so the agent consolidates entries. See [Memory & Skills tips](./tips.md#memory--skills) and [Capacity Management](../user-guide/features/memory.md#capacity-management).
 
 ## 6. Check that skills and tools are loaded
 
@@ -128,7 +128,7 @@ You can also help directly: say "remember this for next time" after a productive
 
 If a compressed-away detail matters, ask the agent to search for it (`session_search` reaches the archived turns), or re-paste the key facts into the conversation.
 
-See [Context Compression](/user-guide/configuration#context-compression) for the full settings reference and [Auto-Lineage on Compression](/user-guide/sessions#auto-lineage-on-compression) for how titled sessions chain.
+See [Context Compression](../user-guide/configuration.md#context-compression) for the full settings reference and [Auto-Lineage on Compression](../user-guide/sessions.md#auto-lineage-on-compression) for how titled sessions chain.
 
 ---
 
diff --git a/website/docs/guides/use-mcp-with-hermes.md b/website/docs/guides/use-mcp-with-hermes.md
index f4aaadcb51..c614acb400 100644
--- a/website/docs/guides/use-mcp-with-hermes.md
+++ b/website/docs/guides/use-mcp-with-hermes.md
@@ -541,6 +541,6 @@ Not-great first servers:
 
 ## Related docs
 
-- [MCP (Model Context Protocol)](/user-guide/features/mcp)
-- [FAQ](/reference/faq)
-- [Slash Commands](/reference/slash-commands)
+- [MCP (Model Context Protocol)](../user-guide/features/mcp.md)
+- [FAQ](../reference/faq.md)
+- [Slash Commands](../reference/slash-commands.md)
diff --git a/website/docs/guides/use-soul-with-hermes.md b/website/docs/guides/use-soul-with-hermes.md
index 5d3d3b7698..3f55d0758b 100644
--- a/website/docs/guides/use-soul-with-hermes.md
+++ b/website/docs/guides/use-soul-with-hermes.md
@@ -260,7 +260,7 @@ Move project instructions into `AGENTS.md` and keep `SOUL.md` focused on identit
 
 ## Related docs
 
-- [Personality & SOUL.md](/user-guide/features/personality)
-- [Context Files](/user-guide/features/context-files)
-- [Configuration](/user-guide/configuration)
-- [Tips & Best Practices](/guides/tips)
+- [Personality & SOUL.md](../user-guide/features/personality.md)
+- [Context Files](../user-guide/features/context-files.md)
+- [Configuration](../user-guide/configuration.md)
+- [Tips & Best Practices](./tips.md)
diff --git a/website/docs/guides/use-voice-mode-with-hermes.md b/website/docs/guides/use-voice-mode-with-hermes.md
index 996f0167b0..b9cca2a4aa 100644
--- a/website/docs/guides/use-voice-mode-with-hermes.md
+++ b/website/docs/guides/use-voice-mode-with-hermes.md
@@ -6,12 +6,12 @@ description: "A practical guide to setting up and using Hermes voice mode across
 
 # Use Voice Mode with Hermes
 
-This guide is the practical companion to the [Voice Mode feature reference](/user-guide/features/voice-mode).
+This guide is the practical companion to the [Voice Mode feature reference](../user-guide/features/voice-mode.md).
 
 If the feature page explains what voice mode can do, this guide shows how to actually use it well.
 
 :::tip
-[Nous Portal](/integrations/nous-portal) bundles both the LLM and TTS through one OAuth — voice mode works end-to-end with no extra credentials.
+[Nous Portal](../integrations/nous-portal.md) bundles both the LLM and TTS through one OAuth — voice mode works end-to-end with no extra credentials.
 :::
 
 ## What voice mode is good for
@@ -466,8 +466,8 @@ That progression keeps the debugging surface small.
 
 ## Where to read next
 
-- [Voice Mode feature reference](/user-guide/features/voice-mode)
-- [Messaging Gateway](/user-guide/messaging)
-- [Discord setup](/user-guide/messaging/discord)
-- [Telegram setup](/user-guide/messaging/telegram)
-- [Configuration](/user-guide/configuration)
+- [Voice Mode feature reference](../user-guide/features/voice-mode.md)
+- [Messaging Gateway](../user-guide/messaging/index.md)
+- [Discord setup](../user-guide/messaging/discord.md)
+- [Telegram setup](../user-guide/messaging/telegram.md)
+- [Configuration](../user-guide/configuration.md)
diff --git a/website/docs/guides/webhook-github-pr-review.md b/website/docs/guides/webhook-github-pr-review.md
index 3f7ec74d2b..c875c7b9cd 100644
--- a/website/docs/guides/webhook-github-pr-review.md
+++ b/website/docs/guides/webhook-github-pr-review.md
@@ -16,7 +16,7 @@ If you don't have a public URL or just want to get started quickly, check out [B
 :::
 
 :::info Reference docs
-For the full webhook platform reference (all config options, delivery types, dynamic subscriptions, security model) see [Webhooks](/user-guide/messaging/webhooks).
+For the full webhook platform reference (all config options, delivery types, dynamic subscriptions, security model) see [Webhooks](../user-guide/messaging/webhooks.md).
 :::
 
 :::warning Prompt injection risk
@@ -88,7 +88,7 @@ platforms:
 | `deliver_extra.pr_number` | Resolves to the PR number from the payload. |
 
 :::note The payload does not contain code
-The GitHub webhook payload includes PR metadata (title, description, branch names, URLs) but **not the diff**. The prompt above instructs the agent to run `gh pr diff` to fetch the actual changes. The default `hermes-webhook` toolset is deliberately constrained (web search/extract, vision, clarify — **no terminal**) because webhook payloads can carry untrusted content. To let this route run `gh`, add a per-route toolset grant: `toolsets: ["terminal", "web"]` on the route config — see [Per-route toolsets](/docs/user-guide/messaging/webhooks#per-route-toolsets).
+The GitHub webhook payload includes PR metadata (title, description, branch names, URLs) but **not the diff**. The prompt above instructs the agent to run `gh pr diff` to fetch the actual changes. The default `hermes-webhook` toolset is deliberately constrained (web search/extract, vision, clarify — **no terminal**) because webhook payloads can carry untrusted content. To let this route run `gh`, add a per-route toolset grant: `toolsets: ["terminal", "web"]` on the route config — see [Per-route toolsets](../user-guide/messaging/webhooks.md#per-route-toolsets).
 :::
 
 ---
@@ -204,7 +204,7 @@ For high-volume repositories, you can still filter upstream with a GitHub Action
 
 ## Using a skill for consistent review style
 
-Load a [Hermes skill](/user-guide/features/skills) to give the agent a consistent review persona. Add `skills` to your route inside `platforms.webhook.extra.routes` in `config.yaml`:
+Load a [Hermes skill](../user-guide/features/skills.md) to give the agent a consistent review persona. Add `skills` to your route inside `platforms.webhook.extra.routes` in `config.yaml`:
 
 ```yaml
 platforms:
@@ -331,6 +331,6 @@ platforms:
 ## What's Next?
 
 - **[Cron-Based PR Reviews](./github-pr-review-agent.md)** — poll for PRs on a schedule, no public endpoint needed
-- **[Webhook Reference](/user-guide/messaging/webhooks)** — full config reference for the webhook platform
-- **[Build a Plugin](/developer-guide/plugins)** — package review logic into a shareable plugin
-- **[Profiles](/user-guide/profiles)** — run a dedicated reviewer profile with its own memory and config
+- **[Webhook Reference](../user-guide/messaging/webhooks.md)** — full config reference for the webhook platform
+- **[Build a Plugin](../developer-guide/plugins/index.md)** — package review logic into a shareable plugin
+- **[Profiles](../user-guide/profiles.md)** — run a dedicated reviewer profile with its own memory and config
diff --git a/website/docs/guides/work-with-skills.md b/website/docs/guides/work-with-skills.md
index 2a011a2b7b..59b81b6321 100644
--- a/website/docs/guides/work-with-skills.md
+++ b/website/docs/guides/work-with-skills.md
@@ -8,7 +8,7 @@ description: "Find, install, use, and create skills — on-demand knowledge that
 
 Skills are on-demand knowledge documents that teach Hermes how to handle specific tasks — from generating ASCII art to managing GitHub PRs. This guide walks you through using them day to day.
 
-For the full technical reference, see [Skills System](/user-guide/features/skills).
+For the full technical reference, see [Skills System](../user-guide/features/skills.md).
 
 ---
 
@@ -135,7 +135,7 @@ skill_view("writing-plans")
 
 Plugin skills are **not** listed in the system prompt and don't appear in `skills_list`. They're opt-in — load them explicitly when you know a plugin provides one. When loaded, the agent sees a banner listing sibling skills from the same plugin.
 
-For how to ship skills in your own plugin, see [Build a Hermes Plugin → Bundle skills](/developer-guide/plugins#bundle-skills).
+For how to ship skills in your own plugin, see [Build a Hermes Plugin → Bundle skills](../developer-guide/plugins/index.md#bundle-skills).
 
 ---
 
@@ -287,4 +287,4 @@ Both are persistent across sessions, but they serve different purposes:
 
 ---
 
-*For the complete skills reference — frontmatter fields, conditional activation, external directories, and more — see [Skills System](/user-guide/features/skills).*
+*For the complete skills reference — frontmatter fields, conditional activation, external directories, and more — see [Skills System](../user-guide/features/skills.md).*
diff --git a/website/docs/index.mdx b/website/docs/index.mdx
index 0634bcdb84..430f708451 100644
--- a/website/docs/index.mdx
+++ b/website/docs/index.mdx
@@ -97,10 +97,10 @@ Run in powershell:
 iex (irm https://hermes-agent.nousresearch.com/install.ps1)
 ```
 
-See the full **[Installation Guide](/getting-started/installation)** for what the installer does, the per-user vs root layout, and Windows-specific notes. For the complete platform support matrix, see **[Platform Support](/getting-started/platform-support)**.
+See the full **[Installation Guide](./getting-started/installation.md)** for what the installer does, the per-user vs root layout, and Windows-specific notes. For the complete platform support matrix, see **[Platform Support](./getting-started/platform-support.md)**.
 
 :::tip Fastest path to a working agent
-After installing, run `hermes setup --portal` — one OAuth covers a model plus all four Tool Gateway tools (web search, image generation, TTS, browser). See [Nous Portal](/integrations/nous-portal).
+After installing, run `hermes setup --portal` — one OAuth covers a model plus all four Tool Gateway tools (web search, image generation, TTS, browser). See [Nous Portal](./integrations/nous-portal.md).
 :::
 
 ## What is Hermes Agent?
@@ -111,25 +111,25 @@ It's not a coding copilot tethered to an IDE or a chatbot wrapper around a singl
 
 |                                                                         |                                                                       |
 | ----------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| 🚀 **[Installation](/getting-started/installation)**                    | Install in 60 seconds on Linux, macOS, WSL2, native Windows, Nix & NixOS or Android |
-| 📖 **[Quickstart Tutorial](/getting-started/quickstart)**               | Your first conversation and key features to try                       |
-| 🗺️ **[Learning Path](/getting-started/learning-path)**                  | Find the right docs for your experience level                         |
-| ⚙️ **[Configuration](/user-guide/configuration)**                       | Config file, providers, models, and options                           |
-| 💬 **[Messaging Gateway](/user-guide/messaging)**                       | Set up Telegram, Discord, Slack, WhatsApp, Teams, or more             |
-| 🤖 **[Bot Mode](/user-guide/bot-mode)**                                | Named Bots with their own model, memory, skills, routines, and chats  |
-| 🔧 **[Tools & Toolsets](/user-guide/features/tools)**                   | 60+ built-in tools and how to configure them                          |
-| 🧠 **[Memory System](/user-guide/features/memory)**                     | Persistent memory that grows across sessions                          |
-| 📚 **[Skills System](/user-guide/features/skills)**                     | Procedural memory the agent creates and reuses                        |
-| 🔌 **[MCP Integration](/user-guide/features/mcp)**                      | Connect to MCP servers, filter their tools, and extend Hermes safely  |
-| 🧭 **[Use MCP with Hermes](/guides/use-mcp-with-hermes)**               | Practical MCP setup patterns, examples, and tutorials                 |
-| 🎙️ **[Voice Mode](/user-guide/features/voice-mode)**                    | Real-time voice interaction in CLI, Telegram, Discord, and Discord VC |
-| 🗣️ **[Use Voice Mode with Hermes](/guides/use-voice-mode-with-hermes)** | Hands-on setup and usage patterns for Hermes voice workflows          |
-| 🎭 **[Personality & SOUL.md](/user-guide/features/personality)**        | Define Hermes' default voice with a global SOUL.md                    |
-| 📄 **[Context Files](/user-guide/features/context-files)**              | Project context files that shape every conversation                   |
-| 🔒 **[Security](/user-guide/security)**                                 | Command approval, authorization, container isolation                  |
-| 💡 **[Tips & Best Practices](/guides/tips)**                            | Quick wins to get the most out of Hermes                              |
-| 🏗️ **[Architecture](/developer-guide/architecture)**                    | How it works under the hood                                           |
-| ❓ **[FAQ & Troubleshooting](/reference/faq)**                          | Common questions and solutions                                        |
+| 🚀 **[Installation](./getting-started/installation.md)**                    | Install in 60 seconds on Linux, macOS, WSL2, native Windows, Nix & NixOS or Android |
+| 📖 **[Quickstart Tutorial](./getting-started/quickstart.md)**               | Your first conversation and key features to try                       |
+| 🗺️ **[Learning Path](./getting-started/learning-path.md)**                  | Find the right docs for your experience level                         |
+| ⚙️ **[Configuration](./user-guide/configuration.md)**                       | Config file, providers, models, and options                           |
+| 💬 **[Messaging Gateway](./user-guide/messaging/index.md)**                       | Set up Telegram, Discord, Slack, WhatsApp, Teams, or more             |
+| 🤖 **[Bot Mode](./user-guide/bot-mode.md)**                                | Named Bots with their own model, memory, skills, routines, and chats  |
+| 🔧 **[Tools & Toolsets](./user-guide/features/tools.md)**                   | 60+ built-in tools and how to configure them                          |
+| 🧠 **[Memory System](./user-guide/features/memory.md)**                     | Persistent memory that grows across sessions                          |
+| 📚 **[Skills System](./user-guide/features/skills.md)**                     | Procedural memory the agent creates and reuses                        |
+| 🔌 **[MCP Integration](./user-guide/features/mcp.md)**                      | Connect to MCP servers, filter their tools, and extend Hermes safely  |
+| 🧭 **[Use MCP with Hermes](./guides/use-mcp-with-hermes.md)**               | Practical MCP setup patterns, examples, and tutorials                 |
+| 🎙️ **[Voice Mode](./user-guide/features/voice-mode.md)**                    | Real-time voice interaction in CLI, Telegram, Discord, and Discord VC |
+| 🗣️ **[Use Voice Mode with Hermes](./guides/use-voice-mode-with-hermes.md)** | Hands-on setup and usage patterns for Hermes voice workflows          |
+| 🎭 **[Personality & SOUL.md](./user-guide/features/personality.md)**        | Define Hermes' default voice with a global SOUL.md                    |
+| 📄 **[Context Files](./user-guide/features/context-files.md)**              | Project context files that shape every conversation                   |
+| 🔒 **[Security](./user-guide/security.md)**                                 | Command approval, authorization, container isolation                  |
+| 💡 **[Tips & Best Practices](./guides/tips.md)**                            | Quick wins to get the most out of Hermes                              |
+| 🏗️ **[Architecture](./developer-guide/architecture.md)**                    | How it works under the hood                                           |
+| ❓ **[FAQ & Troubleshooting](./reference/faq.md)**                          | Common questions and solutions                                        |
 
 ## Key Features
 
@@ -138,10 +138,10 @@ It's not a coding copilot tethered to an IDE or a chatbot wrapper around a singl
 - **Lives where you do** — CLI, Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost, Email, SMS, DingTalk, Feishu, WeCom, Weixin, QQ Bot, Yuanbao, BlueBubbles, Home Assistant, Microsoft Teams, Google Chat, and more — 20+ platforms from one gateway
 - **Built by model trainers** — Created by [Nous Research](https://nousresearch.com), the lab behind Hermes, Nomos, and Psyche. Works with [Nous Portal](https://portal.nousresearch.com), [OpenRouter](https://openrouter.ai), OpenAI, or any endpoint
 - **Scheduled automations** — Built-in cron with delivery to any platform
-- **[Bot Mode](/user-guide/bot-mode)** — Build a durable team of specialist Bots that work together in group chats and through `@mentions`
+- **[Bot Mode](./user-guide/bot-mode.md)** — Build a durable team of specialist Bots that work together in group chats and through `@mentions`
 - **Delegates & parallelizes** — Spawn isolated subagents for parallel workstreams. Programmatic Tool Calling via `execute_code` collapses multi-step pipelines into single inference calls
 - **Open standard skills** — Compatible with [agentskills.io](https://agentskills.io). Skills are portable, shareable, and community-contributed via the Skills Hub
-- **Full web control** — Search, extract, browse, vision, image generation, TTS — one subscription via [Nous Portal](/integrations/nous-portal) bundles all of them
+- **Full web control** — Search, extract, browse, vision, image generation, TTS — one subscription via [Nous Portal](./integrations/nous-portal.md) bundles all of them
 - **MCP support** — Connect to any MCP server for extended tool capabilities
 - **Research-ready** — Batch processing, trajectory export, RL training with Atropos. Built by [Nous Research](https://nousresearch.com) — the lab behind Hermes, Nomos, and Psyche models
 
diff --git a/website/docs/integrations/buzz.md b/website/docs/integrations/buzz.md
index c0514bf99e..32074ebb08 100644
--- a/website/docs/integrations/buzz.md
+++ b/website/docs/integrations/buzz.md
@@ -22,7 +22,7 @@ Hermes integrates with Buzz three ways. Pick by where Hermes runs and what you w
 
 Buzz Desktop ships Hermes as a preset runtime. With Hermes installed the normal way, open **Settings → Runtimes** and Hermes appears automatically — discovery resolves the `hermes-acp` launcher on your login-shell PATH, which the installer writes to `~/.local/bin` (and `hermes update` self-heals on older installs).
 
-Full setup, troubleshooting, and the security posture (Buzz auto-approves tool permissions — keep agents owner-only): **[ACP Host Integration → Buzz Desktop](/user-guide/features/acp#buzz-desktop)**
+Full setup, troubleshooting, and the security posture (Buzz auto-approves tool permissions — keep agents owner-only): **[ACP Host Integration → Buzz Desktop](../user-guide/features/acp.md#buzz-desktop)**
 
 ## ② Relay bridge (buzz-acp + ACP)
 
@@ -32,7 +32,7 @@ For a hosted Hermes identity that joins Buzz *channels* while Buzz's own harness
 Buzz relay <-- WebSocket --> buzz-acp <-- ACP over stdio --> Hermes Agent
 ```
 
-The spawned Hermes uses the same config, credentials, memory, and skills as `hermes` on that host. Key minting, channel discovery, owner-only telemetry (`BUZZ_ACP_RELAY_OBSERVER`), and headless-permission guidance: **[ACP Host Integration → Buzz channels (relay bridge)](/user-guide/features/acp#buzz-channels-relay-bridge)**
+The spawned Hermes uses the same config, credentials, memory, and skills as `hermes` on that host. Key minting, channel discovery, owner-only telemetry (`BUZZ_ACP_RELAY_OBSERVER`), and headless-permission guidance: **[ACP Host Integration → Buzz channels (relay bridge)](../user-guide/features/acp.md#buzz-channels-relay-bridge)**
 
 ## ③ Native gateway platform (recommended for full Hermes)
 
@@ -42,7 +42,7 @@ The bundled `buzz` platform plugin makes Buzz a normal Hermes messaging platform
 hermes gateway setup   # pick Buzz
 ```
 
-Full configuration reference (env vars, config.yaml, transport modes, access control): **[Messaging → Buzz](/user-guide/messaging/buzz)**
+Full configuration reference (env vars, config.yaml, transport modes, access control): **[Messaging → Buzz](../user-guide/messaging/buzz.md)**
 
 ## Which one should I use?
 
diff --git a/website/docs/integrations/index.md b/website/docs/integrations/index.md
index 370309310c..67feaf70de 100644
--- a/website/docs/integrations/index.md
+++ b/website/docs/integrations/index.md
@@ -9,20 +9,20 @@ sidebar_position: 0
 Hermes Agent connects to external systems for AI inference, tool servers, IDE workflows, programmatic access, and more. These integrations extend what Hermes can do and where it can run.
 
 :::tip Start here
-If you only have time to set up one integration, set up [Nous Portal](/integrations/nous-portal) — a single OAuth login covers 300+ models plus the four Tool Gateway tools (web search, image generation, TTS, and browser automation).
+If you only have time to set up one integration, set up [Nous Portal](./nous-portal.md) — a single OAuth login covers 300+ models plus the four Tool Gateway tools (web search, image generation, TTS, and browser automation).
 :::
 
 ## AI Providers & Routing
 
 Hermes supports multiple AI inference providers out of the box. Use `hermes model` to configure interactively, or set them in `config.yaml`.
 
-- **[AI Providers](/integrations/providers)** — OpenRouter, Anthropic, OpenAI, Google, and any OpenAI-compatible endpoint. Hermes auto-detects capabilities like vision, streaming, and tool use per provider.
-- **[Provider Routing](/user-guide/features/provider-routing)** — Fine-grained control over which underlying providers handle your OpenRouter requests. Optimize for cost, speed, or quality with sorting, whitelists, blacklists, and explicit priority ordering.
-- **[Fallback Providers](/user-guide/features/fallback-providers)** — Automatic failover to backup LLM providers when your primary model encounters errors. Includes primary model fallback and independent auxiliary task fallback for vision, compression, and web extraction.
+- **[AI Providers](./providers.md)** — OpenRouter, Anthropic, OpenAI, Google, and any OpenAI-compatible endpoint. Hermes auto-detects capabilities like vision, streaming, and tool use per provider.
+- **[Provider Routing](../user-guide/features/provider-routing.md)** — Fine-grained control over which underlying providers handle your OpenRouter requests. Optimize for cost, speed, or quality with sorting, whitelists, blacklists, and explicit priority ordering.
+- **[Fallback Providers](../user-guide/features/fallback-providers.md)** — Automatic failover to backup LLM providers when your primary model encounters errors. Includes primary model fallback and independent auxiliary task fallback for vision, compression, and web extraction.
 
 ## Tool Servers (MCP)
 
-- **[MCP Servers](/user-guide/features/mcp)** — Connect Hermes to external tool servers via Model Context Protocol. Access tools from GitHub, databases, file systems, browser stacks, internal APIs, and more without writing native Hermes tools. Supports both stdio and SSE transports, per-server tool filtering, and capability-aware resource/prompt registration.
+- **[MCP Servers](../user-guide/features/mcp.md)** — Connect Hermes to external tool servers via Model Context Protocol. Access tools from GitHub, databases, file systems, browser stacks, internal APIs, and more without writing native Hermes tools. Supports both stdio and SSE transports, per-server tool filtering, and capability-aware resource/prompt registration.
 
 ## Web Search Backends
 
@@ -56,7 +56,7 @@ Hermes includes full browser automation with multiple backend options for naviga
 - **Local Chromium-family CDP** — Connect to your running Chrome, Brave, Chromium, or Edge browser using `/browser connect`
 - **Local Chromium** — Headless local browser via the `agent-browser` CLI
 
-See [Browser Automation](/user-guide/features/browser) for setup and usage.
+See [Browser Automation](../user-guide/features/browser.md) for setup and usage.
 
 ## Voice & TTS Providers
 
@@ -71,28 +71,28 @@ Text-to-speech and speech-to-text across all messaging platforms:
 | **xAI TTS** | Good | Paid | `XAI_API_KEY` |
 | **NeuTTS** | Good | Free | None needed |
 
-Speech-to-text supports eight providers: local faster-whisper (free, runs on-device), a local command wrapper, Groq, OpenAI Whisper API, Mistral, xAI, ElevenLabs Scribe, and DeepInfra. Voice message transcription works across Telegram, Discord, WhatsApp, and other messaging platforms. See [Voice & TTS](/user-guide/features/tts) and [Voice Mode](/user-guide/features/voice-mode) for details.
+Speech-to-text supports eight providers: local faster-whisper (free, runs on-device), a local command wrapper, Groq, OpenAI Whisper API, Mistral, xAI, ElevenLabs Scribe, and DeepInfra. Voice message transcription works across Telegram, Discord, WhatsApp, and other messaging platforms. See [Voice & TTS](../user-guide/features/tts.md) and [Voice Mode](../user-guide/features/voice-mode.md) for details.
 
 ## IDE & Editor Integration
 
-- **[IDE Integration (ACP)](/user-guide/features/acp)** — Use Hermes Agent inside ACP-compatible editors such as VS Code, Zed, and JetBrains. Hermes runs as an ACP server, rendering chat messages, tool activity, file diffs, and terminal commands inside your editor.
+- **[IDE Integration (ACP)](../user-guide/features/acp.md)** — Use Hermes Agent inside ACP-compatible editors such as VS Code, Zed, and JetBrains. Hermes runs as an ACP server, rendering chat messages, tool activity, file diffs, and terminal commands inside your editor.
 
 ## Programmatic Access
 
-- **[API Server](/user-guide/features/api-server)** — Expose Hermes as an OpenAI-compatible HTTP endpoint. Any frontend that speaks the OpenAI format — Open WebUI, LobeChat, LibreChat, NextChat, ChatBox — can connect and use Hermes as a backend with its full toolset.
+- **[API Server](../user-guide/features/api-server.md)** — Expose Hermes as an OpenAI-compatible HTTP endpoint. Any frontend that speaks the OpenAI format — Open WebUI, LobeChat, LibreChat, NextChat, ChatBox — can connect and use Hermes as a backend with its full toolset.
 
 ## Memory & Personalization
 
-- **[Built-in Memory](/user-guide/features/memory)** — Persistent, curated memory via `MEMORY.md` and `USER.md` files. The agent maintains bounded stores of personal notes and user profile data that survive across sessions.
-- **[Memory Providers](/user-guide/features/memory-providers)** — Plug in external memory backends for deeper personalization. Eight providers are supported: Honcho (dialectic reasoning), OpenViking (tiered retrieval), Mem0 (cloud extraction), Hindsight (knowledge graphs), Holographic (local SQLite), RetainDB (hybrid search), ByteRover (CLI-based), and Supermemory.
+- **[Built-in Memory](../user-guide/features/memory.md)** — Persistent, curated memory via `MEMORY.md` and `USER.md` files. The agent maintains bounded stores of personal notes and user profile data that survive across sessions.
+- **[Memory Providers](../user-guide/features/memory-providers.md)** — Plug in external memory backends for deeper personalization. Eight providers are supported: Honcho (dialectic reasoning), OpenViking (tiered retrieval), Mem0 (cloud extraction), Hindsight (knowledge graphs), Holographic (local SQLite), RetainDB (hybrid search), ByteRover (CLI-based), and Supermemory.
 
 ## Messaging Platforms
 
 Hermes runs as a gateway bot on 27+ messaging platforms, all configured through the same `gateway` subsystem:
 
-- **[Telegram](/user-guide/messaging/telegram)**, **[Discord](/user-guide/messaging/discord)**, **[Slack](/user-guide/messaging/slack)**, **[WhatsApp](/user-guide/messaging/whatsapp)**, **[Signal](/user-guide/messaging/signal)**, **[Matrix](/user-guide/messaging/matrix)**, **[Mattermost](/user-guide/messaging/mattermost)**, **[Email](/user-guide/messaging/email)**, **[SMS](/user-guide/messaging/sms)**, **[DingTalk](/user-guide/messaging/dingtalk)**, **[Feishu/Lark](/user-guide/messaging/feishu)**, **[WeCom](/user-guide/messaging/wecom)**, **[WeCom Callback](/user-guide/messaging/wecom-callback)**, **[Weixin](/user-guide/messaging/weixin)**, **[BlueBubbles](/user-guide/messaging/bluebubbles)**, **[Buzz](/user-guide/messaging/buzz)**, **[QQ Bot](/user-guide/messaging/qqbot)**, **[Yuanbao](/user-guide/messaging/yuanbao)**, **[Home Assistant](/user-guide/messaging/homeassistant)**, **[Microsoft Teams](/user-guide/messaging/teams)**, **[Microsoft Teams Meetings](/user-guide/messaging/teams-meetings)**, **[Microsoft Graph Webhook](/user-guide/messaging/msgraph-webhook)**, **[Google Chat](/user-guide/messaging/google_chat)**, **[LINE](/user-guide/messaging/line)**, **[ntfy](/user-guide/messaging/ntfy)**, **[SimpleX](/user-guide/messaging/simplex)**, **[Open WebUI](/user-guide/messaging/open-webui)**, **[Webhooks](/user-guide/messaging/webhooks)**
+- **[Telegram](../user-guide/messaging/telegram.md)**, **[Discord](../user-guide/messaging/discord.md)**, **[Slack](../user-guide/messaging/slack.md)**, **[WhatsApp](../user-guide/messaging/whatsapp.md)**, **[Signal](../user-guide/messaging/signal.md)**, **[Matrix](../user-guide/messaging/matrix.md)**, **[Mattermost](../user-guide/messaging/mattermost.md)**, **[Email](../user-guide/messaging/email.md)**, **[SMS](../user-guide/messaging/sms.md)**, **[DingTalk](../user-guide/messaging/dingtalk.md)**, **[Feishu/Lark](../user-guide/messaging/feishu.md)**, **[WeCom](../user-guide/messaging/wecom.md)**, **[WeCom Callback](../user-guide/messaging/wecom-callback.md)**, **[Weixin](../user-guide/messaging/weixin.md)**, **[BlueBubbles](../user-guide/messaging/bluebubbles.md)**, **[Buzz](../user-guide/messaging/buzz.md)**, **[QQ Bot](../user-guide/messaging/qqbot.md)**, **[Yuanbao](../user-guide/messaging/yuanbao.md)**, **[Home Assistant](../user-guide/messaging/homeassistant.md)**, **[Microsoft Teams](../user-guide/messaging/teams.md)**, **[Microsoft Teams Meetings](../user-guide/messaging/teams-meetings.md)**, **[Microsoft Graph Webhook](../user-guide/messaging/msgraph-webhook.md)**, **[Google Chat](../user-guide/messaging/google_chat.md)**, **[LINE](../user-guide/messaging/line.md)**, **[ntfy](../user-guide/messaging/ntfy.md)**, **[SimpleX](../user-guide/messaging/simplex.md)**, **[Open WebUI](../user-guide/messaging/open-webui.md)**, **[Webhooks](../user-guide/messaging/webhooks.md)**
 
-See the [Messaging Gateway overview](/user-guide/messaging) for the platform comparison table and setup guide.
+See the [Messaging Gateway overview](../user-guide/messaging/index.md) for the platform comparison table and setup guide.
 
 ### Quick connect links
 
@@ -110,17 +110,17 @@ Each platform's setup page walks through what to do once you're there.
 
 ## Collaboration Workspaces
 
-- **[Buzz](/integrations/buzz)** — Block's Nostr-based human+agent workspace. Three integration paths: Buzz Desktop spawns Hermes as a managed ACP runtime, the `buzz-acp` relay bridge hosts a Hermes identity server-side, or the native gateway platform joins Buzz channels with full Hermes memory/skills/approvals/cron. The overview page compares all three.
+- **[Buzz](./buzz.md)** — Block's Nostr-based human+agent workspace. Three integration paths: Buzz Desktop spawns Hermes as a managed ACP runtime, the `buzz-acp` relay bridge hosts a Hermes identity server-side, or the native gateway platform joins Buzz channels with full Hermes memory/skills/approvals/cron. The overview page compares all three.
 
 ## Home Automation
 
-- **[Home Assistant](/user-guide/messaging/homeassistant)** — Control smart home devices via four dedicated tools (`ha_list_entities`, `ha_get_state`, `ha_list_services`, `ha_call_service`). The Home Assistant toolset activates automatically when `HASS_TOKEN` is configured.
+- **[Home Assistant](../user-guide/messaging/homeassistant.md)** — Control smart home devices via four dedicated tools (`ha_list_entities`, `ha_get_state`, `ha_list_services`, `ha_call_service`). The Home Assistant toolset activates automatically when `HASS_TOKEN` is configured.
 
 ## Plugins
 
-- **[Plugin System](/user-guide/features/plugins)** — Extend Hermes with custom tools, lifecycle hooks, and CLI commands without modifying core code. Plugins are discovered from `~/.hermes/plugins/`, project-local `.hermes/plugins/`, and pip-installed entry points.
-- **[Build a Plugin](/developer-guide/plugins)** — Step-by-step guide for creating Hermes plugins with tools, hooks, and CLI commands.
+- **[Plugin System](../user-guide/features/plugins.md)** — Extend Hermes with custom tools, lifecycle hooks, and CLI commands without modifying core code. Plugins are discovered from `~/.hermes/plugins/`, project-local `.hermes/plugins/`, and pip-installed entry points.
+- **[Build a Plugin](../developer-guide/plugins/index.md)** — Step-by-step guide for creating Hermes plugins with tools, hooks, and CLI commands.
 
 ## Training & Evaluation
 
-- **[Batch Processing](/user-guide/features/batch-processing)** — Run the agent across hundreds of prompts in parallel, generating structured ShareGPT-format trajectory data for training data generation or evaluation.
+- **[Batch Processing](../user-guide/features/batch-processing.md)** — Run the agent across hundreds of prompts in parallel, generating structured ShareGPT-format trajectory data for training data generation or evaluation.
diff --git a/website/docs/integrations/providers.md b/website/docs/integrations/providers.md
index 31db32c2be..da7ef399bb 100644
--- a/website/docs/integrations/providers.md
+++ b/website/docs/integrations/providers.md
@@ -64,7 +64,7 @@ Both built-in OpenCode providers send an opaque, per-conversation `x-opencode-se
 
 The two built-in OpenCode providers each pin their own relay on `opencode.ai` (`opencode-zen` → `/zen/v1`, `opencode-go` → `/zen/go/v1`). A `model.base_url` left behind by the other relay is healed to the selected provider's relay, and the model you pick (`-m`, `/model`, a fallback entry or a channel override) decides which relay is used — so switching from a Zen model to a Go-only one never sends the request to Zen. A custom provider you define under `providers:` whose name extends a family slug (for example `opencode-go-bridge`) still gets the family's per-model API-mode routing and `/v1` handling, but its `base_url` is taken as declared: name it after the relay it actually points at.
 
-For the official API-key path, see the dedicated [Google Gemini guide](/guides/google-gemini).
+For the official API-key path, see the dedicated [Google Gemini guide](../guides/google-gemini.md).
 
 :::tip Model key alias
 In the `model:` config section, you can use either `default:` or `model:` as the key name for your model ID. Both `model: { default: my-model }` and `model: { model: my-model }` work identically.
@@ -73,7 +73,7 @@ In the `model:` config section, you can use either `default:` or `model:` as the
 
 ### Nous Portal
 
-[Nous Portal](https://portal.nousresearch.com) is Nous Research's unified subscription gateway and **the recommended way to run Hermes Agent**. One OAuth login covers 300+ frontier agentic models (Claude, GPT, Gemini, DeepSeek, Qwen, Kimi, GLM, MiniMax, Grok, ...) plus the [Tool Gateway](/user-guide/features/tool-gateway) (web search, image generation, TTS, browser automation) — billed against your Nous subscription instead of separate per-provider accounts.
+[Nous Portal](https://portal.nousresearch.com) is Nous Research's unified subscription gateway and **the recommended way to run Hermes Agent**. One OAuth login covers 300+ frontier agentic models (Claude, GPT, Gemini, DeepSeek, Qwen, Kimi, GLM, MiniMax, Grok, ...) plus the [Tool Gateway](../user-guide/features/tool-gateway.md) (web search, image generation, TTS, browser automation) — billed against your Nous subscription instead of separate per-provider accounts.
 
 ```bash
 hermes setup --portal     # fresh install — OAuth + provider + gateway in one command
@@ -83,7 +83,7 @@ hermes portal info        # inspect login + routing at any time
 
 Don't have a subscription yet? Get one at [portal.nousresearch.com/manage-subscription](https://portal.nousresearch.com/manage-subscription).
 
-**For full details:** see the dedicated [Nous Portal integration page](/integrations/nous-portal) (what's in the subscription, model catalog, troubleshooting) and the step-by-step [Run Hermes Agent with Nous Portal guide](/guides/run-hermes-with-nous-portal).
+**For full details:** see the dedicated [Nous Portal integration page](./nous-portal.md) (what's in the subscription, model catalog, troubleshooting) and the step-by-step [Run Hermes Agent with Nous Portal guide](../guides/run-hermes-with-nous-portal.md).
 
 **Client identification.** Every Portal request from Hermes Agent carries a `client=hermes-client-v<version>` tag (e.g. `client=hermes-client-v0.13.0`) auto-aligned to your installed release. This is sent on all Portal pathways — main chat loop, auxiliary calls, compression summarizer, web extraction — and lets Portal-side telemetry distinguish Hermes traffic from other clients. No config required; the tag updates automatically when you `hermes update`.
 
@@ -112,11 +112,11 @@ Groups = x25519:secp256r1:secp384r1:x448
 :::
 
 :::warning
-Even when using Nous Portal, Codex, or a custom endpoint, some tools (vision, web summarization, MoA) use a separate "auxiliary" model. By default (`auxiliary.*.provider: "auto"`), Hermes routes these tasks to your **main chat model** — the same model you picked in `hermes model`. You can override each task individually to route it to a cheaper/faster model (e.g. Gemini Flash on OpenRouter) — see [Auxiliary Models](/user-guide/configuration#auxiliary-models).
+Even when using Nous Portal, Codex, or a custom endpoint, some tools (vision, web summarization, MoA) use a separate "auxiliary" model. By default (`auxiliary.*.provider: "auto"`), Hermes routes these tasks to your **main chat model** — the same model you picked in `hermes model`. You can override each task individually to route it to a cheaper/faster model (e.g. Gemini Flash on OpenRouter) — see [Auxiliary Models](../user-guide/configuration.md#auxiliary-models).
 :::
 
 :::tip Nous Tool Gateway
-Paid Nous Portal subscribers also get access to the **[Tool Gateway](/user-guide/features/tool-gateway)** — web search, image generation, TTS, and browser automation routed through your subscription. No extra API keys needed. On a fresh install, `hermes setup --portal` logs you in, sets Nous as your provider, and turns the gateway on in one command. Existing users can enable it from `hermes model` or per-tool from `hermes tools`. Inspect routing at any time with `hermes portal info`.
+Paid Nous Portal subscribers also get access to the **[Tool Gateway](../user-guide/features/tool-gateway.md)** — web search, image generation, TTS, and browser automation routed through your subscription. No extra API keys needed. On a fresh install, `hermes setup --portal` logs you in, sets Nous as your provider, and turns the gateway on in one command. Existing users can enable it from `hermes model` or per-tool from `hermes tools`. Inspect routing at any time with `hermes portal info`.
 :::
 
 ### Two Commands for Model Management
@@ -151,7 +151,7 @@ Several providers let you sign in to Hermes with a **consumer subscription** (Cl
 
 **xAI (SuperGrok / X Premium+).** Browser OAuth works with either an active SuperGrok subscription or an X Premium+ subscription on the linked X account, and the same bearer token is reused by direct-to-xAI tools (TTS, image gen, video gen, transcription, X Search). If inference returns `HTTP 403` after a successful login, that's a tier/entitlement restriction on xAI's side, not a stale token — the workaround is switching to an `XAI_API_KEY`. See [xAI (Grok)](#xai-grok--responses-api--prompt-caching) below and the [xAI Grok OAuth guide](../guides/xai-grok-oauth.md).
 
-**Google Gemini.** There is currently no way to sign in to Hermes with a consumer Gemini subscription — the `gemini` provider takes an API key, and [Google Vertex AI](#google-vertex-ai) bills to your GCP project. A billing-enabled Google Cloud project is recommended for agent use; free-tier quotas are too small for long-running agent sessions. See the [Google Gemini guide](/guides/google-gemini).
+**Google Gemini.** There is currently no way to sign in to Hermes with a consumer Gemini subscription — the `gemini` provider takes an API key, and [Google Vertex AI](#google-vertex-ai) bills to your GCP project. A billing-enabled Google Cloud project is recommended for agent use; free-tier quotas are too small for long-running agent sessions. See the [Google Gemini guide](../guides/google-gemini.md).
 
 :::tip One subscription instead of five
 If you'd rather not track per-provider plan semantics at all, [Nous Portal](#nous-portal) covers 300+ models under a single subscription with one OAuth login.
@@ -461,7 +461,7 @@ Authentication uses the standard boto3 chain: explicit `AWS_ACCESS_KEY_ID`/`AWS_
 
 Bedrock uses the **Converse API** under the hood — requests are translated to Bedrock's model-agnostic shape, so the same config works for Claude, Nova, DeepSeek, and Llama models. Set `BEDROCK_BASE_URL` only if you're calling a non-default regional endpoint.
 
-See the [AWS Bedrock guide](/guides/aws-bedrock) for a walkthrough of IAM setup, region selection, and cross-region inference.
+See the [AWS Bedrock guide](../guides/aws-bedrock.md) for a walkthrough of IAM setup, region selection, and cross-region inference.
 
 ### Google Vertex AI
 
@@ -486,7 +486,7 @@ vertex:
   region: "global"               # required for the Gemini 3.x previews
 ```
 
-`VERTEX_PROJECT_ID` / `VERTEX_REGION` env vars override the `config.yaml` values. Hermes lazy-installs `google-auth` on first use; run `hermes setup` if the managed install needs repair. See the [Google Vertex AI guide](/guides/google-vertex) for the full walkthrough, and the [Google Gemini guide](/guides/google-gemini) for the static-API-key AI Studio path instead.
+`VERTEX_PROJECT_ID` / `VERTEX_REGION` env vars override the `config.yaml` values. Hermes lazy-installs `google-auth` on first use; run `hermes setup` if the managed install needs repair. See the [Google Vertex AI guide](../guides/google-vertex.md) for the full walkthrough, and the [Google Gemini guide](../guides/google-gemini.md) for the static-API-key AI Studio path instead.
 
 ### Qwen Portal (OAuth)
 
@@ -557,7 +557,7 @@ model:
 Supported models: `MiniMax-M2.7` (main) and `MiniMax-M2.7-highspeed` (wired as the default auxiliary model). The OAuth path ignores `MINIMAX_API_KEY` / `MINIMAX_BASE_URL`.
 
 :::tip MiniMax OAuth vs API key
-`minimax-oauth` uses MiniMax's consumer-facing portal with OAuth login — no billing setup required. The `minimax` and `minimax-cn` providers use `MINIMAX_API_KEY` / `MINIMAX_CN_API_KEY` — for programmatic access. See the [MiniMax OAuth guide](/guides/minimax-oauth) for a full walkthrough.
+`minimax-oauth` uses MiniMax's consumer-facing portal with OAuth login — no billing setup required. The `minimax` and `minimax-cn` providers use `MINIMAX_API_KEY` / `MINIMAX_CN_API_KEY` — for programmatic access. See the [MiniMax OAuth guide](../guides/minimax-oauth.md) for a full walkthrough.
 :::
 
 ### NVIDIA NIM
@@ -1161,7 +1161,7 @@ model:
 
 **Possible causes:**
 1. **Low output limit on the server** — configure the server's generation default (for example SGLang's `--default-max-tokens`). Hermes does not expose an output-token cap setting. Response length is distinct from the conversation's context window (`context_length`).
-2. **Context exhaustion** — The model filled its context window. Increase `model.context_length` or enable [context compression](/user-guide/configuration#context-compression) in Hermes.
+2. **Context exhaustion** — The model filled its context window. Increase `model.context_length` or enable [context compression](../user-guide/configuration.md#context-compression) in Hermes.
 
 ---
 
@@ -1639,7 +1639,7 @@ provider_routing:
   #   "anthropic/claude-fable-5.1": {only: ["anthropic"]}
 ```
 
-**Shortcuts:** Append `:nitro` to any model name for throughput sorting (e.g., `anthropic/claude-sonnet-4:nitro`), or `:floor` for price sorting. Per-model details: [Provider Routing](/user-guide/features/provider-routing#per-model-overrides-models).
+**Shortcuts:** Append `:nitro` to any model name for throughput sorting (e.g., `anthropic/claude-sonnet-4:nitro`), or `:floor` for price sorting. Per-model details: [Provider Routing](../user-guide/features/provider-routing.md#per-model-overrides-models).
 
 ## OpenRouter Pareto Code Router
 
@@ -1660,7 +1660,7 @@ Notes:
 - Set to empty string (or remove the line) to let OpenRouter pick the strongest available coder — its documented behavior when the plugins block is omitted.
 - Selection is deterministic per score on a given day, but the actual model chosen can shift as the Pareto frontier moves (new models, benchmark updates).
 - See OpenRouter's [Pareto Router docs](https://openrouter.ai/docs/guides/routing/routers/pareto-router) for the full router behavior.
-- To use the Pareto Code router for a specific **auxiliary task** (compression, vision, etc.) instead of the main agent, set `extra_body.plugins` under that task — see [Auxiliary Models → OpenRouter routing & Pareto Code for auxiliary tasks](/user-guide/configuration#openrouter-routing--pareto-code-for-auxiliary-tasks).
+- To use the Pareto Code router for a specific **auxiliary task** (compression, vision, etc.) instead of the main agent, set `extra_body.plugins` under that task — see [Auxiliary Models → OpenRouter routing & Pareto Code for auxiliary tasks](../user-guide/configuration.md#openrouter-routing--pareto-code-for-auxiliary-tasks).
 
 ## Fallback Providers
 
@@ -1689,12 +1689,12 @@ When activated, the fallback swaps the model and provider mid-session without lo
 Supported providers: `openrouter`, `nous`, `novita`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `gemini`, `qwen-oauth`, `huggingface`, `zai`, `kimi-coding`, `kimi-coding-cn`, `minimax`, `minimax-cn`, `minimax-oauth`, `deepseek`, `nvidia`, `xai`, `xai-oauth`, `ollama-cloud`, `bedrock`, `ai-gateway`, `azure-foundry`, `opencode-zen`, `opencode-go`, `commandcode`, `commandcode-anthropic`, `kilocode`, `xiaomi`, `arcee`, `gmi`, `actual`, `stepfun`, `lmstudio`, `alibaba`, `alibaba-coding-plan`, `tencent-tokenhub`, `tencent-tokenplan`, `nebius-token-factory`, `router`, `custom`.
 
 :::tip
-Fallback is configured exclusively through `config.yaml` — or interactively via `hermes fallback`. For full details on when it triggers, how the chain advances, and how it interacts with auxiliary tasks and delegation, see [Fallback Providers](/user-guide/features/fallback-providers).
+Fallback is configured exclusively through `config.yaml` — or interactively via `hermes fallback`. For full details on when it triggers, how the chain advances, and how it interacts with auxiliary tasks and delegation, see [Fallback Providers](../user-guide/features/fallback-providers.md).
 :::
 
 ---
 
 ## See Also
 
-- [Configuration](/user-guide/configuration) — General configuration (directory structure, config precedence, terminal backends, memory, compression, and more)
-- [Environment Variables](/reference/environment-variables) — Complete reference of all environment variables
+- [Configuration](../user-guide/configuration.md) — General configuration (directory structure, config precedence, terminal backends, memory, compression, and more)
+- [Environment Variables](../reference/environment-variables.md) — Complete reference of all environment variables
diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.md
index 5cd0246734..4aa9fb5ed3 100644
--- a/website/docs/reference/cli-commands.md
+++ b/website/docs/reference/cli-commands.md
@@ -325,9 +325,9 @@ Subcommands:
 | `install` | Install as a systemd (Linux) or launchd (macOS) background service. |
 | `uninstall` | Remove the installed service. |
 | `setup` | Interactive messaging-platform setup. |
-| `migrate` | Move per-profile standalone gateways onto one multiplexed default gateway (`--multiplex`, the default) or roll back from the recorded manifest (`--standalone`). Runs a preflight (duplicate bot tokens, secondary port-binders without a `/p/<profile>/` ingress) and changes nothing when blocked. Flags: `--dry-run`, `-y`/`--yes`. See [Migrating from per-profile gateways](/user-guide/multi-profile-gateways#migrating-from-per-profile-gateways). |
+| `migrate` | Move per-profile standalone gateways onto one multiplexed default gateway (`--multiplex`, the default) or roll back from the recorded manifest (`--standalone`). Runs a preflight (duplicate bot tokens, secondary port-binders without a `/p/<profile>/` ingress) and changes nothing when blocked. Flags: `--dry-run`, `-y`/`--yes`. See [Migrating from per-profile gateways](../user-guide/multi-profile-gateways.md#migrating-from-per-profile-gateways). |
 | `migrate-legacy` | Remove legacy `hermes.service` units left over from pre-rename installs. Profile units (`hermes-gateway-<profile>.service`) and unrelated services are never touched. Flags: `--dry-run`, `-y`/`--yes`. |
-| `enroll` | Experimental: enroll this gateway with a relay connector and save relay credentials for connector-backed platforms. See [Hermes Relay](/user-guide/messaging/relay). |
+| `enroll` | Experimental: enroll this gateway with a relay connector and save relay credentials for connector-backed platforms. See [Hermes Relay](../user-guide/messaging/relay.md). |
 
 Options:
 
@@ -350,7 +350,7 @@ stopped.
 `hermes gateway enroll` accepts `--token`, `--connector-url`, `--gateway-id`, and `--wake-url`. It exchanges the enrollment token with the connector and writes the resulting `GATEWAY_RELAY_ID`, `GATEWAY_RELAY_SECRET`, `GATEWAY_RELAY_DELIVERY_KEY`, optional `GATEWAY_RELAY_URL`, and (when `--wake-url` is given) `GATEWAY_RELAY_WAKE_URL` values to the active profile's `.env`.
 
 :::tip WSL users
-Use `hermes gateway run` instead of `hermes gateway start` — WSL's systemd support is unreliable. Wrap it in tmux for persistence: `tmux new -s hermes 'hermes gateway run'`. See [WSL FAQ](/reference/faq#wsl-gateway-keeps-disconnecting-or-hermes-gateway-start-fails) for details.
+Use `hermes gateway run` instead of `hermes gateway start` — WSL's systemd support is unreliable. Wrap it in tmux for persistence: `tmux new -s hermes 'hermes gateway run'`. See [WSL FAQ](./faq.md#wsl-gateway-keeps-disconnecting-or-hermes-gateway-start-fails) for details.
 :::
 
 ## `hermes lsp`
@@ -377,7 +377,7 @@ Subcommands:
 | `restart` | Tear down running clients so the next edit re-spawns. |
 | `which <id>` | Print the resolved binary path for one server. |
 
-See [LSP — Semantic Diagnostics](/user-guide/features/lsp) for
+See [LSP — Semantic Diagnostics](../user-guide/features/lsp.md) for
 the full guide, supported languages, and configuration knobs.
 
 ## `hermes setup`
@@ -649,7 +649,7 @@ On-demand vulnerability scan against [OSV.dev](https://osv.dev). Covers the Herm
 
 ## `hermes auth`
 
-Manage credential pools for same-provider key rotation. See [Credential Pools](/user-guide/features/credential-pools) for full documentation.
+Manage credential pools for same-provider key rotation. See [Credential Pools](../user-guide/features/credential-pools.md) for full documentation.
 
 ```bash
 hermes auth                                              # Interactive wizard
@@ -724,7 +724,7 @@ Multi-profile, multi-project collaboration board. Each install can host many boa
 |------|---------|
 | `--board <slug>` | Operate on a specific board. Defaults to the current board (set via `hermes kanban boards switch`, the `HERMES_KANBAN_BOARD` env var, or `default`). |
 
-**This is the human / scripting surface.** Agent workers spawned by the dispatcher drive the board through a dedicated `kanban_*` [toolset](/user-guide/features/kanban#how-workers-interact-with-the-board) (`kanban_show`, `kanban_complete`, `kanban_request_review`, `kanban_request_changes`, `kanban_block`, `kanban_create`, `kanban_link`, `kanban_comment`, `kanban_heartbeat`; orchestrator profiles also get `kanban_list` and `kanban_unblock`) instead of shelling to `hermes kanban`. Workers have `HERMES_KANBAN_BOARD` pinned in their env so they physically cannot see other boards.
+**This is the human / scripting surface.** Agent workers spawned by the dispatcher drive the board through a dedicated `kanban_*` [toolset](../user-guide/features/kanban.md#how-workers-interact-with-the-board) (`kanban_show`, `kanban_complete`, `kanban_request_review`, `kanban_request_changes`, `kanban_block`, `kanban_create`, `kanban_link`, `kanban_comment`, `kanban_heartbeat`; orchestrator profiles also get `kanban_list` and `kanban_unblock`) instead of shelling to `hermes kanban`. Workers have `HERMES_KANBAN_BOARD` pinned in their env so they physically cannot see other boards.
 
 | Action | Purpose |
 |--------|---------|
@@ -755,7 +755,7 @@ Multi-profile, multi-project collaboration board. Each install can host many boa
 | `dispatch` | One dispatcher pass on the active board. Flags: `--dry-run`, `--max N`, `--failure-limit N`, `--json`. |
 | `context <id>` | Print the full context a worker would see (title + body + parent results + comments). |
 | `specify <id>` / `specify --all` | Flesh out a triage-column task into a concrete spec (title + body with goal, approach, acceptance criteria) via the auxiliary LLM, then promote it to `todo`. Flags: `--tenant` (scope `--all` to one tenant), `--author`, `--json`. Configure the model under `auxiliary.triage_specifier` in `config.yaml`. |
-| `decompose <id>` / `decompose --all` | Fan a triage-column task out into a graph of child tasks routed to specialist profiles by description. Falls back to specify-style single-task promotion when the LLM decides the task doesn't benefit from fan-out. Same flags as `specify`. Configure the decomposer model under `auxiliary.kanban_decomposer` in `config.yaml`; `kanban.orchestrator_profile` only controls who owns the root/orchestration task after fan-out. Also runs automatically every dispatcher tick when `kanban.auto_decompose: true` (the default). See [Auto vs Manual orchestration](/user-guide/features/kanban#auto-vs-manual-orchestration). |
+| `decompose <id>` / `decompose --all` | Fan a triage-column task out into a graph of child tasks routed to specialist profiles by description. Falls back to specify-style single-task promotion when the LLM decides the task doesn't benefit from fan-out. Same flags as `specify`. Configure the decomposer model under `auxiliary.kanban_decomposer` in `config.yaml`; `kanban.orchestrator_profile` only controls who owns the root/orchestration task after fan-out. Also runs automatically every dispatcher tick when `kanban.auto_decompose: true` (the default). See [Auto vs Manual orchestration](../user-guide/features/kanban.md#auto-vs-manual-orchestration). |
 | `gc` | Remove scratch workspaces for archived tasks. |
 
 Examples:
@@ -778,7 +778,7 @@ Board resolution order (highest precedence first): `--board <slug>` flag → `HE
 
 All actions are also available as a slash command in the gateway (`/kanban …`), with the same argument surface — including `boards` subcommands and the `--board` flag.
 
-For the full design — comparison with Cline Kanban / Paperclip / NanoClaw / Gemini Enterprise, eight collaboration patterns, four user stories, concurrency correctness proof — see the [Kanban user guide](/user-guide/features/kanban).
+For the full design — comparison with Cline Kanban / Paperclip / NanoClaw / Gemini Enterprise, eight collaboration patterns, four user stories, concurrency correctness proof — see the [Kanban user guide](../user-guide/features/kanban.md).
 
 ## `hermes egress`
 
@@ -1772,7 +1772,7 @@ Every successful import registers its source in `~/.hermes/import-sync.json`; `h
 hermes serve [options]
 ```
 
-Start the Hermes **backend server** — the JSON-RPC/WebSocket gateway the [desktop app](/user-guide/desktop) and remote clients connect to. It is the same server `hermes dashboard` runs, but **headless**: it never opens a browser UI. The desktop app launches its own `hermes serve` backend; use this command directly when you want a headless backend on a remote host. Accepts the same `--host` / `--port` / `--insecure` / `--skip-build` / `--stop` / `--status` options as `hermes dashboard` below (a non-loopback bind engages the same auth gate). Requires the `[web]` extra; the embedded Chat socket additionally needs `[pty]` on a POSIX host.
+Start the Hermes **backend server** — the JSON-RPC/WebSocket gateway the [desktop app](../user-guide/desktop.md) and remote clients connect to. It is the same server `hermes dashboard` runs, but **headless**: it never opens a browser UI. The desktop app launches its own `hermes serve` backend; use this command directly when you want a headless backend on a remote host. Accepts the same `--host` / `--port` / `--insecure` / `--skip-build` / `--stop` / `--status` options as `hermes dashboard` below (a non-loopback bind engages the same auth gate). Requires the `[web]` extra; the embedded Chat socket additionally needs `[pty]` on a POSIX host.
 
 **Port conflicts:** if the requested port (default `9119`) is already held by another process (e.g. a second `hermes serve` or the gateway), the command prints a machine-readable sentinel line `BACKEND_PORT_IN_USE port=<port>` to stdout, a human hint naming the likely holder, and exits with code **75** (`EX_TEMPFAIL`) instead of a generic error — so scripts and the desktop app can tell "port occupied" apart from "backend broken". Pass `--port 0` to bind a free ephemeral port (the successful boot announces the chosen port via `HERMES_BACKEND_READY port=<port>`).
 
@@ -1782,7 +1782,7 @@ Start the Hermes **backend server** — the JSON-RPC/WebSocket gateway the [desk
 hermes dashboard [options]
 ```
 
-Launch the web dashboard — a browser-based UI for managing configuration, API keys, and monitoring sessions. (For a headless backend with no browser UI — e.g. what the desktop app spawns — use [`hermes serve`](#hermes-serve) above.) Requires `cd ~/.hermes/hermes-agent && uv pip install -e ".[web]"` (FastAPI + Uvicorn). The embedded browser Chat tab is always available and additionally needs the `pty` extra (`cd ~/.hermes/hermes-agent && uv pip install -e ".[web,pty]"`) plus a POSIX PTY environment such as Linux, macOS, or WSL2. See [Web Dashboard](/user-guide/features/web-dashboard) for full documentation.
+Launch the web dashboard — a browser-based UI for managing configuration, API keys, and monitoring sessions. (For a headless backend with no browser UI — e.g. what the desktop app spawns — use [`hermes serve`](#hermes-serve) above.) Requires `cd ~/.hermes/hermes-agent && uv pip install -e ".[web]"` (FastAPI + Uvicorn). The embedded browser Chat tab is always available and additionally needs the `pty` extra (`cd ~/.hermes/hermes-agent && uv pip install -e ".[web,pty]"`) plus a POSIX PTY environment such as Linux, macOS, or WSL2. See [Web Dashboard](../user-guide/features/web-dashboard.md) for full documentation.
 
 | Option | Default | Description |
 |--------|---------|-------------|
diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/environment-variables.md
index 33a1b95648..7eb8b0398a 100644
--- a/website/docs/reference/environment-variables.md
+++ b/website/docs/reference/environment-variables.md
@@ -69,7 +69,7 @@ Hermes reads environment variables from the process environment and, for user-ma
 | `AZURE_CLIENT_SECRET` | Service principal secret used by `EnvironmentCredential` |
 | `AZURE_CLIENT_CERTIFICATE_PATH` | Service principal certificate (alternative to `AZURE_CLIENT_SECRET`) |
 | `AZURE_FEDERATED_TOKEN_FILE` | Federated token file path for AKS Workload Identity / OIDC flows |
-| `AZURE_AUTHORITY_HOST` | Sovereign-cloud authority override (e.g. `https://login.microsoftonline.us` for Azure Government). See [Azure Foundry guide](/guides/azure-foundry#sovereign-clouds-government-china) |
+| `AZURE_AUTHORITY_HOST` | Sovereign-cloud authority override (e.g. `https://login.microsoftonline.us` for Azure Government). See [Azure Foundry guide](../guides/azure-foundry.md#sovereign-clouds-government-china) |
 | `IDENTITY_ENDPOINT` / `MSI_ENDPOINT` | Managed Identity endpoint for App Service, Functions, and Container Apps; VMs usually use IMDS instead and do not set these |
 | `HF_TOKEN` | Hugging Face token for Inference Providers ([huggingface.co/settings/tokens](https://huggingface.co/settings/tokens)) |
 | `HF_BASE_URL` | Override Hugging Face base URL (default: `https://router.huggingface.co/v1`) |
@@ -189,7 +189,7 @@ For native Anthropic auth, Hermes prefers Claude Code's own credential files whe
 | `HINDSIGHT_API_URL` | Base URL for the Hindsight API (default: `https://api.hindsight.vectorize.io`) |
 | `HINDSIGHT_TIMEOUT` | Timeout in seconds for Hindsight memory-provider API calls (default: `60`). Bump this if your Hindsight instance is slow to respond during `/sync` or `on_session_switch` and you're seeing timeouts in `errors.log`. |
 | `MEM0_API_KEY` | Mem0 Platform API key for semantic persistent memory ([app.mem0.ai](https://app.mem0.ai)) |
-| `MEM0_MODE` | Mem0 backend mode: `platform` (default) or `oss` — see [Memory Providers](/user-guide/features/memory-providers) |
+| `MEM0_MODE` | Mem0 backend mode: `platform` (default) or `oss` — see [Memory Providers](../user-guide/features/memory-providers.md) |
 | `MEM0_HOST` | Base URL of a self-hosted Mem0 server (switches the plugin off the Platform API) |
 | `MEM0_USER_ID` | Override the user id Mem0 memories are stored under |
 | `MEM0_AGENT_ID` | Override the agent id Mem0 memories are tagged with |
@@ -218,7 +218,7 @@ Secrets consumed by specific bundled / optional skills. Each is only needed if y
 
 ### Langfuse Observability
 
-Environment variables for the bundled [`observability/langfuse`](/user-guide/features/built-in-plugins#observabilitylangfuse) plugin. Set these in `~/.hermes/.env`. The plugin must also be enabled (`hermes plugins enable observability/langfuse`, or check the box in `hermes plugins`) before any of these take effect.
+Environment variables for the bundled [`observability/langfuse`](../user-guide/features/built-in-plugins.md#observabilitylangfuse) plugin. Set these in `~/.hermes/.env`. The plugin must also be enabled (`hermes plugins enable observability/langfuse`, or check the box in `hermes plugins`) before any of these take effect.
 
 | Variable | Description |
 |----------|-------------|
@@ -234,7 +234,7 @@ Environment variables for the bundled [`observability/langfuse`](/user-guide/fea
 
 ### Nous Tool Gateway
 
-These variables configure the [Tool Gateway](/user-guide/features/tool-gateway) for paid Nous subscribers or self-hosted gateway deployments. Most users don't need to set these — the gateway is configured automatically via `hermes model` or `hermes tools`.
+These variables configure the [Tool Gateway](../user-guide/features/tool-gateway.md) for paid Nous subscribers or self-hosted gateway deployments. Most users don't need to set these — the gateway is configured automatically via `hermes model` or `hermes tools`.
 
 | Variable | Description |
 |----------|-------------|
@@ -548,7 +548,7 @@ These are set automatically by the Docker terminal backend when `proxy.enabled:
 | `API_SERVER_PORT` | Port for the API server (default: `8642`) |
 | `API_SERVER_HOST` | Host/bind address for the API server (default: `127.0.0.1`). `API_SERVER_KEY` is still required on loopback; use a narrow `API_SERVER_CORS_ORIGINS` allowlist for browser access. |
 | `API_SERVER_MODEL_NAME` | Model name advertised on `/v1/models`. Defaults to the profile name (or `hermes-agent` for the default profile). Useful for multi-user setups where frontends like Open WebUI need distinct model names per connection. |
-| `GATEWAY_PROXY_URL` | URL of a remote Hermes API server to forward messages to ([proxy mode](/user-guide/messaging/matrix#proxy-mode-e2ee-on-macos)). When set, the gateway handles platform I/O only — all agent work is delegated to the remote server. Also configurable via `gateway.proxy_url` in `config.yaml`. |
+| `GATEWAY_PROXY_URL` | URL of a remote Hermes API server to forward messages to ([proxy mode](../user-guide/messaging/matrix.md#proxy-mode-e2ee-on-macos)). When set, the gateway handles platform I/O only — all agent work is delegated to the remote server. Also configurable via `gateway.proxy_url` in `config.yaml`. |
 | `GATEWAY_PROXY_KEY` | Bearer token for authenticating with the remote API server in proxy mode. Must match `API_SERVER_KEY` on the remote host. |
 | `MESSAGING_CWD` | Deprecated compatibility fallback for gateway working directory. Prefer `terminal.cwd` in `config.yaml`. |
 | `GATEWAY_ALLOWED_USERS` | Comma-separated user IDs allowed across all platforms |
@@ -556,9 +556,9 @@ These are set automatically by the Docker terminal backend when `proxy.enabled:
 
 ### Web Dashboard & Hermes Desktop
 
-Auth for the [web dashboard](/user-guide/features/web-dashboard) and for connecting [Hermes Desktop to a remote backend](/user-guide/features/web-dashboard#connecting-hermes-desktop-to-a-remote-backend). Per the secrets-only convention, credentials belong in `~/.hermes/.env`; the OAuth `client_id` is better set under `dashboard.oauth` in `config.yaml` (env wins when set).
+Auth for the [web dashboard](../user-guide/features/web-dashboard.md) and for connecting [Hermes Desktop to a remote backend](../user-guide/features/web-dashboard.md#connecting-hermes-desktop-to-a-remote-backend). Per the secrets-only convention, credentials belong in `~/.hermes/.env`; the OAuth `client_id` is better set under `dashboard.oauth` in `config.yaml` (env wins when set).
 
-Three dashboard-auth providers ship in the box. For a remote Hermes Desktop connection or any internet-facing dashboard, the recommended provider is **OAuth (Nous Portal)** — set `HERMES_DASHBOARD_OAUTH_CLIENT_ID` (provision it with `hermes dashboard register`). The bundled **username/password** provider (`HERMES_DASHBOARD_BASIC_AUTH_*`) is the quickest option for a backend on a trusted LAN or behind a VPN, but is not suitable for direct public-internet exposure. To authenticate against your own identity provider, use the **self-hosted OIDC** provider (`HERMES_DASHBOARD_OIDC_*`). Either way, a non-loopback bind (`hermes dashboard --host 0.0.0.0`) engages the auth gate. See [Web Dashboard → Authentication](/user-guide/features/web-dashboard#authentication-gated-mode) for the full picture.
+Three dashboard-auth providers ship in the box. For a remote Hermes Desktop connection or any internet-facing dashboard, the recommended provider is **OAuth (Nous Portal)** — set `HERMES_DASHBOARD_OAUTH_CLIENT_ID` (provision it with `hermes dashboard register`). The bundled **username/password** provider (`HERMES_DASHBOARD_BASIC_AUTH_*`) is the quickest option for a backend on a trusted LAN or behind a VPN, but is not suitable for direct public-internet exposure. To authenticate against your own identity provider, use the **self-hosted OIDC** provider (`HERMES_DASHBOARD_OIDC_*`). Either way, a non-loopback bind (`hermes dashboard --host 0.0.0.0`) engages the auth gate. See [Web Dashboard → Authentication](../user-guide/features/web-dashboard.md#authentication-gated-mode) for the full picture.
 
 | Variable | Description |
 |----------|-------------|
@@ -583,7 +583,7 @@ Three dashboard-auth providers ship in the box. For a remote Hermes Desktop conn
 
 ### Microsoft Graph (Teams Meetings)
 
-App-only credentials for the Microsoft Graph REST client used by the upcoming Teams meeting summary pipeline. See [Register a Microsoft Graph application](/guides/microsoft-graph-app-registration) for the Azure portal walkthrough and the exact API permissions required.
+App-only credentials for the Microsoft Graph REST client used by the upcoming Teams meeting summary pipeline. See [Register a Microsoft Graph application](../guides/microsoft-graph-app-registration.md) for the Azure portal walkthrough and the exact API permissions required.
 
 | Variable | Description |
 |----------|-------------|
@@ -595,7 +595,7 @@ App-only credentials for the Microsoft Graph REST client used by the upcoming Te
 
 ### Microsoft Graph Webhook Listener
 
-Inbound change-notification listener for Graph events (Teams meetings, calendar, chat, etc.). See [Microsoft Graph Webhook Listener](/user-guide/messaging/msgraph-webhook) for setup and security hardening.
+Inbound change-notification listener for Graph events (Teams meetings, calendar, chat, etc.). See [Microsoft Graph Webhook Listener](../user-guide/messaging/msgraph-webhook.md) for setup and security hardening.
 
 | Variable | Description |
 |----------|-------------|
@@ -607,7 +607,7 @@ Inbound change-notification listener for Graph events (Teams meetings, calendar,
 
 ### Teams Meeting Summary Delivery
 
-Only used when the [`teams_pipeline` plugin](/user-guide/messaging/msgraph-webhook) is enabled. Settings are also configurable under `platforms.teams.extra` in `config.yaml` — env vars take priority when both are set. See [Microsoft Teams → Meeting Summary Delivery](/user-guide/messaging/teams#meeting-summary-delivery-teams-meeting-pipeline).
+Only used when the [`teams_pipeline` plugin](../user-guide/messaging/msgraph-webhook.md) is enabled. Settings are also configurable under `platforms.teams.extra` in `config.yaml` — env vars take priority when both are set. See [Microsoft Teams → Meeting Summary Delivery](../user-guide/messaging/teams.md#meeting-summary-delivery-teams-meeting-pipeline).
 
 | Variable | Description |
 |----------|-------------|
@@ -620,7 +620,7 @@ Only used when the [`teams_pipeline` plugin](/user-guide/messaging/msgraph-webho
 
 ### LINE Messaging API
 
-Used by the bundled LINE platform plugin (`plugins/platforms/line/`). See [Messaging Gateway → LINE](/user-guide/messaging/line) for full setup.
+Used by the bundled LINE platform plugin (`plugins/platforms/line/`). See [Messaging Gateway → LINE](../user-guide/messaging/line.md) for full setup.
 
 | Variable | Description |
 |----------|-------------|
@@ -657,11 +657,11 @@ Used by the bundled LINE platform plugin (`plugins/platforms/line/`). See [Messa
 | `NTFY_HOME_CHANNEL` | Default delivery target for cron jobs with `deliver: ntfy`. |
 | `NTFY_HOME_CHANNEL_NAME` | Human label for the home channel (defaults to the topic name). |
 
-See [the ntfy messaging guide](/user-guide/messaging/ntfy) — particularly the **identity model** section — before deploying with untrusted topics.
+See [the ntfy messaging guide](../user-guide/messaging/ntfy.md) — particularly the **identity model** section — before deploying with untrusted topics.
 
 ### IRC
 
-Connect Hermes to an IRC server. No external dependencies. See [the IRC messaging guide](/user-guide/messaging/irc).
+Connect Hermes to an IRC server. No external dependencies. See [the IRC messaging guide](../user-guide/messaging/irc.md).
 
 | Variable | Description |
 |----------|-------------|
@@ -678,7 +678,7 @@ Connect Hermes to an IRC server. No external dependencies. See [the IRC messagin
 
 ### SimpleX
 
-Connect Hermes to a [SimpleX Chat](https://simplex.chat/) network via a local `simplex-chat` daemon. See [the SimpleX messaging guide](/user-guide/messaging/simplex).
+Connect Hermes to a [SimpleX Chat](https://simplex.chat/) network via a local `simplex-chat` daemon. See [the SimpleX messaging guide](../user-guide/messaging/simplex.md).
 
 | Variable | Description |
 |----------|-------------|
@@ -692,7 +692,7 @@ Connect Hermes to a [SimpleX Chat](https://simplex.chat/) network via a local `s
 
 ### Photon
 
-Connect Hermes to [Photon](https://photon.codes/) / Spectrum (iMessage and other Spectrum platforms) via the Node sidecar. See [the Photon messaging guide](/user-guide/messaging/photon).
+Connect Hermes to [Photon](https://photon.codes/) / Spectrum (iMessage and other Spectrum platforms) via the Node sidecar. See [the Photon messaging guide](../user-guide/messaging/photon.md).
 
 | Variable | Description |
 |----------|-------------|
@@ -732,7 +732,7 @@ Connect Hermes to [Photon](https://photon.codes/) / Spectrum (iMessage and other
 
 ### Microsoft Teams (adapter)
 
-The Microsoft Teams platform adapter (Bot Framework / Azure AD), distinct from the [Microsoft Graph (Teams Meetings)](#microsoft-graph-teams-meetings) integration above. See [the Teams messaging guide](/user-guide/messaging/teams).
+The Microsoft Teams platform adapter (Bot Framework / Azure AD), distinct from the [Microsoft Graph (Teams Meetings)](#microsoft-graph-teams-meetings) integration above. See [the Teams messaging guide](../user-guide/messaging/teams.md).
 
 | Variable | Description |
 |----------|-------------|
@@ -938,7 +938,7 @@ fallback_providers:
 
 The older top-level `fallback_model` single-provider shape is still read for backward compatibility, but new configuration should use `fallback_providers`. For task-specific auxiliary policy, use `auxiliary.<task>.fallback_chain` in `config.yaml`; there is no environment variable equivalent.
 
-See [Fallback Providers](/user-guide/features/fallback-providers) for full details.
+See [Fallback Providers](../user-guide/features/fallback-providers.md) for full details.
 
 ## Provider Routing (config.yaml only)
 
diff --git a/website/docs/reference/faq.md b/website/docs/reference/faq.md
index b8f3caf82a..62fc20ec60 100644
--- a/website/docs/reference/faq.md
+++ b/website/docs/reference/faq.md
@@ -17,7 +17,7 @@ Quick answers and fixes for the most common questions and issues.
 Hermes Agent works with any OpenAI-compatible API. Supported providers include:
 
 - **[OpenRouter](https://openrouter.ai/)** — access hundreds of models through one API key (recommended for flexibility)
-- **[Nous Portal](/integrations/nous-portal)** — Nous Research's subscription gateway — 300+ models plus web/image/TTS/browser through one OAuth login (recommended for newcomers)
+- **[Nous Portal](../integrations/nous-portal.md)** — Nous Research's subscription gateway — 300+ models plus web/image/TTS/browser through one OAuth login (recommended for newcomers)
 - **OpenAI** — GPT-5.4, GPT-5-codex, GPT-4.1, GPT-4o, etc.
 - **Anthropic** — Claude models (direct API, OAuth via `hermes auth add anthropic`, OpenRouter, or any compatible proxy)
 - **Google** — Gemini models (direct API via `gemini` provider, OpenRouter, or compatible proxy)
@@ -228,7 +228,7 @@ To isolate the source:
 3. Retry in a fresh session with another configured model or provider. A refusal that changes with the model is model/provider behavior, not a Hermes execution control.
 4. If an explicit tool error appears, use its exact text when reporting the problem.
 
-See [Security](/user-guide/security) for Hermes' documented execution controls and [Providers](/integrations/providers) for provider configuration.
+See [Security](../user-guide/security.md) for Hermes' documented execution controls and [Providers](../integrations/providers.md) for provider configuration.
 
 #### `/model` only shows one provider / can't switch providers
 
@@ -532,7 +532,7 @@ hermes prompt-size
 /usage
 ```
 
-If the baseline looks high before you've typed anything, that's the fixed prompt budget — the system prompt plus tool schemas sent on every call. Run [`hermes prompt-size`](/reference/cli-commands#hermes-prompt-size) to measure it, then trim: disable toolsets you don't use (`hermes tools`) and uninstall or disable skills you don't need (`hermes skills`).
+If the baseline looks high before you've typed anything, that's the fixed prompt budget — the system prompt plus tool schemas sent on every call. Run [`hermes prompt-size`](./cli-commands.md#hermes-prompt-size) to measure it, then trim: disable toolsets you don't use (`hermes tools`) and uninstall or disable skills you don't need (`hermes skills`).
 
 :::tip
 Use `/compress` regularly during long sessions. It summarizes the conversation history and reduces token usage significantly while preserving context.
@@ -603,9 +603,9 @@ hermes chat
 ```
 
 See also:
-- [MCP (Model Context Protocol)](/user-guide/features/mcp)
-- [Use MCP with Hermes](/guides/use-mcp-with-hermes)
-- [MCP Config Reference](/reference/mcp-config-reference)
+- [MCP (Model Context Protocol)](../user-guide/features/mcp.md)
+- [Use MCP with Hermes](../guides/use-mcp-with-hermes.md)
+- [MCP Config Reference](./mcp-config-reference.md)
 
 #### MCP timeout errors
 
@@ -636,7 +636,7 @@ No. Each messaging platform (Telegram, Discord, etc.) requires exclusive access
 
 No. Each profile has its own memory store, session database, and skills directory. They are completely isolated. If you want to start a new profile with existing memories and sessions, use `hermes profile create newname --clone-all` to copy everything from the current profile, or add `--clone-from <profile>` to copy from a specific source profile.
 
-This isolation is also the reason to never run two agents against the *same* profile or Hermes home: both write memory automatically and each loads the other's writes at session start, so their stored state degrades with every session. One agent per profile; for genuinely shared memory across agents, use an [external memory provider](/user-guide/features/memory-providers).
+This isolation is also the reason to never run two agents against the *same* profile or Hermes home: both write memory automatically and each loads the other's writes at session start, so their stored state degrades with every session. One agent per profile; for genuinely shared memory across agents, use an [external memory provider](../user-guide/features/memory-providers.md).
 
 ### What happens when I run `hermes update`?
 
diff --git a/website/docs/reference/mcp-config-reference.md b/website/docs/reference/mcp-config-reference.md
index fdd6efd0c1..71828ec63d 100644
--- a/website/docs/reference/mcp-config-reference.md
+++ b/website/docs/reference/mcp-config-reference.md
@@ -9,8 +9,8 @@ description: "Reference for Hermes Agent MCP configuration keys, filtering seman
 This page is the compact reference companion to the main MCP docs.
 
 For conceptual guidance, see:
-- [MCP (Model Context Protocol)](/user-guide/features/mcp)
-- [Use MCP with Hermes](/guides/use-mcp-with-hermes)
+- [MCP (Model Context Protocol)](../user-guide/features/mcp.md)
+- [Use MCP with Hermes](../guides/use-mcp-with-hermes.md)
 
 ## Root config shape
 
@@ -337,7 +337,7 @@ Behavior:
 - Tokens are persisted to `~/.hermes/mcp-tokens/<server>.json` (a named profile uses `~/.hermes/profiles/<name>/mcp-tokens/`) and reused across sessions
 - Token refresh is automatic; re-authorization only happens when refresh fails
 - Only applies to HTTP/StreamableHTTP transport (`url`-based servers)
-- Under a [multiplexed gateway](/user-guide/multi-profile-gateways), an OAuth connection is never shared across profiles: each profile authenticates with its own token and opens its own connection, even when the `mcp_servers` entries are identical
+- Under a [multiplexed gateway](../user-guide/multi-profile-gateways.md), an OAuth connection is never shared across profiles: each profile authenticates with its own token and opens its own connection, even when the `mcp_servers` entries are identical
 
 ### Device-code login (RFC 8628)
 
diff --git a/website/docs/reference/optional-skills-catalog.md b/website/docs/reference/optional-skills-catalog.md
index d88b11affb..83f8056ae1 100644
--- a/website/docs/reference/optional-skills-catalog.md
+++ b/website/docs/reference/optional-skills-catalog.md
@@ -31,265 +31,265 @@ hermes skills uninstall <skill-name>
 
 | Skill | Description |
 |-------|-------------|
-| [**antigravity-cli**](/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-antigravity-cli) | Operate the Antigravity CLI (agy): plugins, auth, sandbox. |
-| [**blackbox**](/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-blackbox) | Delegate coding tasks to the Blackbox AI multi-model CLI. |
-| [**dynamic-workflow**](/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-dynamic-workflow) | Plan-in-code fan-outs, adversarial verification, waves. |
-| [**grok**](/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-grok) | Delegate coding to xAI Grok Build CLI (features, PRs). |
-| [**honcho**](/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho) | Configure and troubleshoot Honcho memory for Hermes. |
-| [**openhands**](/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands) | Delegate coding to OpenHands CLI (model-agnostic, LiteLLM). |
+| [**antigravity-cli**](../user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-antigravity-cli.md) | Operate the Antigravity CLI (agy): plugins, auth, sandbox. |
+| [**blackbox**](../user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-blackbox.md) | Delegate coding tasks to the Blackbox AI multi-model CLI. |
+| [**dynamic-workflow**](../user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-dynamic-workflow.md) | Plan-in-code fan-outs, adversarial verification, waves. |
+| [**grok**](../user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-grok.md) | Delegate coding to xAI Grok Build CLI (features, PRs). |
+| [**honcho**](../user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho.md) | Configure and troubleshoot Honcho memory for Hermes. |
+| [**openhands**](../user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands.md) | Delegate coding to OpenHands CLI (model-agnostic, LiteLLM). |
 
 ## blockchain
 
 | Skill | Description |
 |-------|-------------|
-| [**evm**](/docs/user-guide/skills/optional/blockchain/blockchain-evm) | Read-only EVM client: wallets, tokens, gas across 8 chains. |
-| [**hyperliquid**](/docs/user-guide/skills/optional/blockchain/blockchain-hyperliquid) | Hyperliquid market data, account history, trade review. |
-| [**pr-lens**](/docs/user-guide/skills/optional/software-development/software-development-pr-lens) | Draw code changes as animated architecture/data-flow SVGs. |
-| [**solana**](/docs/user-guide/skills/optional/blockchain/blockchain-solana) | Query Solana wallets, tokens, txs, and NFTs in USD. |
+| [**evm**](../user-guide/skills/optional/blockchain/blockchain-evm.md) | Read-only EVM client: wallets, tokens, gas across 8 chains. |
+| [**hyperliquid**](../user-guide/skills/optional/blockchain/blockchain-hyperliquid.md) | Hyperliquid market data, account history, trade review. |
+| [**pr-lens**](../user-guide/skills/optional/software-development/software-development-pr-lens.md) | Draw code changes as animated architecture/data-flow SVGs. |
+| [**solana**](../user-guide/skills/optional/blockchain/blockchain-solana.md) | Query Solana wallets, tokens, txs, and NFTs in USD. |
 
 ## communication
 
 | Skill | Description |
 |-------|-------------|
-| [**one-three-one-rule**](/docs/user-guide/skills/optional/communication/communication-one-three-one-rule) | 1-3-1 decision briefs: problem, three options, one pick. |
+| [**one-three-one-rule**](../user-guide/skills/optional/communication/communication-one-three-one-rule.md) | 1-3-1 decision briefs: problem, three options, one pick. |
 
 ## creative
 
 | Skill | Description |
 |-------|-------------|
-| [**ai-presenter-video**](/docs/user-guide/skills/optional/creative/creative-ai-presenter-video) | Make a verified AI presenter video from script + image. |
-| [**archify**](/docs/user-guide/skills/optional/creative/creative-archify) | Validated interactive HTML diagrams, upstream-maintained. |
-| [**ascii-art**](/docs/user-guide/skills/optional/creative/creative-ascii-art) | ASCII art: pyfiglet, cowsay, boxes, image-to-ascii. |
-| [**audiocraft-audio-generation**](/docs/user-guide/skills/optional/creative/creative-audiocraft-audio-generation) | AudioCraft: MusicGen text-to-music, AudioGen text-to-sound. |
-| [**auteur**](/docs/user-guide/skills/optional/creative/creative-auteur) | Design and build cinematic, award-level web pages. |
-| [**baoyu-article-illustrator**](/docs/user-guide/skills/optional/creative/creative-baoyu-article-illustrator) | Article illustrations: type × style × palette consistency. |
-| [**baoyu-comic**](/docs/user-guide/skills/optional/creative/creative-baoyu-comic) | Knowledge comics (知识漫画): educational, biography, tutorial. |
-| [**comfyui**](/docs/user-guide/skills/optional/creative/creative-comfyui) | Generate images, video, and audio via diffusion workflows. |
-| [**concept-diagrams**](/docs/user-guide/skills/optional/creative/creative-concept-diagrams) | Generate flat, minimal educational SVG visuals as HTML. |
-| [**creative-ideation**](/docs/user-guide/skills/optional/creative/creative-creative-ideation) | Generate ideas via named methods from creative practice. |
-| [**draw-your-font**](/docs/user-guide/skills/optional/creative/creative-draw-your-font) | Turn a handwriting photo into an installable TTF font. |
-| [**dream-loop**](/docs/user-guide/skills/optional/creative/creative-dream-loop) | Build stunning 3D scenes via a concept-art fidelity loop. |
-| [**excalidraw**](/docs/user-guide/skills/optional/creative/creative-excalidraw) | Hand-drawn Excalidraw JSON diagrams (arch, flow, seq). |
-| [**heartmula**](/docs/user-guide/skills/optional/creative/creative-heartmula) | HeartMuLa: Suno-like song generation from lyrics + tags. |
-| [**hyperframes**](/docs/user-guide/skills/optional/creative/creative-hyperframes) | Render MP4/WebM videos from HTML compositions. |
-| [**impeccable**](/docs/user-guide/skills/optional/creative/creative-impeccable) | Frontend design guidance, upstream-maintained (impeccable). |
-| [**ip-as-logo**](/docs/user-guide/skills/optional/creative/creative-ip-as-logo) | Design minimal cute IP mascot marks readable at 32px. |
-| [**kanban-video-orchestrator**](/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator) | Plan and run multi-agent video production pipelines. |
-| [**meme-generation**](/docs/user-guide/skills/optional/creative/creative-meme-generation) | Create meme PNGs from templates with Pillow text overlay. |
-| [**mono-color**](/docs/user-guide/skills/optional/creative/creative-mono-color) | Generate one- or two-ink editorial print poster images. |
-| [**pixel-art**](/docs/user-guide/skills/optional/creative/creative-pixel-art) | Pixel art w/ era palettes (NES, Game Boy, PICO-8). |
-| [**pretext**](/docs/user-guide/skills/optional/creative/creative-pretext) | Build creative browser demos with DOM-free text layout. |
-| [**simple-english**](/docs/user-guide/skills/optional/creative/creative-simple-english) | Rewrite text to ASD-STE100 Simplified Technical English. |
-| [**sketch**](/docs/user-guide/skills/optional/creative/creative-sketch) | Throwaway HTML mockups: 2-3 design variants to compare. |
-| [**social-media-content-calendar**](/docs/user-guide/skills/optional/creative/creative-social-media-content-calendar) | Plan multi-platform social campaigns: briefs to posting. |
-| [**system-atlas**](/docs/user-guide/skills/optional/creative/creative-system-atlas) | Build explorable isometric architecture atlases as HTML. |
-| [**tldraw-offline**](/docs/user-guide/skills/optional/creative/creative-tldraw-offline) | Drive and script tldraw offline canvases with an agent. |
-| [**unreal-mcp**](/docs/user-guide/skills/optional/creative/creative-unreal-mcp) | Automate Unreal Engine editor scenes, actors, and renders. |
+| [**ai-presenter-video**](../user-guide/skills/optional/creative/creative-ai-presenter-video.md) | Make a verified AI presenter video from script + image. |
+| [**archify**](../user-guide/skills/optional/creative/creative-archify.md) | Validated interactive HTML diagrams, upstream-maintained. |
+| [**ascii-art**](../user-guide/skills/optional/creative/creative-ascii-art.md) | ASCII art: pyfiglet, cowsay, boxes, image-to-ascii. |
+| [**audiocraft-audio-generation**](../user-guide/skills/optional/creative/creative-audiocraft-audio-generation.md) | AudioCraft: MusicGen text-to-music, AudioGen text-to-sound. |
+| [**auteur**](../user-guide/skills/optional/creative/creative-auteur.md) | Design and build cinematic, award-level web pages. |
+| [**baoyu-article-illustrator**](../user-guide/skills/optional/creative/creative-baoyu-article-illustrator.md) | Article illustrations: type × style × palette consistency. |
+| [**baoyu-comic**](../user-guide/skills/optional/creative/creative-baoyu-comic.md) | Knowledge comics (知识漫画): educational, biography, tutorial. |
+| [**comfyui**](../user-guide/skills/optional/creative/creative-comfyui.md) | Generate images, video, and audio via diffusion workflows. |
+| [**concept-diagrams**](../user-guide/skills/optional/creative/creative-concept-diagrams.md) | Generate flat, minimal educational SVG visuals as HTML. |
+| [**creative-ideation**](../user-guide/skills/optional/creative/creative-creative-ideation.md) | Generate ideas via named methods from creative practice. |
+| [**draw-your-font**](../user-guide/skills/optional/creative/creative-draw-your-font.md) | Turn a handwriting photo into an installable TTF font. |
+| [**dream-loop**](../user-guide/skills/optional/creative/creative-dream-loop.md) | Build stunning 3D scenes via a concept-art fidelity loop. |
+| [**excalidraw**](../user-guide/skills/optional/creative/creative-excalidraw.md) | Hand-drawn Excalidraw JSON diagrams (arch, flow, seq). |
+| [**heartmula**](../user-guide/skills/optional/creative/creative-heartmula.md) | HeartMuLa: Suno-like song generation from lyrics + tags. |
+| [**hyperframes**](../user-guide/skills/optional/creative/creative-hyperframes.md) | Render MP4/WebM videos from HTML compositions. |
+| [**impeccable**](../user-guide/skills/optional/creative/creative-impeccable.md) | Frontend design guidance, upstream-maintained (impeccable). |
+| [**ip-as-logo**](../user-guide/skills/optional/creative/creative-ip-as-logo.md) | Design minimal cute IP mascot marks readable at 32px. |
+| [**kanban-video-orchestrator**](../user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md) | Plan and run multi-agent video production pipelines. |
+| [**meme-generation**](../user-guide/skills/optional/creative/creative-meme-generation.md) | Create meme PNGs from templates with Pillow text overlay. |
+| [**mono-color**](../user-guide/skills/optional/creative/creative-mono-color.md) | Generate one- or two-ink editorial print poster images. |
+| [**pixel-art**](../user-guide/skills/optional/creative/creative-pixel-art.md) | Pixel art w/ era palettes (NES, Game Boy, PICO-8). |
+| [**pretext**](../user-guide/skills/optional/creative/creative-pretext.md) | Build creative browser demos with DOM-free text layout. |
+| [**simple-english**](../user-guide/skills/optional/creative/creative-simple-english.md) | Rewrite text to ASD-STE100 Simplified Technical English. |
+| [**sketch**](../user-guide/skills/optional/creative/creative-sketch.md) | Throwaway HTML mockups: 2-3 design variants to compare. |
+| [**social-media-content-calendar**](../user-guide/skills/optional/creative/creative-social-media-content-calendar.md) | Plan multi-platform social campaigns: briefs to posting. |
+| [**system-atlas**](../user-guide/skills/optional/creative/creative-system-atlas.md) | Build explorable isometric architecture atlases as HTML. |
+| [**tldraw-offline**](../user-guide/skills/optional/creative/creative-tldraw-offline.md) | Drive and script tldraw offline canvases with an agent. |
+| [**unreal-mcp**](../user-guide/skills/optional/creative/creative-unreal-mcp.md) | Automate Unreal Engine editor scenes, actors, and renders. |
 
 ## data-science
 
 | Skill | Description |
 |-------|-------------|
-| [**jupyter-notebook**](/docs/user-guide/skills/optional/data-science/data-science-jupyter-notebook) | Iterative Python via live Jupyter kernel (hamelnb). |
+| [**jupyter-notebook**](../user-guide/skills/optional/data-science/data-science-jupyter-notebook.md) | Iterative Python via live Jupyter kernel (hamelnb). |
 
 ## devops
 
 | Skill | Description |
 |-------|-------------|
-| [**actual-setup**](/docs/user-guide/skills/optional/devops/devops-actual-setup) | Set up Actual Computer (actual.inc) inference in Hermes. |
-| [**docker-management**](/docs/user-guide/skills/optional/devops/devops-docker-management) | Manage Docker containers, images, volumes, and Compose. |
-| [**hermes-s6-container-supervision**](/docs/user-guide/skills/optional/devops/devops-hermes-s6-container-supervision) | Modify or debug s6 services in the Hermes Docker image. |
-| [**inference-sh-cli**](/docs/user-guide/skills/optional/devops/devops-inference-sh-cli) | Run 150+ AI apps (image, video, LLM) via inference.sh CLI. |
-| [**pinggy-tunnel**](/docs/user-guide/skills/optional/devops/devops-pinggy-tunnel) | Zero-install localhost tunnels over SSH via Pinggy. |
-| [**setup-wizard-generator**](/docs/user-guide/skills/optional/devops/devops-setup-wizard-generator) | Generate a bash wizard guiding a human through manual setup. |
-| [**watchers**](/docs/user-guide/skills/optional/devops/devops-watchers) | Poll RSS, JSON APIs, and GitHub with watermark dedup. |
+| [**actual-setup**](../user-guide/skills/optional/devops/devops-actual-setup.md) | Set up Actual Computer (actual.inc) inference in Hermes. |
+| [**docker-management**](../user-guide/skills/optional/devops/devops-docker-management.md) | Manage Docker containers, images, volumes, and Compose. |
+| [**hermes-s6-container-supervision**](../user-guide/skills/optional/devops/devops-hermes-s6-container-supervision.md) | Modify or debug s6 services in the Hermes Docker image. |
+| [**inference-sh-cli**](../user-guide/skills/optional/devops/devops-inference-sh-cli.md) | Run 150+ AI apps (image, video, LLM) via inference.sh CLI. |
+| [**pinggy-tunnel**](../user-guide/skills/optional/devops/devops-pinggy-tunnel.md) | Zero-install localhost tunnels over SSH via Pinggy. |
+| [**setup-wizard-generator**](../user-guide/skills/optional/devops/devops-setup-wizard-generator.md) | Generate a bash wizard guiding a human through manual setup. |
+| [**watchers**](../user-guide/skills/optional/devops/devops-watchers.md) | Poll RSS, JSON APIs, and GitHub with watermark dedup. |
 
 ## dogfood
 
 | Skill | Description |
 |-------|-------------|
-| [**adversarial-ux-test**](/docs/user-guide/skills/optional/dogfood/dogfood-adversarial-ux-test) | Roleplay a hostile user to find and triage UX pain points. |
+| [**adversarial-ux-test**](../user-guide/skills/optional/dogfood/dogfood-adversarial-ux-test.md) | Roleplay a hostile user to find and triage UX pain points. |
 
 ## email
 
 | Skill | Description |
 |-------|-------------|
-| [**agentmail**](/docs/user-guide/skills/optional/email/email-agentmail) | Use when an agent needs AgentMail CLI email inboxes. |
+| [**agentmail**](../user-guide/skills/optional/email/email-agentmail.md) | Use when an agent needs AgentMail CLI email inboxes. |
 
 ## finance
 
 | Skill | Description |
 |-------|-------------|
-| [**3-statement-model**](/docs/user-guide/skills/optional/finance/finance-3-statement-model) | Build integrated IS/BS/CF financial workbooks in Excel. |
-| [**comps-analysis**](/docs/user-guide/skills/optional/finance/finance-comps-analysis) | Build comparable-company valuation workbooks in Excel. |
-| [**dcf-model**](/docs/user-guide/skills/optional/finance/finance-dcf-model) | Build discounted cash flow valuation workbooks in Excel. |
-| [**excel-author**](/docs/user-guide/skills/optional/finance/finance-excel-author) | Build auditable financial workbooks headless via openpyxl. |
-| [**lbo-model**](/docs/user-guide/skills/optional/finance/finance-lbo-model) | Build leveraged buyout workbooks with IRR/MOIC in Excel. |
-| [**merger-model**](/docs/user-guide/skills/optional/finance/finance-merger-model) | Build M&A accretion/dilution workbooks in Excel. |
-| [**polymarket**](/docs/user-guide/skills/optional/finance/finance-polymarket) | Query Polymarket: markets, prices, orderbooks, history. |
-| [**pptx-author**](/docs/user-guide/skills/optional/finance/finance-pptx-author) | Build PowerPoint decks headless with python-pptx. |
-| [**stocks**](/docs/user-guide/skills/optional/finance/finance-stocks) | Stock quotes, history, search, compare, crypto via Yahoo. |
+| [**3-statement-model**](../user-guide/skills/optional/finance/finance-3-statement-model.md) | Build integrated IS/BS/CF financial workbooks in Excel. |
+| [**comps-analysis**](../user-guide/skills/optional/finance/finance-comps-analysis.md) | Build comparable-company valuation workbooks in Excel. |
+| [**dcf-model**](../user-guide/skills/optional/finance/finance-dcf-model.md) | Build discounted cash flow valuation workbooks in Excel. |
+| [**excel-author**](../user-guide/skills/optional/finance/finance-excel-author.md) | Build auditable financial workbooks headless via openpyxl. |
+| [**lbo-model**](../user-guide/skills/optional/finance/finance-lbo-model.md) | Build leveraged buyout workbooks with IRR/MOIC in Excel. |
+| [**merger-model**](../user-guide/skills/optional/finance/finance-merger-model.md) | Build M&A accretion/dilution workbooks in Excel. |
+| [**polymarket**](../user-guide/skills/optional/finance/finance-polymarket.md) | Query Polymarket: markets, prices, orderbooks, history. |
+| [**pptx-author**](../user-guide/skills/optional/finance/finance-pptx-author.md) | Build PowerPoint decks headless with python-pptx. |
+| [**stocks**](../user-guide/skills/optional/finance/finance-stocks.md) | Stock quotes, history, search, compare, crypto via Yahoo. |
 
 ## gaming
 
 | Skill | Description |
 |-------|-------------|
-| [**minecraft-modpack-server**](/docs/user-guide/skills/optional/gaming/gaming-minecraft-modpack-server) | Host modded Minecraft servers (CurseForge, Modrinth). |
-| [**pokemon-player**](/docs/user-guide/skills/optional/gaming/gaming-pokemon-player) | Play Pokemon via headless emulator + RAM reads. |
+| [**minecraft-modpack-server**](../user-guide/skills/optional/gaming/gaming-minecraft-modpack-server.md) | Host modded Minecraft servers (CurseForge, Modrinth). |
+| [**pokemon-player**](../user-guide/skills/optional/gaming/gaming-pokemon-player.md) | Play Pokemon via headless emulator + RAM reads. |
 
 ## health
 
 | Skill | Description |
 |-------|-------------|
-| [**fitness-nutrition**](/docs/user-guide/skills/optional/health/health-fitness-nutrition) | Workout planning, macros, and body metrics via wger/USDA. |
-| [**neuroskill-bci**](/docs/user-guide/skills/optional/health/health-neuroskill-bci) | Use live BCI cognitive and mood state from NeuroSkill. |
+| [**fitness-nutrition**](../user-guide/skills/optional/health/health-fitness-nutrition.md) | Workout planning, macros, and body metrics via wger/USDA. |
+| [**neuroskill-bci**](../user-guide/skills/optional/health/health-neuroskill-bci.md) | Use live BCI cognitive and mood state from NeuroSkill. |
 
 ## mcp
 
 | Skill | Description |
 |-------|-------------|
-| [**fastmcp**](/docs/user-guide/skills/optional/mcp/mcp-fastmcp) | Build, test, and deploy Python MCP servers. |
-| [**mcp-oauth-remote-gateway**](/docs/user-guide/skills/optional/mcp/mcp-mcp-oauth-remote-gateway) | Manual OAuth for remote MCP servers on headless gateways. |
-| [**mcporter**](/docs/user-guide/skills/optional/mcp/mcp-mcporter) | List, auth, and call MCP servers/tools from the terminal. |
+| [**fastmcp**](../user-guide/skills/optional/mcp/mcp-fastmcp.md) | Build, test, and deploy Python MCP servers. |
+| [**mcp-oauth-remote-gateway**](../user-guide/skills/optional/mcp/mcp-mcp-oauth-remote-gateway.md) | Manual OAuth for remote MCP servers on headless gateways. |
+| [**mcporter**](../user-guide/skills/optional/mcp/mcp-mcporter.md) | List, auth, and call MCP servers/tools from the terminal. |
 
 ## migration
 
 | Skill | Description |
 |-------|-------------|
-| [**openclaw-migration**](/docs/user-guide/skills/optional/migration/migration-openclaw-migration) | Import an OpenClaw setup (memories, skills) into Hermes. |
+| [**openclaw-migration**](../user-guide/skills/optional/migration/migration-openclaw-migration.md) | Import an OpenClaw setup (memories, skills) into Hermes. |
 
 ## mlops
 
 | Skill | Description |
 |-------|-------------|
-| [**accelerate**](/docs/user-guide/skills/optional/mlops/mlops-accelerate) | Run PyTorch training across GPUs with minimal changes. |
-| [**axolotl**](/docs/user-guide/skills/optional/mlops/mlops-training-axolotl) | Axolotl: YAML LLM fine-tuning (LoRA, DPO, GRPO). |
-| [**chroma**](/docs/user-guide/skills/optional/mlops/mlops-chroma) | Embedding database for RAG and semantic search. |
-| [**clip**](/docs/user-guide/skills/optional/mlops/mlops-clip) | Zero-shot image classification and image-text search. |
-| [**dspy**](/docs/user-guide/skills/optional/mlops/mlops-research-dspy) | DSPy: declarative LM programs, auto-optimize prompts, RAG. |
-| [**evaluating-llms-harness**](/docs/user-guide/skills/optional/mlops/mlops-evaluation-evaluating-llms-harness) | lm-eval-harness: benchmark LLMs (MMLU, GSM8K, etc.). |
-| [**faiss**](/docs/user-guide/skills/optional/mlops/mlops-faiss) | Fast vector similarity search at billion scale. |
-| [**flash-attention**](/docs/user-guide/skills/optional/mlops/mlops-flash-attention) | Speed up long-sequence transformer training and inference. |
-| [**guidance**](/docs/user-guide/skills/optional/mlops/mlops-guidance) | Constrain LLM output with grammars; guarantee valid JSON. |
-| [**huggingface-hub**](/docs/user-guide/skills/optional/mlops/mlops-models-huggingface-hub) | HuggingFace hf CLI: search/download/upload models, datasets. |
-| [**huggingface-tokenizers**](/docs/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers) | Fast BPE/WordPiece tokenization and custom vocab training. |
-| [**instructor**](/docs/user-guide/skills/optional/mlops/mlops-instructor) | Structured LLM outputs validated with Pydantic. |
-| [**lambda-labs**](/docs/user-guide/skills/optional/mlops/mlops-lambda-labs) | On-demand GPU cloud instances for ML training. |
-| [**llama-cpp**](/docs/user-guide/skills/optional/mlops/mlops-inference-llama-cpp) | llama.cpp local GGUF inference + HF Hub model discovery. |
-| [**llava**](/docs/user-guide/skills/optional/mlops/mlops-llava) | Vision-language chat: VQA, captioning, image dialogue. |
-| [**modal**](/docs/user-guide/skills/optional/mlops/mlops-modal) | Serverless GPU cloud for ML jobs and model APIs. |
-| [**nemo-curator**](/docs/user-guide/skills/optional/mlops/mlops-nemo-curator) | Curate LLM training data: dedupe, filter, PII redaction. |
-| [**obliteratus**](/docs/user-guide/skills/optional/mlops/mlops-obliteratus) | OBLITERATUS: abliterate LLM refusals (diff-in-means). |
-| [**outlines**](/docs/user-guide/skills/optional/mlops/mlops-inference-outlines) | Outlines: structured JSON/regex/Pydantic LLM generation. |
-| [**peft**](/docs/user-guide/skills/optional/mlops/mlops-peft) | Fine-tune large LLMs with LoRA on limited GPU memory. |
-| [**pinecone**](/docs/user-guide/skills/optional/mlops/mlops-pinecone) | Managed vector DB for production RAG and search. |
-| [**pytorch-fsdp**](/docs/user-guide/skills/optional/mlops/mlops-pytorch-fsdp) | Fully sharded data-parallel training for large models. |
-| [**pytorch-lightning**](/docs/user-guide/skills/optional/mlops/mlops-pytorch-lightning) | Clean training loops with built-in distributed support. |
-| [**qdrant**](/docs/user-guide/skills/optional/mlops/mlops-qdrant) | Vector search engine for production RAG systems. |
-| [**saelens**](/docs/user-guide/skills/optional/mlops/mlops-saelens) | Train sparse autoencoders to interpret model features. |
-| [**segment-anything-model**](/docs/user-guide/skills/optional/mlops/mlops-models-segment-anything-model) | SAM: zero-shot image segmentation via points, boxes, masks. |
-| [**serving-llms-vllm**](/docs/user-guide/skills/optional/mlops/mlops-inference-serving-llms-vllm) | vLLM: high-throughput LLM serving, OpenAI API, quantization. |
-| [**simpo**](/docs/user-guide/skills/optional/mlops/mlops-simpo) | Reference-free preference alignment, simpler than DPO. |
-| [**slime**](/docs/user-guide/skills/optional/mlops/mlops-slime) | RL post-training for LLMs with Megatron and SGLang. |
-| [**stable-diffusion**](/docs/user-guide/skills/optional/mlops/mlops-stable-diffusion) | Text-to-image generation, inpainting, and img2img. |
-| [**tensorrt-llm**](/docs/user-guide/skills/optional/mlops/mlops-tensorrt-llm) | High-throughput LLM inference on NVIDIA GPUs. |
-| [**torchtitan**](/docs/user-guide/skills/optional/mlops/mlops-torchtitan) | Pretrain LLMs at scale with PyTorch 4D parallelism. |
-| [**trl-fine-tuning**](/docs/user-guide/skills/optional/mlops/mlops-training-trl-fine-tuning) | TRL: SFT, DPO, GRPO, RLOO reward modeling for LLM RLHF. |
-| [**unsloth**](/docs/user-guide/skills/optional/mlops/mlops-training-unsloth) | Unsloth: 2-5x faster LoRA/QLoRA fine-tuning, less VRAM. |
-| [**weights-and-biases**](/docs/user-guide/skills/optional/mlops/mlops-evaluation-weights-and-biases) | W&B: log ML experiments, sweeps, model registry, dashboards. |
-| [**whisper**](/docs/user-guide/skills/optional/mlops/mlops-whisper) | Transcribe and translate speech in 99 languages. |
+| [**accelerate**](../user-guide/skills/optional/mlops/mlops-accelerate.md) | Run PyTorch training across GPUs with minimal changes. |
+| [**axolotl**](../user-guide/skills/optional/mlops/mlops-training-axolotl.md) | Axolotl: YAML LLM fine-tuning (LoRA, DPO, GRPO). |
+| [**chroma**](../user-guide/skills/optional/mlops/mlops-chroma.md) | Embedding database for RAG and semantic search. |
+| [**clip**](../user-guide/skills/optional/mlops/mlops-clip.md) | Zero-shot image classification and image-text search. |
+| [**dspy**](../user-guide/skills/optional/mlops/mlops-research-dspy.md) | DSPy: declarative LM programs, auto-optimize prompts, RAG. |
+| [**evaluating-llms-harness**](../user-guide/skills/optional/mlops/mlops-evaluation-evaluating-llms-harness.md) | lm-eval-harness: benchmark LLMs (MMLU, GSM8K, etc.). |
+| [**faiss**](../user-guide/skills/optional/mlops/mlops-faiss.md) | Fast vector similarity search at billion scale. |
+| [**flash-attention**](../user-guide/skills/optional/mlops/mlops-flash-attention.md) | Speed up long-sequence transformer training and inference. |
+| [**guidance**](../user-guide/skills/optional/mlops/mlops-guidance.md) | Constrain LLM output with grammars; guarantee valid JSON. |
+| [**huggingface-hub**](../user-guide/skills/optional/mlops/mlops-models-huggingface-hub.md) | HuggingFace hf CLI: search/download/upload models, datasets. |
+| [**huggingface-tokenizers**](../user-guide/skills/optional/mlops/mlops-huggingface-tokenizers.md) | Fast BPE/WordPiece tokenization and custom vocab training. |
+| [**instructor**](../user-guide/skills/optional/mlops/mlops-instructor.md) | Structured LLM outputs validated with Pydantic. |
+| [**lambda-labs**](../user-guide/skills/optional/mlops/mlops-lambda-labs.md) | On-demand GPU cloud instances for ML training. |
+| [**llama-cpp**](../user-guide/skills/optional/mlops/mlops-inference-llama-cpp.md) | llama.cpp local GGUF inference + HF Hub model discovery. |
+| [**llava**](../user-guide/skills/optional/mlops/mlops-llava.md) | Vision-language chat: VQA, captioning, image dialogue. |
+| [**modal**](../user-guide/skills/optional/mlops/mlops-modal.md) | Serverless GPU cloud for ML jobs and model APIs. |
+| [**nemo-curator**](../user-guide/skills/optional/mlops/mlops-nemo-curator.md) | Curate LLM training data: dedupe, filter, PII redaction. |
+| [**obliteratus**](../user-guide/skills/optional/mlops/mlops-obliteratus.md) | OBLITERATUS: abliterate LLM refusals (diff-in-means). |
+| [**outlines**](../user-guide/skills/optional/mlops/mlops-inference-outlines.md) | Outlines: structured JSON/regex/Pydantic LLM generation. |
+| [**peft**](../user-guide/skills/optional/mlops/mlops-peft.md) | Fine-tune large LLMs with LoRA on limited GPU memory. |
+| [**pinecone**](../user-guide/skills/optional/mlops/mlops-pinecone.md) | Managed vector DB for production RAG and search. |
+| [**pytorch-fsdp**](../user-guide/skills/optional/mlops/mlops-pytorch-fsdp.md) | Fully sharded data-parallel training for large models. |
+| [**pytorch-lightning**](../user-guide/skills/optional/mlops/mlops-pytorch-lightning.md) | Clean training loops with built-in distributed support. |
+| [**qdrant**](../user-guide/skills/optional/mlops/mlops-qdrant.md) | Vector search engine for production RAG systems. |
+| [**saelens**](../user-guide/skills/optional/mlops/mlops-saelens.md) | Train sparse autoencoders to interpret model features. |
+| [**segment-anything-model**](../user-guide/skills/optional/mlops/mlops-models-segment-anything-model.md) | SAM: zero-shot image segmentation via points, boxes, masks. |
+| [**serving-llms-vllm**](../user-guide/skills/optional/mlops/mlops-inference-serving-llms-vllm.md) | vLLM: high-throughput LLM serving, OpenAI API, quantization. |
+| [**simpo**](../user-guide/skills/optional/mlops/mlops-simpo.md) | Reference-free preference alignment, simpler than DPO. |
+| [**slime**](../user-guide/skills/optional/mlops/mlops-slime.md) | RL post-training for LLMs with Megatron and SGLang. |
+| [**stable-diffusion**](../user-guide/skills/optional/mlops/mlops-stable-diffusion.md) | Text-to-image generation, inpainting, and img2img. |
+| [**tensorrt-llm**](../user-guide/skills/optional/mlops/mlops-tensorrt-llm.md) | High-throughput LLM inference on NVIDIA GPUs. |
+| [**torchtitan**](../user-guide/skills/optional/mlops/mlops-torchtitan.md) | Pretrain LLMs at scale with PyTorch 4D parallelism. |
+| [**trl-fine-tuning**](../user-guide/skills/optional/mlops/mlops-training-trl-fine-tuning.md) | TRL: SFT, DPO, GRPO, RLOO reward modeling for LLM RLHF. |
+| [**unsloth**](../user-guide/skills/optional/mlops/mlops-training-unsloth.md) | Unsloth: 2-5x faster LoRA/QLoRA fine-tuning, less VRAM. |
+| [**weights-and-biases**](../user-guide/skills/optional/mlops/mlops-evaluation-weights-and-biases.md) | W&B: log ML experiments, sweeps, model registry, dashboards. |
+| [**whisper**](../user-guide/skills/optional/mlops/mlops-whisper.md) | Transcribe and translate speech in 99 languages. |
 
 ## payments
 
 | Skill | Description |
 |-------|-------------|
-| [**mpp-agent**](/docs/user-guide/skills/optional/payments/payments-mpp-agent) | Pay HTTP 402 APIs via Machine Payments Protocol (MPP). |
-| [**stripe-link-cli**](/docs/user-guide/skills/optional/payments/payments-stripe-link-cli) | Agent payments via Stripe Link — cards, SPT, approvals. |
-| [**stripe-projects**](/docs/user-guide/skills/optional/payments/payments-stripe-projects) | Provision SaaS services + sync creds via Stripe Projects. |
+| [**mpp-agent**](../user-guide/skills/optional/payments/payments-mpp-agent.md) | Pay HTTP 402 APIs via Machine Payments Protocol (MPP). |
+| [**stripe-link-cli**](../user-guide/skills/optional/payments/payments-stripe-link-cli.md) | Agent payments via Stripe Link — cards, SPT, approvals. |
+| [**stripe-projects**](../user-guide/skills/optional/payments/payments-stripe-projects.md) | Provision SaaS services + sync creds via Stripe Projects. |
 
 ## productivity
 
 | Skill | Description |
 |-------|-------------|
-| [**canvas**](/docs/user-guide/skills/optional/productivity/productivity-canvas) | Fetch Canvas LMS courses and assignments via API token. |
-| [**decision-questionnaire**](/docs/user-guide/skills/optional/productivity/productivity-decision-questionnaire) | Turn an unanswerable decision into a questionnaire doc. |
-| [**here-now**](/docs/user-guide/skills/optional/productivity/productivity-here-now) | Publish sites to &#123;slug&#125;.here.now and store files in Drives. |
-| [**live-dashboard**](/docs/user-guide/skills/optional/productivity/productivity-live-dashboard) | Build self-updating dashboards from live sources. |
-| [**memento-flashcards**](/docs/user-guide/skills/optional/productivity/productivity-memento-flashcards) | Spaced-repetition flashcards: create, review, quiz, export. |
-| [**property-listings**](/docs/user-guide/skills/optional/productivity/productivity-property-listings) | Present property and rental listings as desktop cards. |
-| [**shop**](/docs/user-guide/skills/optional/productivity/productivity-shop) | Shop catalog search, checkout, order tracking, returns. |
-| [**shopify**](/docs/user-guide/skills/optional/productivity/productivity-shopify) | Query Shopify Admin/Storefront GraphQL APIs via curl. |
-| [**siyuan**](/docs/user-guide/skills/optional/productivity/productivity-siyuan) | Query and edit a SiYuan knowledge base via its API. |
-| [**telephony**](/docs/user-guide/skills/optional/productivity/productivity-telephony) | Provision Twilio numbers, SMS/MMS, and AI outbound calls. |
+| [**canvas**](../user-guide/skills/optional/productivity/productivity-canvas.md) | Fetch Canvas LMS courses and assignments via API token. |
+| [**decision-questionnaire**](../user-guide/skills/optional/productivity/productivity-decision-questionnaire.md) | Turn an unanswerable decision into a questionnaire doc. |
+| [**here-now**](../user-guide/skills/optional/productivity/productivity-here-now.md) | Publish sites to &#123;slug&#125;.here.now and store files in Drives. |
+| [**live-dashboard**](../user-guide/skills/optional/productivity/productivity-live-dashboard.md) | Build self-updating dashboards from live sources. |
+| [**memento-flashcards**](../user-guide/skills/optional/productivity/productivity-memento-flashcards.md) | Spaced-repetition flashcards: create, review, quiz, export. |
+| [**property-listings**](../user-guide/skills/optional/productivity/productivity-property-listings.md) | Present property and rental listings as desktop cards. |
+| [**shop**](../user-guide/skills/optional/productivity/productivity-shop.md) | Shop catalog search, checkout, order tracking, returns. |
+| [**shopify**](../user-guide/skills/optional/productivity/productivity-shopify.md) | Query Shopify Admin/Storefront GraphQL APIs via curl. |
+| [**siyuan**](../user-guide/skills/optional/productivity/productivity-siyuan.md) | Query and edit a SiYuan knowledge base via its API. |
+| [**telephony**](../user-guide/skills/optional/productivity/productivity-telephony.md) | Provision Twilio numbers, SMS/MMS, and AI outbound calls. |
 
 ## research
 
 | Skill | Description |
 |-------|-------------|
-| [**bioinformatics**](/docs/user-guide/skills/optional/research/research-bioinformatics) | Gateway to 400+ genomics and computational biology skills. |
-| [**blogwatcher**](/docs/user-guide/skills/optional/research/research-blogwatcher) | Monitor blogs and RSS/Atom feeds via blogwatcher-cli tool. |
-| [**darwinian-evolver**](/docs/user-guide/skills/optional/research/research-darwinian-evolver) | Evolve prompts/regex/SQL/code with Imbue's evolution loop. |
-| [**domain-intel**](/docs/user-guide/skills/optional/research/research-domain-intel) | Passive recon of subdomains, SSL certs, WHOIS, and DNS. |
-| [**drug-discovery**](/docs/user-guide/skills/optional/research/research-drug-discovery) | Drug discovery: ChEMBL search, drug-likeness, interactions. |
-| [**duckduckgo-search**](/docs/user-guide/skills/optional/research/research-duckduckgo-search) | Free keyless web, news, and image search via ddgs. |
-| [**gitnexus-explorer**](/docs/user-guide/skills/optional/research/research-gitnexus-explorer) | Serve an interactive codebase knowledge graph web UI. |
-| [**osint-investigation**](/docs/user-guide/skills/optional/research/research-osint-investigation) | Follow the money via public records and sanctions data. |
-| [**parallel-cli**](/docs/user-guide/skills/optional/research/research-parallel-cli) | Agent-native web search, deep research, and enrichment. |
-| [**pinecone-research**](/docs/user-guide/skills/optional/research/research-pinecone-research) | Agent RAG and long-term memory with Pinecone. |
-| [**qmd**](/docs/user-guide/skills/optional/research/research-qmd) | Hybrid local search over notes, docs, and transcripts. |
-| [**research-paper-writing**](/docs/user-guide/skills/optional/research/research-research-paper-writing) | Write ML papers for NeurIPS/ICML/ICLR: design→submit. |
-| [**rss-feeds**](/docs/user-guide/skills/optional/research/research-rss-feeds) | Read RSS, Atom, JSON feeds; discover feeds behind a page. |
-| [**scrapling**](/docs/user-guide/skills/optional/research/research-scrapling) | Scrape sites with stealth browsing and Cloudflare bypass. |
-| [**searxng-search**](/docs/user-guide/skills/optional/research/research-searxng-search) | Free keyless meta-search aggregating 70+ engines. |
+| [**bioinformatics**](../user-guide/skills/optional/research/research-bioinformatics.md) | Gateway to 400+ genomics and computational biology skills. |
+| [**blogwatcher**](../user-guide/skills/optional/research/research-blogwatcher.md) | Monitor blogs and RSS/Atom feeds via blogwatcher-cli tool. |
+| [**darwinian-evolver**](../user-guide/skills/optional/research/research-darwinian-evolver.md) | Evolve prompts/regex/SQL/code with Imbue's evolution loop. |
+| [**domain-intel**](../user-guide/skills/optional/research/research-domain-intel.md) | Passive recon of subdomains, SSL certs, WHOIS, and DNS. |
+| [**drug-discovery**](../user-guide/skills/optional/research/research-drug-discovery.md) | Drug discovery: ChEMBL search, drug-likeness, interactions. |
+| [**duckduckgo-search**](../user-guide/skills/optional/research/research-duckduckgo-search.md) | Free keyless web, news, and image search via ddgs. |
+| [**gitnexus-explorer**](../user-guide/skills/optional/research/research-gitnexus-explorer.md) | Serve an interactive codebase knowledge graph web UI. |
+| [**osint-investigation**](../user-guide/skills/optional/research/research-osint-investigation.md) | Follow the money via public records and sanctions data. |
+| [**parallel-cli**](../user-guide/skills/optional/research/research-parallel-cli.md) | Agent-native web search, deep research, and enrichment. |
+| [**pinecone-research**](../user-guide/skills/optional/research/research-pinecone-research.md) | Agent RAG and long-term memory with Pinecone. |
+| [**qmd**](../user-guide/skills/optional/research/research-qmd.md) | Hybrid local search over notes, docs, and transcripts. |
+| [**research-paper-writing**](../user-guide/skills/optional/research/research-research-paper-writing.md) | Write ML papers for NeurIPS/ICML/ICLR: design→submit. |
+| [**rss-feeds**](../user-guide/skills/optional/research/research-rss-feeds.md) | Read RSS, Atom, JSON feeds; discover feeds behind a page. |
+| [**scrapling**](../user-guide/skills/optional/research/research-scrapling.md) | Scrape sites with stealth browsing and Cloudflare bypass. |
+| [**searxng-search**](../user-guide/skills/optional/research/research-searxng-search.md) | Free keyless meta-search aggregating 70+ engines. |
 
 ## security
 
 | Skill | Description |
 |-------|-------------|
-| [**1password**](/docs/user-guide/skills/optional/security/security-1password) | Set up op CLI, sign in, and read or inject secrets. |
-| [**godmode**](/docs/user-guide/skills/optional/security/security-godmode) | Jailbreak LLMs: Parseltongue, GODMODE, ULTRAPLINIAN. |
-| [**oss-forensics**](/docs/user-guide/skills/optional/security/security-oss-forensics) | GitHub supply-chain forensics: recovery, IOCs, reporting. |
-| [**sherlock**](/docs/user-guide/skills/optional/security/security-sherlock) | Find accounts for a username across 400+ platforms. |
-| [**unbroker**](/docs/user-guide/skills/optional/security/security-unbroker) | Autonomously remove your info from data-broker sites. |
-| [**web-pentest**](/docs/user-guide/skills/optional/security/security-web-pentest) | Authorized web pentest: recon, proof-based exploits, report. |
+| [**1password**](../user-guide/skills/optional/security/security-1password.md) | Set up op CLI, sign in, and read or inject secrets. |
+| [**godmode**](../user-guide/skills/optional/security/security-godmode.md) | Jailbreak LLMs: Parseltongue, GODMODE, ULTRAPLINIAN. |
+| [**oss-forensics**](../user-guide/skills/optional/security/security-oss-forensics.md) | GitHub supply-chain forensics: recovery, IOCs, reporting. |
+| [**sherlock**](../user-guide/skills/optional/security/security-sherlock.md) | Find accounts for a username across 400+ platforms. |
+| [**unbroker**](../user-guide/skills/optional/security/security-unbroker.md) | Autonomously remove your info from data-broker sites. |
+| [**web-pentest**](../user-guide/skills/optional/security/security-web-pentest.md) | Authorized web pentest: recon, proof-based exploits, report. |
 
 ## smart-home
 
 | Skill | Description |
 |-------|-------------|
-| [**openhue**](/docs/user-guide/skills/optional/smart-home/smart-home-openhue) | Control Philips Hue lights, scenes, rooms via OpenHue CLI. |
+| [**openhue**](../user-guide/skills/optional/smart-home/smart-home-openhue.md) | Control Philips Hue lights, scenes, rooms via OpenHue CLI. |
 
 ## social-media
 
 | Skill | Description |
 |-------|-------------|
-| [**reddit-reading**](/docs/user-guide/skills/optional/social-media/social-media-reddit-reading) | Read Reddit: subreddits, search, threads, users. No browser. |
+| [**reddit-reading**](../user-guide/skills/optional/social-media/social-media-reddit-reading.md) | Read Reddit: subreddits, search, threads, users. No browser. |
 
 ## software-development
 
 | Skill | Description |
 |-------|-------------|
-| [**ast-grep**](/docs/user-guide/skills/optional/software-development/software-development-ast-grep) | AST-aware structural code search and rewrite via ast-grep. |
-| [**code-wiki**](/docs/user-guide/skills/optional/software-development/software-development-code-wiki) | Generate wiki docs + Mermaid diagrams for any codebase. |
-| [**grill-me**](/docs/user-guide/skills/optional/software-development/software-development-grill-me) | Adversarial plan interview before implementation. |
-| [**rest-graphql-debug**](/docs/user-guide/skills/optional/software-development/software-development-rest-graphql-debug) | Debug REST/GraphQL APIs: status codes, auth, schemas, repro. |
-| [**subagent-driven-development**](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development) | Execute plans via delegate_task subagents (2-stage review). |
+| [**ast-grep**](../user-guide/skills/optional/software-development/software-development-ast-grep.md) | AST-aware structural code search and rewrite via ast-grep. |
+| [**code-wiki**](../user-guide/skills/optional/software-development/software-development-code-wiki.md) | Generate wiki docs + Mermaid diagrams for any codebase. |
+| [**grill-me**](../user-guide/skills/optional/software-development/software-development-grill-me.md) | Adversarial plan interview before implementation. |
+| [**rest-graphql-debug**](../user-guide/skills/optional/software-development/software-development-rest-graphql-debug.md) | Debug REST/GraphQL APIs: status codes, auth, schemas, repro. |
+| [**subagent-driven-development**](../user-guide/skills/optional/software-development/software-development-subagent-driven-development.md) | Execute plans via delegate_task subagents (2-stage review). |
 
 ## web-development
 
 | Skill | Description |
 |-------|-------------|
-| [**cloudflare-temporary-deploy**](/docs/user-guide/skills/optional/web-development/web-development-cloudflare-temporary-deploy) | Deploy a Worker live, no account, via wrangler --temporary. |
-| [**har-derived-api-client**](/docs/user-guide/skills/optional/web-development/web-development-har-derived-api-client) | Record a site's XHR into a HAR, derive an HTTP client. |
-| [**page-agent**](/docs/user-guide/skills/optional/web-development/web-development-page-agent) | Embed an in-page natural-language GUI copilot in web apps. |
-| [**publish-site**](/docs/user-guide/skills/optional/web-development/web-development-publish-site) | Versioned site deploys to GitHub/Cloudflare/Netlify Pages. |
-| [**scrollcraft**](/docs/user-guide/skills/optional/web-development/web-development-scrollcraft) | Premium scroll-driven landing pages; scroll = timeline. |
+| [**cloudflare-temporary-deploy**](../user-guide/skills/optional/web-development/web-development-cloudflare-temporary-deploy.md) | Deploy a Worker live, no account, via wrangler --temporary. |
+| [**har-derived-api-client**](../user-guide/skills/optional/web-development/web-development-har-derived-api-client.md) | Record a site's XHR into a HAR, derive an HTTP client. |
+| [**page-agent**](../user-guide/skills/optional/web-development/web-development-page-agent.md) | Embed an in-page natural-language GUI copilot in web apps. |
+| [**publish-site**](../user-guide/skills/optional/web-development/web-development-publish-site.md) | Versioned site deploys to GitHub/Cloudflare/Netlify Pages. |
+| [**scrollcraft**](../user-guide/skills/optional/web-development/web-development-scrollcraft.md) | Premium scroll-driven landing pages; scroll = timeline. |
 
 ## yuanbao
 
 | Skill | Description |
 |-------|-------------|
-| [**yuanbao**](/docs/user-guide/skills/optional/yuanbao/yuanbao-yuanbao) | Yuanbao (元宝) groups: @mention users, query info/members. |
+| [**yuanbao**](../user-guide/skills/optional/yuanbao/yuanbao-yuanbao.md) | Yuanbao (元宝) groups: @mention users, query info/members. |
 
 ---
 
diff --git a/website/docs/reference/skills-catalog.md b/website/docs/reference/skills-catalog.md
index b6ab7f5c21..96d399c1b7 100644
--- a/website/docs/reference/skills-catalog.md
+++ b/website/docs/reference/skills-catalog.md
@@ -16,117 +16,117 @@ If a skill is missing from this list but present in the repo, the catalog is reg
 
 | Skill | Description | Path |
 |-------|-------------|------|
-| [`apple-notes`](/docs/user-guide/skills/bundled/apple/apple-apple-notes) | Manage Apple Notes via memo CLI: create, search, edit. | `apple\apple-notes` |
-| [`apple-reminders`](/docs/user-guide/skills/bundled/apple/apple-apple-reminders) | Apple Reminders via remindctl: add, list, complete. | `apple\apple-reminders` |
-| [`findmy`](/docs/user-guide/skills/bundled/apple/apple-findmy) | Track Apple devices/AirTags via FindMy.app on macOS. | `apple\findmy` |
-| [`imessage`](/docs/user-guide/skills/bundled/apple/apple-imessage) | Send and receive iMessages/SMS via the imsg CLI on macOS. | `apple\imessage` |
+| [`apple-notes`](../user-guide/skills/bundled/apple/apple-apple-notes.md) | Manage Apple Notes via memo CLI: create, search, edit. | `apple\apple-notes` |
+| [`apple-reminders`](../user-guide/skills/bundled/apple/apple-apple-reminders.md) | Apple Reminders via remindctl: add, list, complete. | `apple\apple-reminders` |
+| [`findmy`](../user-guide/skills/bundled/apple/apple-findmy.md) | Track Apple devices/AirTags via FindMy.app on macOS. | `apple\findmy` |
+| [`imessage`](../user-guide/skills/bundled/apple/apple-imessage.md) | Send and receive iMessages/SMS via the imsg CLI on macOS. | `apple\imessage` |
 
 ## autonomous-ai-agents
 
 | Skill | Description | Path |
 |-------|-------------|------|
-| [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code) | Delegate coding to Claude Code CLI (features, PRs). | `autonomous-ai-agents\claude-code` |
-| [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex) | Delegate coding to OpenAI Codex CLI (features, PRs). | `autonomous-ai-agents\codex` |
-| [`computer-use`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-computer-use) | Drive the desktop background-first; escalate on signal. | `autonomous-ai-agents\computer-use` |
-| [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) | Use, configure, theme, extend, and orchestrate Hermes Agent. | `autonomous-ai-agents\hermes-agent` |
-| [`merge-reconciler`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-merge-reconciler) | Neutral third-party resolution of agent merge conflicts. | `autonomous-ai-agents\merge-reconciler` |
-| [`opencode`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode) | Delegate coding to OpenCode CLI (features, PR review). | `autonomous-ai-agents\opencode` |
+| [`claude-code`](../user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md) | Delegate coding to Claude Code CLI (features, PRs). | `autonomous-ai-agents\claude-code` |
+| [`codex`](../user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md) | Delegate coding to OpenAI Codex CLI (features, PRs). | `autonomous-ai-agents\codex` |
+| [`computer-use`](../user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-computer-use.md) | Drive the desktop background-first; escalate on signal. | `autonomous-ai-agents\computer-use` |
+| [`hermes-agent`](../user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md) | Use, configure, theme, extend, and orchestrate Hermes Agent. | `autonomous-ai-agents\hermes-agent` |
+| [`merge-reconciler`](../user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-merge-reconciler.md) | Neutral third-party resolution of agent merge conflicts. | `autonomous-ai-agents\merge-reconciler` |
+| [`opencode`](../user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md) | Delegate coding to OpenCode CLI (features, PR review). | `autonomous-ai-agents\opencode` |
 
 ## creative
 
 | Skill | Description | Path |
 |-------|-------------|------|
-| [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) | Dark-themed SVG architecture/cloud/infra diagrams as HTML. | `creative\architecture-diagram` |
-| [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video) | ASCII video: convert video/audio to colored ASCII MP4/GIF. | `creative\ascii-video` |
-| [`baoyu-infographic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic) | Infographics: 21 layouts x 21 styles (信息图, 可视化). | `creative\baoyu-infographic` |
-| [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design) | Design one-off HTML artifacts (landing, deck, prototype). | `creative\claude-design` |
-| [`design-md`](/docs/user-guide/skills/bundled/creative/creative-design-md) | Author/validate/export Google's DESIGN.md token spec files. | `creative\design-md` |
-| [`humanizer`](/docs/user-guide/skills/bundled/creative/creative-humanizer) | Humanize text: strip AI-isms and add real voice. | `creative\humanizer` |
-| [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video) | Manim CE animations: 3Blue1Brown math/algo videos. | `creative\manim-video` |
-| [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js) | p5.js sketches: gen art, shaders, interactive, 3D. | `creative\p5js` |
-| [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs) | 54 real design systems (Stripe, Linear, Vercel) as HTML/CSS. | `creative\popular-web-designs` |
-| [`songwriting-and-ai-music`](/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music) | Songwriting craft and Suno AI music prompts. | `creative\songwriting-and-ai-music` |
+| [`architecture-diagram`](../user-guide/skills/bundled/creative/creative-architecture-diagram.md) | Dark-themed SVG architecture/cloud/infra diagrams as HTML. | `creative\architecture-diagram` |
+| [`ascii-video`](../user-guide/skills/bundled/creative/creative-ascii-video.md) | ASCII video: convert video/audio to colored ASCII MP4/GIF. | `creative\ascii-video` |
+| [`baoyu-infographic`](../user-guide/skills/bundled/creative/creative-baoyu-infographic.md) | Infographics: 21 layouts x 21 styles (信息图, 可视化). | `creative\baoyu-infographic` |
+| [`claude-design`](../user-guide/skills/bundled/creative/creative-claude-design.md) | Design one-off HTML artifacts (landing, deck, prototype). | `creative\claude-design` |
+| [`design-md`](../user-guide/skills/bundled/creative/creative-design-md.md) | Author/validate/export Google's DESIGN.md token spec files. | `creative\design-md` |
+| [`humanizer`](../user-guide/skills/bundled/creative/creative-humanizer.md) | Humanize text: strip AI-isms and add real voice. | `creative\humanizer` |
+| [`manim-video`](../user-guide/skills/bundled/creative/creative-manim-video.md) | Manim CE animations: 3Blue1Brown math/algo videos. | `creative\manim-video` |
+| [`p5js`](../user-guide/skills/bundled/creative/creative-p5js.md) | p5.js sketches: gen art, shaders, interactive, 3D. | `creative\p5js` |
+| [`popular-web-designs`](../user-guide/skills/bundled/creative/creative-popular-web-designs.md) | 54 real design systems (Stripe, Linear, Vercel) as HTML/CSS. | `creative\popular-web-designs` |
+| [`songwriting-and-ai-music`](../user-guide/skills/bundled/creative/creative-songwriting-and-ai-music.md) | Songwriting craft and Suno AI music prompts. | `creative\songwriting-and-ai-music` |
 
 ## devops
 
 | Skill | Description | Path |
 |-------|-------------|------|
-| [`sdlc-review`](/docs/user-guide/skills/bundled/devops/devops-sdlc-review) | Review Kanban handoffs and route verified outcomes. | `devops\sdlc-review` |
+| [`sdlc-review`](../user-guide/skills/bundled/devops/devops-sdlc-review.md) | Review Kanban handoffs and route verified outcomes. | `devops\sdlc-review` |
 
 ## email
 
 | Skill | Description | Path |
 |-------|-------------|------|
-| [`email-inbox-triage`](/docs/user-guide/skills/bundled/email/email-email-inbox-triage) | Triage an inbox: prioritize threads, draft replies safely. | `email\email-inbox-triage` |
-| [`himalaya`](/docs/user-guide/skills/bundled/email/email-himalaya) | Himalaya CLI: IMAP/SMTP email from terminal. | `email\himalaya` |
+| [`email-inbox-triage`](../user-guide/skills/bundled/email/email-email-inbox-triage.md) | Triage an inbox: prioritize threads, draft replies safely. | `email\email-inbox-triage` |
+| [`himalaya`](../user-guide/skills/bundled/email/email-himalaya.md) | Himalaya CLI: IMAP/SMTP email from terminal. | `email\himalaya` |
 
 ## media
 
 | Skill | Description | Path |
 |-------|-------------|------|
-| [`gif-search`](/docs/user-guide/skills/bundled/media/media-gif-search) | Search/download GIFs from Tenor via curl + jq. | `media\gif-search` |
-| [`songsee`](/docs/user-guide/skills/bundled/media/media-songsee) | Audio spectrograms/features (mel, chroma, MFCC) via CLI. | `media\songsee` |
-| [`youtube-content`](/docs/user-guide/skills/bundled/media/media-youtube-content) | YouTube transcripts to summaries, threads, blogs. | `media\youtube-content` |
+| [`gif-search`](../user-guide/skills/bundled/media/media-gif-search.md) | Search/download GIFs from Tenor via curl + jq. | `media\gif-search` |
+| [`songsee`](../user-guide/skills/bundled/media/media-songsee.md) | Audio spectrograms/features (mel, chroma, MFCC) via CLI. | `media\songsee` |
+| [`youtube-content`](../user-guide/skills/bundled/media/media-youtube-content.md) | YouTube transcripts to summaries, threads, blogs. | `media\youtube-content` |
 
 ## note-taking
 
 | Skill | Description | Path |
 |-------|-------------|------|
-| [`obsidian`](/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian) | Read, search, create, and edit notes in the Obsidian vault. | `note-taking\obsidian` |
+| [`obsidian`](../user-guide/skills/bundled/note-taking/note-taking-obsidian.md) | Read, search, create, and edit notes in the Obsidian vault. | `note-taking\obsidian` |
 
 ## productivity
 
 | Skill | Description | Path |
 |-------|-------------|------|
-| [`airtable`](/docs/user-guide/skills/bundled/productivity/productivity-airtable) | Airtable REST API via curl. Records CRUD, filters, upserts. | `productivity\airtable` |
-| [`box`](/docs/user-guide/skills/bundled/productivity/productivity-box) | Box manages cloud files, sharing, search, and metadata. | `productivity\box` |
-| [`document-to-action-items`](/docs/user-guide/skills/bundled/productivity/productivity-document-to-action-items) | Extract cited obligations, deadlines, tasks from documents. | `productivity\document-to-action-items` |
-| [`docx`](/docs/user-guide/skills/bundled/productivity/productivity-docx) | Create, read, edit, template, and review Word .docx files. | `productivity\docx` |
-| [`google-workspace`](/docs/user-guide/skills/bundled/productivity/productivity-google-workspace) | Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python. | `productivity\google-workspace` |
-| [`maps`](/docs/user-guide/skills/bundled/productivity/productivity-maps) | Geocode, POIs, routes, timezones via OpenStreetMap/OSRM. | `productivity\maps` |
-| [`meeting-action-items`](/docs/user-guide/skills/bundled/productivity/productivity-meeting-action-items) | Turn meeting notes into cited decisions, owners, tickets. | `productivity\meeting-action-items` |
-| [`notion`](/docs/user-guide/skills/bundled/productivity/productivity-notion) | Notion API + ntn CLI: pages, databases, markdown, Workers. | `productivity\notion` |
-| [`pdf`](/docs/user-guide/skills/bundled/productivity/productivity-pdf) | PDF files: create, read, merge, fill, OCR, edit text. | `productivity\pdf` |
-| [`powerpoint`](/docs/user-guide/skills/bundled/productivity/productivity-powerpoint) | Create, read, edit .pptx decks with python-pptx. | `productivity\powerpoint` |
-| [`product-price-monitor`](/docs/user-guide/skills/bundled/productivity/productivity-product-price-monitor) | Watch product, flight, or listing prices; alert on target. | `productivity\product-price-monitor` |
-| [`teams-meeting-pipeline`](/docs/user-guide/skills/bundled/productivity/productivity-teams-meeting-pipeline) | Teams meeting summaries, job replay, Graph subscriptions. | `productivity\teams-meeting-pipeline` |
-| [`weekly-review-planning`](/docs/user-guide/skills/bundled/productivity/productivity-weekly-review-planning) | Weekly reset: commitments, stalled work, next-week plan. | `productivity\weekly-review-planning` |
-| [`xlsx`](/docs/user-guide/skills/bundled/productivity/productivity-xlsx) | Create, read, edit Excel .xlsx workbooks and CSVs. | `productivity\xlsx` |
+| [`airtable`](../user-guide/skills/bundled/productivity/productivity-airtable.md) | Airtable REST API via curl. Records CRUD, filters, upserts. | `productivity\airtable` |
+| [`box`](../user-guide/skills/bundled/productivity/productivity-box.md) | Box manages cloud files, sharing, search, and metadata. | `productivity\box` |
+| [`document-to-action-items`](../user-guide/skills/bundled/productivity/productivity-document-to-action-items.md) | Extract cited obligations, deadlines, tasks from documents. | `productivity\document-to-action-items` |
+| [`docx`](../user-guide/skills/bundled/productivity/productivity-docx.md) | Create, read, edit, template, and review Word .docx files. | `productivity\docx` |
+| [`google-workspace`](../user-guide/skills/bundled/productivity/productivity-google-workspace.md) | Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python. | `productivity\google-workspace` |
+| [`maps`](../user-guide/skills/bundled/productivity/productivity-maps.md) | Geocode, POIs, routes, timezones via OpenStreetMap/OSRM. | `productivity\maps` |
+| [`meeting-action-items`](../user-guide/skills/bundled/productivity/productivity-meeting-action-items.md) | Turn meeting notes into cited decisions, owners, tickets. | `productivity\meeting-action-items` |
+| [`notion`](../user-guide/skills/bundled/productivity/productivity-notion.md) | Notion API + ntn CLI: pages, databases, markdown, Workers. | `productivity\notion` |
+| [`pdf`](../user-guide/skills/bundled/productivity/productivity-pdf.md) | PDF files: create, read, merge, fill, OCR, edit text. | `productivity\pdf` |
+| [`powerpoint`](../user-guide/skills/bundled/productivity/productivity-powerpoint.md) | Create, read, edit .pptx decks with python-pptx. | `productivity\powerpoint` |
+| [`product-price-monitor`](../user-guide/skills/bundled/productivity/productivity-product-price-monitor.md) | Watch product, flight, or listing prices; alert on target. | `productivity\product-price-monitor` |
+| [`teams-meeting-pipeline`](../user-guide/skills/bundled/productivity/productivity-teams-meeting-pipeline.md) | Teams meeting summaries, job replay, Graph subscriptions. | `productivity\teams-meeting-pipeline` |
+| [`weekly-review-planning`](../user-guide/skills/bundled/productivity/productivity-weekly-review-planning.md) | Weekly reset: commitments, stalled work, next-week plan. | `productivity\weekly-review-planning` |
+| [`xlsx`](../user-guide/skills/bundled/productivity/productivity-xlsx.md) | Create, read, edit Excel .xlsx workbooks and CSVs. | `productivity\xlsx` |
 
 ## research
 
 | Skill | Description | Path |
 |-------|-------------|------|
-| [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv) | Search arXiv papers by keyword, author, category, or ID. | `research\arxiv` |
-| [`competitor-news-monitor`](/docs/user-guide/skills/bundled/research/research-competitor-news-monitor) | Watch named companies for material news; cited digests. | `research\competitor-news-monitor` |
-| [`grounded-citations`](/docs/user-guide/skills/bundled/research/research-grounded-citations) | Ground answers and documents in cited, verifiable sources. | `research\grounded-citations` |
-| [`llm-wiki`](/docs/user-guide/skills/bundled/research/research-llm-wiki) | Karpathy's LLM Wiki: build/query interlinked markdown KB. | `research\llm-wiki` |
+| [`arxiv`](../user-guide/skills/bundled/research/research-arxiv.md) | Search arXiv papers by keyword, author, category, or ID. | `research\arxiv` |
+| [`competitor-news-monitor`](../user-guide/skills/bundled/research/research-competitor-news-monitor.md) | Watch named companies for material news; cited digests. | `research\competitor-news-monitor` |
+| [`grounded-citations`](../user-guide/skills/bundled/research/research-grounded-citations.md) | Ground answers and documents in cited, verifiable sources. | `research\grounded-citations` |
+| [`llm-wiki`](../user-guide/skills/bundled/research/research-llm-wiki.md) | Karpathy's LLM Wiki: build/query interlinked markdown KB. | `research\llm-wiki` |
 
 ## social-media
 
 | Skill | Description | Path |
 |-------|-------------|------|
-| [`xurl`](/docs/user-guide/skills/bundled/social-media/social-media-xurl) | X/Twitter via xurl CLI: raw post search, posting, DM, media. | `social-media\xurl` |
+| [`xurl`](../user-guide/skills/bundled/social-media/social-media-xurl.md) | X/Twitter via xurl CLI: raw post search, posting, DM, media. | `social-media\xurl` |
 
 ## software-development
 
 | Skill | Description | Path |
 |-------|-------------|------|
-| [`codebase-inspection`](/docs/user-guide/skills/bundled/software-development/software-development-codebase-inspection) | Inspect codebases w/ pygount: LOC, languages, ratios. | `software-development\codebase-inspection` |
-| [`dogfood`](/docs/user-guide/skills/bundled/software-development/software-development-dogfood) | Exploratory QA of web apps: find bugs, evidence, reports. | `software-development\dogfood` |
-| [`github`](/docs/user-guide/skills/bundled/software-development/software-development-github) | GitHub via gh CLI: PRs, issues, reviews, repos, auth. | `software-development\github` |
-| [`hermes-agent-skill-authoring`](/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring) | Author in-repo SKILL.md files: frontmatter and structure. | `software-development\hermes-agent-skill-authoring` |
-| [`inspecting-hermes-desktop-dom`](/docs/user-guide/skills/bundled/software-development/software-development-inspecting-hermes-desktop-dom) | Read the live Hermes desktop DOM/CSS over CDP. | `software-development\inspecting-hermes-desktop-dom` |
-| [`node-inspect-debugger`](/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger) | Debug Node.js via --inspect + Chrome DevTools Protocol CLI. | `software-development\node-inspect-debugger` |
-| [`python-debugpy`](/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy) | Debug Python: pdb REPL + debugpy remote (DAP). | `software-development\python-debugpy` |
-| [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review) | Pre-commit review: security scan, quality gates, auto-fix. | `software-development\requesting-code-review` |
-| [`simplify-code`](/docs/user-guide/skills/bundled/software-development/software-development-simplify-code) | Parallel 4-agent cleanup of recent code changes. | `software-development\simplify-code` |
-| [`spike`](/docs/user-guide/skills/bundled/software-development/software-development-spike) | Throwaway experiments to validate an idea before build. | `software-development\spike` |
-| [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging) | 4-phase root cause debugging: understand bugs before fixing. | `software-development\systematic-debugging` |
-| [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development) | TDD: enforce RED-GREEN-REFACTOR, tests before code. | `software-development\test-driven-development` |
+| [`codebase-inspection`](../user-guide/skills/bundled/software-development/software-development-codebase-inspection.md) | Inspect codebases w/ pygount: LOC, languages, ratios. | `software-development\codebase-inspection` |
+| [`dogfood`](../user-guide/skills/bundled/software-development/software-development-dogfood.md) | Exploratory QA of web apps: find bugs, evidence, reports. | `software-development\dogfood` |
+| [`github`](../user-guide/skills/bundled/software-development/software-development-github.md) | GitHub via gh CLI: PRs, issues, reviews, repos, auth. | `software-development\github` |
+| [`hermes-agent-skill-authoring`](../user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md) | Author in-repo SKILL.md files: frontmatter and structure. | `software-development\hermes-agent-skill-authoring` |
+| [`inspecting-hermes-desktop-dom`](../user-guide/skills/bundled/software-development/software-development-inspecting-hermes-desktop-dom.md) | Read the live Hermes desktop DOM/CSS over CDP. | `software-development\inspecting-hermes-desktop-dom` |
+| [`node-inspect-debugger`](../user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md) | Debug Node.js via --inspect + Chrome DevTools Protocol CLI. | `software-development\node-inspect-debugger` |
+| [`python-debugpy`](../user-guide/skills/bundled/software-development/software-development-python-debugpy.md) | Debug Python: pdb REPL + debugpy remote (DAP). | `software-development\python-debugpy` |
+| [`requesting-code-review`](../user-guide/skills/bundled/software-development/software-development-requesting-code-review.md) | Pre-commit review: security scan, quality gates, auto-fix. | `software-development\requesting-code-review` |
+| [`simplify-code`](../user-guide/skills/bundled/software-development/software-development-simplify-code.md) | Parallel 4-agent cleanup of recent code changes. | `software-development\simplify-code` |
+| [`spike`](../user-guide/skills/bundled/software-development/software-development-spike.md) | Throwaway experiments to validate an idea before build. | `software-development\spike` |
+| [`systematic-debugging`](../user-guide/skills/bundled/software-development/software-development-systematic-debugging.md) | 4-phase root cause debugging: understand bugs before fixing. | `software-development\systematic-debugging` |
+| [`test-driven-development`](../user-guide/skills/bundled/software-development/software-development-test-driven-development.md) | TDD: enforce RED-GREEN-REFACTOR, tests before code. | `software-development\test-driven-development` |
 
 ## web
 
 | Skill | Description | Path |
 |-------|-------------|------|
-| [`blocked-page-recovery`](/docs/user-guide/skills/bundled/web/web-blocked-page-recovery) | Use when a fetch fails: 403/429, paywall, WAF, bot wall. | `web\blocked-page-recovery` |
+| [`blocked-page-recovery`](../user-guide/skills/bundled/web/web-blocked-page-recovery.md) | Use when a fetch fails: 403/429, paywall, WAF, bot wall. | `web\blocked-page-recovery` |
diff --git a/website/docs/reference/tools-reference.md b/website/docs/reference/tools-reference.md
index 96a6cc2a43..4ebc3a670e 100644
--- a/website/docs/reference/tools-reference.md
+++ b/website/docs/reference/tools-reference.md
@@ -11,7 +11,7 @@ This page documents Hermes' built-in tools, grouped by toolset. Availability var
 **Quick counts (current registry):** ~86 tools — 10 browser tools (core) + 2 CDP-gated browser tools, 4 file tools, 4 Home Assistant tools, 2 terminal tools (`terminal`, `process`), 12 desktop-GUI tools (`read_terminal`, `close_terminal`, `open_preview`, `close_preview`, `read_preview`, `drive_preview`, `annotate_preview`, `read_window_below`, `focus_pane`, `react_to_message`, `tour`, `tip` — desktop-app sessions only), 2 web tools, 5 Feishu tools, 7 Spotify tools (registered by the bundled `spotify` plugin), 5 Yuanbao tools, 12 kanban tools (registered when the kanban dispatcher spawns the agent), 3 project tools (desktop/GUI sessions), 2 Discord tools, 3 video tools (`video_generate`, `xai_video_edit`, `xai_video_extend`), and a handful of standalone tools (`memory`, `clarify`, `delegate_task`, `execute_code`, `cronjob`, `session_search`, `skill_view`/`skill_manage`/`skills_list`, `text_to_speech`, `image_generate`, `vision_analyze`, `video_analyze`, `todo`, `computer_use`, `x_search`).
 
 :::tip MCP Tools
-In addition to built-in tools, Hermes can load tools dynamically from MCP servers. MCP tools appear with the prefix `mcp__<server>__` (e.g., `mcp__github__create_issue` for the `github` MCP server). See [MCP Integration](/user-guide/features/mcp) for configuration.
+In addition to built-in tools, Hermes can load tools dynamically from MCP servers. MCP tools appear with the prefix `mcp__<server>__` (e.g., `mcp__github__create_issue` for the `github` MCP server). See [MCP Integration](../user-guide/features/mcp.md) for configuration.
 :::
 
 ## `browser` toolset
@@ -145,7 +145,7 @@ Scoped to the Feishu document-comment handler. Drives comment read/write operati
 
 ## `kanban` toolset
 
-Registered when the agent is either (a) spawned by the kanban dispatcher (`HERMES_KANBAN_TASK` env set) or (b) running in a profile that explicitly enables the `kanban` toolset. Task-scoped workers use lifecycle tools for their assigned task; orchestrator profiles additionally get board-routing tools like `kanban_list` and `kanban_unblock`. See [Kanban Multi-Agent](/user-guide/features/kanban) for the full workflow.
+Registered when the agent is either (a) spawned by the kanban dispatcher (`HERMES_KANBAN_TASK` env set) or (b) running in a profile that explicitly enables the `kanban` toolset. Task-scoped workers use lifecycle tools for their assigned task; orchestrator profiles additionally get board-routing tools like `kanban_list` and `kanban_unblock`. See [Kanban Multi-Agent](../user-guide/features/kanban.md) for the full workflow.
 
 | Tool | Description | Requires environment |
 |------|-------------|----------------------|
@@ -327,7 +327,7 @@ Backends ship as plugins under `plugins/video_gen/<name>/`:
 - **OpenRouter** — every generative model on OpenRouter's video API (Veo 3.1, Sora 2 Pro, Kling 3, Seedance 2, Wan 3, Hailuo 3, Grok Imagine, FLUX 3 Video, …); text-to-video, image-to-video and reference-to-video; catalog and per-model limits fetched live (requires `OPENROUTER_API_KEY`, billed to your OpenRouter credit).
 - **DeepInfra** — live `video-gen` catalog over the OpenAI-compatible videos endpoint (requires `DEEPINFRA_API_KEY`).
 
-The single `video_generate` tool covers both modalities — pass `image_url` to animate a still, omit it to generate from text alone. The active backend auto-routes to the right endpoint. The tool's description is rebuilt at session start to reflect the active backend's actual capabilities (modalities, aspect ratios, resolutions, duration range, max reference images, audio support). See [Video Generation Provider Plugins](/developer-guide/video-gen-provider-plugin) for backend authoring.
+The single `video_generate` tool covers both modalities — pass `image_url` to animate a still, omit it to generate from text alone. The active backend auto-routes to the right endpoint. The tool's description is rebuilt at session start to reflect the active backend's actual capabilities (modalities, aspect ratios, resolutions, duration range, max reference images, audio support). See [Video Generation Provider Plugins](../developer-guide/video-gen-provider-plugin.md) for backend authoring.
 
 | Tool | Description | Requires environment |
 |------|-------------|----------------------|
diff --git a/website/docs/user-guide/bot-mode.md b/website/docs/user-guide/bot-mode.md
index c2a4d0839d..bb32f1d36a 100644
--- a/website/docs/user-guide/bot-mode.md
+++ b/website/docs/user-guide/bot-mode.md
@@ -144,7 +144,7 @@ Use the **Move up** and **Move down** arrows beside a room to choose its positio
 - **Mentions read as identities.** In the transcript a routed `@bot` mention, the human handoff `@user`, and the broadcasts `@everyone` / `@all` render as inline references (accent text, not pills); unknown `@words` and e-mail addresses stay plain. Hover a Bot's message and use **Reply to @handle** to seed `@handle ` into the composer, so your next send goes to that Bot only (when a same-named Bot from a Connection shares the room, the tag is device-qualified, e.g. `@reviewer-mini` / `@reviewer-local`) — **Reply in thread** still continues the whole thread. If a reply box for a *different* thread is open, **Reply to** seeds the main composer instead and so starts a fresh thread; use **Reply in thread** to continue that thread.
 - **Rooms can span machines.** **New Group Chat** is available as soon as two Bots are selectable across all your registered connections — one Bot on this device plus one on another gateway is enough. The picker seats Bots from any registered connection; each member's turns run on its own machine, in its own room session there. Cross-machine members carry a device badge (`dixie · Mac Mini`) in the room and in other members' transcripts, and the disambiguated `@name-device` handle works in room mentions — so same-named agents on two machines never blur together.
 - **Rooms show the same identity as the roster.** Transcript rows, the “X is thinking…” line and Activity rows resolve each member's title and avatar by its owning connection and profile — re-titling a Bot or changing its picture updates every room it sits in, remote members keep their own titles, and two same-named Bots on different connections never borrow each other's avatar. When two members would still read identically, Activity appends the connection label (`Reviewer · Mac Mini`).
-- **Plugins can watch members work.** The durable room log records `turn.started` and `turn.settled`; what a member does in between (tools, approvals, streamed text) is projected to plugins through the [`on_room_member_activity`](/user-guide/features/hooks#on_room_member_activity) hook with room, member and turn coordinates, so community clients can build tool cards and live member status on top of Group Chat without reading Hermes internals.
+- **Plugins can watch members work.** The durable room log records `turn.started` and `turn.settled`; what a member does in between (tools, approvals, streamed text) is projected to plugins through the [`on_room_member_activity`](./features/hooks.md#on_room_member_activity) hook with room, member and turn coordinates, so community clients can build tool cards and live member status on top of Group Chat without reading Hermes internals.
 
 ## Bot-to-bot messaging
 
diff --git a/website/docs/user-guide/cli.md b/website/docs/user-guide/cli.md
index f873026f0f..084e241289 100644
--- a/website/docs/user-guide/cli.md
+++ b/website/docs/user-guide/cli.md
@@ -9,7 +9,7 @@ description: "Master the Hermes Agent terminal interface — commands, keybindin
 Hermes Agent's CLI is a full terminal user interface (TUI) — not a web UI. It features multiline editing, slash-command autocomplete, conversation history, interrupt-and-redirect, and streaming tool output. Built for people who live in the terminal.
 
 :::tip First-time setup
-One command — `hermes setup --portal` — and you're ready to `hermes chat`. See [Nous Portal](/integrations/nous-portal).
+One command — `hermes setup --portal` — and you're ready to `hermes chat`. See [Nous Portal](../integrations/nous-portal.md).
 :::
 
 :::tip
@@ -136,7 +136,7 @@ hermes plugins remove <plugin-name>
 
 Portable packages remain disabled until explicitly enabled. Hermes currently
 loads portable Agent Skills and stdio MCP entries. See the
-[plugin developer guide](/developer-guide/plugins#portable-agent-plugins-v1-packages)
+[plugin developer guide](../developer-guide/plugins/index.md#portable-agent-plugins-v1-packages)
 for the exact supported subset and trust boundary.
 
 ## Interface Layout
@@ -200,7 +200,7 @@ When resuming a previous session (`hermes -c` or `hermes --resume <id>`), a "Pre
 | `Ctrl+X Ctrl+E` | Emacs-style alternate binding for the external editor (same behavior as `Ctrl+G`). |
 | `Ctrl+S` | **Stash the prompt.** Parks the current draft and clears the composer so you can send something else first. Press `Ctrl+S` again on an empty composer to bring the draft back (cursor at the end, attached images restored). Repeated presses build a stack rather than overwriting, so an earlier draft is never silently lost — with two or more stashed, `Ctrl+S` opens a browse panel (`↑`/`↓` to navigate, `Enter` to restore, `D` to discard, `Esc` or `Ctrl+S` to close). A `📌 N` badge in the status bar shows how many drafts are parked. Multi-line drafts round-trip exactly, including blank lines. The stash lives in memory for the session only — nothing is written to disk, since drafts often contain secrets. |
 | `Ctrl+C` | Interrupt agent (double-press within 2s to force exit) |
-| `Ctrl+T` / `F6` | Open the full-screen live subagent monitor without losing the composer draft. The live dock appears automatically above the status bar; arrows select a worker, `Enter` shows its recent log, `s` steers, and `x` requests stop with confirmation. See [Monitoring subagents](/user-guide/features/delegation#monitoring-running-subagents-agents). |
+| `Ctrl+T` / `F6` | Open the full-screen live subagent monitor without losing the composer draft. The live dock appears automatically above the status bar; arrows select a worker, `Enter` shows its recent log, `s` steers, and `x` requests stop with confirmation. See [Monitoring subagents](./features/delegation.md#monitoring-running-subagents-agents). |
 | `F7` | Toggle the live subagent dock between its multi-row preview and a single summary line without moving composer focus. |
 | `Ctrl+D` | Exit |
 | `Ctrl+Z` | Suspend Hermes to background (Unix only). Run `fg` in the shell to resume. |
@@ -279,7 +279,7 @@ quick_commands:
     target: /gateway restart
 ```
 
-Then type `/status`, `/gpu`, or `/restart` in any chat. See the [Configuration guide](/user-guide/configuration#quick-commands) for more examples.
+Then type `/status`, `/gpu`, or `/restart` in any chat. See the [Configuration guide](./configuration.md#quick-commands) for more examples.
 
 ## Preloading Skills at Launch
 
@@ -454,7 +454,7 @@ The CLI shows animated feedback as the agent works:
   ┊ 📄 web_extract (2.1s)
 ```
 
-Cycle through display modes with `/verbose`: `off → new → all → verbose`. This command can also be enabled for messaging platforms — see [configuration](/user-guide/configuration#display-settings).
+Cycle through display modes with `/verbose`: `off → new → all → verbose`. This command can also be enabled for messaging platforms — see [configuration](./configuration.md#display-settings).
 
 ### Tool Preview Length
 
diff --git a/website/docs/user-guide/configuring-models.md b/website/docs/user-guide/configuring-models.md
index e2f501c8f0..94345b2d61 100644
--- a/website/docs/user-guide/configuring-models.md
+++ b/website/docs/user-guide/configuring-models.md
@@ -9,10 +9,10 @@ Hermes uses two kinds of model slots:
 - **Main model** — what the agent thinks with. Every user message, every tool-call loop, every streamed response goes through this model.
 - **Auxiliary models** — smaller side-jobs the agent offloads. Context compression, vision (image analysis), web-page summarization, approval scoring, MCP tool routing, session-title generation, and skill search. Each has its own slot and can be overridden independently.
 
-This page covers configuring both from the dashboard. If you prefer config files or the CLI, jump to [Alternative methods](#alternative-methods) at the bottom. To run models on your own machine instead of a cloud provider, see [Local Models](/user-guide/local-models).
+This page covers configuring both from the dashboard. If you prefer config files or the CLI, jump to [Alternative methods](#alternative-methods) at the bottom. To run models on your own machine instead of a cloud provider, see [Local Models](./local-models.md).
 
 :::tip Fastest path: Nous Portal
-[Nous Portal](/user-guide/features/tool-gateway) provides 300+ models under one subscription. On a fresh install, run `hermes setup --portal` to log in and set Nous as your provider in one command. Inspect what's wired up with `hermes portal info`.
+[Nous Portal](./features/tool-gateway.md) provides 300+ models under one subscription. On a fresh install, run `hermes setup --portal` to log in and set Nous as your provider in one command. Inspect what's wired up with `hermes portal info`.
 
 - Portal subscribers also get **10% off token-billed providers**.
 :::
@@ -361,7 +361,7 @@ hermes config set model.aliases.grok x-ai/grok-4
 
 Both paths feed the same loader (`hermes_cli/model_switch.py`). Entries declared in `model_aliases:` take precedence over `model.aliases:` entries with the same name.
 
-Then `/model fav` or `/model grok` in chat. User aliases shadow built-in short names (`sonnet`, `kimi`, `opus`, etc.). See [Custom model aliases](/reference/slash-commands#custom-model-aliases) for the full reference.
+Then `/model fav` or `/model grok` in chat. User aliases shadow built-in short names (`sonnet`, `kimi`, `opus`, etc.). See [Custom model aliases](../reference/slash-commands.md#custom-model-aliases) for the full reference.
 
 ### `hermes model` subcommand
 
diff --git a/website/docs/user-guide/desktop.md b/website/docs/user-guide/desktop.md
index b6ff3720e8..fc77e3ce87 100644
--- a/website/docs/user-guide/desktop.md
+++ b/website/docs/user-guide/desktop.md
@@ -135,7 +135,7 @@ A real terminal lives in the right sidebar, next to the file browser:
 
 ### Live subagents
 
-While delegated workers are live, a **Subagents** frame appears above the composer with their count, task names, elapsed time, and latest activity. It previews up to three workers; expand the header for the roster, then select a worker for details and **Steer** / **Stop** controls. Each frame belongs to its chat, including in split panes. Steering acknowledges that guidance is queued for a checkpoint, not that the child has already read it. See [Monitoring subagents](/user-guide/features/delegation#monitoring-running-subagents-agents).
+While delegated workers are live, a **Subagents** frame appears above the composer with their count, task names, elapsed time, and latest activity. It previews up to three workers; expand the header for the roster, then select a worker for details and **Steer** / **Stop** controls. Each frame belongs to its chat, including in split panes. Steering acknowledges that guidance is queued for a checkpoint, not that the child has already read it. See [Monitoring subagents](./features/delegation.md#monitoring-running-subagents-agents).
 
 ### Git review & worktrees
 
@@ -191,7 +191,7 @@ When `hermes gui` runs inside WSL2 with `/dev/dxg` present and Mesa's `d3d12_dri
 
 Manage providers, models, tools, and credentials from a real UI instead of editing YAML. First-run onboarding gets you to your first message in seconds. The settings panes cover providers/keys, model selection, toolset configuration, MCP servers, the gateway, and session management.
 
-- **Providers settings pane** — a dedicated place to manage inference providers, with an Accounts / API-keys UX for signing in and storing credentials per provider. Accounts and API keys share the Settings **Applies to** selection: credential reads and edits, OAuth account removal, and sign-in launched here target the selected profile, not the active chat profile. The sign-in flow keeps that target through credential saving and model selection. Changing **Applies to** discards unsaved credential drafts. Closing sign-in cancels polling and ignores late results; a credential write already sent may still finish in its original profile. Externally managed CLI credentials use their own CLI and are not covered by this profile selector. Its **Local Models** view installs and manages an on-device llama.cpp runtime — see [Local Models](/user-guide/local-models).
+- **Providers settings pane** — a dedicated place to manage inference providers, with an Accounts / API-keys UX for signing in and storing credentials per provider. Accounts and API keys share the Settings **Applies to** selection: credential reads and edits, OAuth account removal, and sign-in launched here target the selected profile, not the active chat profile. The sign-in flow keeps that target through credential saving and model selection. Changing **Applies to** discards unsaved credential drafts. Closing sign-in cancels polling and ignores late results; a credential write already sent may still finish in its original profile. Externally managed CLI credentials use their own CLI and are not covered by this profile selector. Its **Local Models** view installs and manages an on-device llama.cpp runtime — see [Local Models](./local-models.md).
 - **Every provider and model in the menus** — the GUI surfaces the full provider list and every model that `hermes model` knows about, so you pick from the same catalog the CLI sees rather than a curated subset.
 - **xAI Grok OAuth** — Grok is a first-class OAuth provider in the launcher; sign in through the browser flow like the other OAuth providers.
 - **Tool-backend installs from the GUI** — run a tool backend's post-setup install steps directly from the app instead of dropping to a terminal. In the terminal backend picker, selecting a backend marked **Needs setup** asks for confirmation first; declining leaves the current backend selected.
diff --git a/website/docs/user-guide/docker.md b/website/docs/user-guide/docker.md
index 773e985c01..def63ea1f0 100644
--- a/website/docs/user-guide/docker.md
+++ b/website/docs/user-guide/docker.md
@@ -40,7 +40,7 @@ docker run -it --rm \
 This drops you into the setup wizard, which will prompt you for your API keys and write them to `~/.hermes/.env`. You only need to do this once. It is highly recommended to set up a chat system for the gateway to work with at this point.
 
 :::tip
-Inside the container, run `hermes setup --portal` once — the refresh token persists in the mounted `~/.hermes` volume. See [Nous Portal](/integrations/nous-portal).
+Inside the container, run `hermes setup --portal` once — the refresh token persists in the mounted `~/.hermes` volume. See [Nous Portal](../integrations/nous-portal.md).
 :::
 
 ## Running in gateway mode
@@ -506,7 +506,7 @@ The official image is based on `debian:13.4` and includes:
 - Playwright with Chromium (`npx playwright install --with-deps chromium --only-shell`)
 - ripgrep, ffmpeg, git, and `xz-utils` as system utilities
 - **`docker-cli`** — so agents running inside the container can drive the host's Docker daemon (bind-mount `/var/run/docker.sock` to opt in) for `docker build`, `docker run`, container inspection, etc.
-- **`openssh-client`** — enables the [SSH terminal backend](/user-guide/configuration#ssh-backend) from inside the container. The SSH backend shells out to the system `ssh` binary; without this, it failed silently in containerized installs.
+- **`openssh-client`** — enables the [SSH terminal backend](./configuration.md#ssh-backend) from inside the container. The SSH backend shells out to the system `ssh` binary; without this, it failed silently in containerized installs.
 - The WhatsApp bridge (`scripts/whatsapp-bridge/`)
 - **[`s6-overlay`](https://github.com/just-containers/s6-overlay) v3** as PID 1 (replaces the older `tini`) — supervises the dashboard and per-profile gateways with auto-restart on crash, reaps zombie subprocesses, and forwards signals.
 
diff --git a/website/docs/user-guide/egress/network-isolation.md b/website/docs/user-guide/egress/network-isolation.md
index 0c0049974b..3c81ade847 100644
--- a/website/docs/user-guide/egress/network-isolation.md
+++ b/website/docs/user-guide/egress/network-isolation.md
@@ -196,6 +196,6 @@ docker compose exec gateway \
 ## Related
 
 - [SECURITY.md](https://github.com/NousResearch/hermes-agent/blob/main/SECURITY.md) — Hermes trust model and vulnerability reporting
-- [Docker](/user-guide/docker) — running Hermes in a container
+- [Docker](../docker.md) — running Hermes in a container
 - [Egress proxy](iron-proxy.md) — credential-injection firewall for the sandbox
 - [docker-compose.yml](https://github.com/NousResearch/hermes-agent/blob/main/docker-compose.yml) — default compose configuration
diff --git a/website/docs/user-guide/features/api-server.md b/website/docs/user-guide/features/api-server.md
index 74a55ee20d..9e8fc51379 100644
--- a/website/docs/user-guide/features/api-server.md
+++ b/website/docs/user-guide/features/api-server.md
@@ -11,7 +11,7 @@ The API server exposes hermes-agent as an OpenAI-compatible HTTP endpoint. Any f
 Your agent handles requests with its full toolset (terminal, file operations, web search, memory, skills) and returns the final response. When streaming, tool progress indicators appear inline so frontends can show what the agent is doing.
 
 :::tip One backend covers models + tools
-Hermes itself needs a configured provider and tool backends for the API server to be useful. A [Nous Portal](/user-guide/features/tool-gateway) subscription handles both — 300+ models plus web/image/TTS/browser via the Tool Gateway. Run `hermes setup --portal` once before starting the API server and frontends like Open WebUI or LobeChat get a fully tool-equipped backend.
+Hermes itself needs a configured provider and tool backends for the API server to be useful. A [Nous Portal](./tool-gateway.md) subscription handles both — 300+ models plus web/image/TTS/browser via the Tool Gateway. Run `hermes setup --portal` once before starting the API server and frontends like Open WebUI or LobeChat get a fully tool-equipped backend.
 :::
 
 ## Quick Start
@@ -51,7 +51,7 @@ curl http://localhost:8642/v1/chat/completions \
   -d '{"model": "hermes-agent", "messages": [{"role": "user", "content": "Hello!"}]}'
 ```
 
-Or connect Open WebUI, LobeChat, or any other frontend — see the [Open WebUI integration guide](/user-guide/messaging/open-webui) for step-by-step instructions.
+Or connect Open WebUI, LobeChat, or any other frontend — see the [Open WebUI integration guide](../messaging/open-webui.md) for step-by-step instructions.
 
 ## Endpoints
 
@@ -200,7 +200,7 @@ Delete a stored response.
 
 ### GET /v1/models
 
-Lists the agent as an available model. The advertised model name defaults to the [profile](/user-guide/profiles) name (or `hermes-agent` for the default profile). Required by most frontends for model discovery.
+Lists the agent as an available model. The advertised model name defaults to the [profile](../profiles.md) name (or `hermes-agent` for the default profile). Required by most frontends for model discovery.
 
 `/v1/models` is intentionally the cheap OpenAI-compat surface. It does **not**
 enumerate every authenticated provider/model combination Hermes can route to,
@@ -656,7 +656,7 @@ Configure the key via `API_SERVER_KEY` env var. If you need a browser to call He
 
 ### Multi-profile routing (`/p/<profile>/…`)
 
-When [multi-profile gateway routing](/user-guide/multi-profile-gateways) is
+When [multi-profile gateway routing](../multi-profile-gateways.md) is
 enabled (`gateway.multiplex_profiles`), the shared listener serves every
 profile through a `/p/<profile>/` URL prefix — and **authentication is bound
 to the routed profile**:
@@ -748,7 +748,7 @@ Any frontend that supports the OpenAI API format works. Tested/documented integr
 
 | Frontend | Stars | Connection |
 |----------|-------|------------|
-| [Open WebUI](/user-guide/messaging/open-webui) | 126k | Full guide available |
+| [Open WebUI](../messaging/open-webui.md) | 126k | Full guide available |
 | LobeChat | 73k | Custom provider endpoint |
 | LibreChat | 34k | Custom endpoint in librechat.yaml |
 | AnythingLLM | 56k | Generic OpenAI provider |
@@ -762,7 +762,7 @@ Any frontend that supports the OpenAI API format works. Tested/documented integr
 
 ## Multi-User Setup with Profiles
 
-To give multiple users their own isolated Hermes instance (separate config, memory, skills), use [profiles](/user-guide/profiles):
+To give multiple users their own isolated Hermes instance (separate config, memory, skills), use [profiles](../profiles.md):
 
 ```bash
 # Create a profile per user
@@ -793,7 +793,7 @@ Each profile's API server automatically advertises the profile name as the model
 - `http://localhost:8643/v1/models` → model `alice`
 - `http://localhost:8644/v1/models` → model `bob`
 
-In Open WebUI, add each as a separate connection. The model dropdown shows `alice` and `bob` as distinct models, each backed by a fully isolated Hermes instance. See the [Open WebUI guide](/user-guide/messaging/open-webui#multi-user-setup-with-profiles) for details.
+In Open WebUI, add each as a separate connection. The model dropdown shows `alice` and `bob` as distinct models, each backed by a fully isolated Hermes instance. See the [Open WebUI guide](../messaging/open-webui.md#multi-user-setup-with-profiles) for details.
 
 ## Limitations
 
@@ -807,4 +807,4 @@ In Open WebUI, add each as a separate connection. The model dropdown shows `alic
 
 The API server also serves as the backend for **gateway proxy mode**. When another Hermes gateway instance is configured with `GATEWAY_PROXY_URL` pointing at this API server, it forwards all messages here instead of running its own agent. This enables split deployments — for example, a Docker container handling Matrix E2EE that relays to a host-side agent.
 
-See [Matrix Proxy Mode](/user-guide/messaging/matrix#proxy-mode-e2ee-on-macos) for the full setup guide.
+See [Matrix Proxy Mode](../messaging/matrix.md#proxy-mode-e2ee-on-macos) for the full setup guide.
diff --git a/website/docs/user-guide/features/batch-processing.md b/website/docs/user-guide/features/batch-processing.md
index 5a0cbacb90..cb86017543 100644
--- a/website/docs/user-guide/features/batch-processing.md
+++ b/website/docs/user-guide/features/batch-processing.md
@@ -35,7 +35,7 @@ python batch_runner.py --list_distributions
 ```
 
 :::tip Predictable cost at scale
-Batch runs spin up many concurrent agent sessions, each making model calls and tool calls. A [Nous Portal](/user-guide/features/tool-gateway) subscription bundles model access plus web search, image gen, TTS, and cloud browsers under one bill — useful when you want stable cost-per-trajectory without juggling rate limits across five vendor accounts. Set up with `hermes setup --portal`, then point `--model` at a Nous model.
+Batch runs spin up many concurrent agent sessions, each making model calls and tool calls. A [Nous Portal](./tool-gateway.md) subscription bundles model access plus web search, image gen, TTS, and cloud browsers under one bill — useful when you want stable cost-per-trajectory without juggling rate limits across five vendor accounts. Set up with `hermes setup --portal`, then point `--model` at a Nous model.
 :::
 
 ## Dataset Format
diff --git a/website/docs/user-guide/features/built-in-plugins.md b/website/docs/user-guide/features/built-in-plugins.md
index 5203ff9e7a..ad5663f207 100644
--- a/website/docs/user-guide/features/built-in-plugins.md
+++ b/website/docs/user-guide/features/built-in-plugins.md
@@ -9,7 +9,7 @@ description: "Plugins shipped with Hermes Agent that run automatically via lifec
 
 Hermes ships a small set of plugins bundled with the repository. They live under `<repo>/plugins/<name>/` and load automatically alongside user-installed plugins in `~/.hermes/plugins/`. They use the same plugin surface as third-party plugins — hooks, tools, slash commands — just maintained in-tree.
 
-See the [Plugins](/user-guide/features/plugins) page for the general plugin system, and [Build a Hermes Plugin](/developer-guide/plugins) to write your own.
+See the [Plugins](./plugins.md) page for the general plugin system, and [Build a Hermes Plugin](../../developer-guide/plugins/index.md) to write your own.
 
 ## How discovery works
 
@@ -350,7 +350,7 @@ Adds a **Steam-style achievements tab to the dashboard** — 60+ collectible, ti
 
 ## Adding a bundled plugin
 
-Bundled plugins are written exactly like any other Hermes plugin — see [Build a Hermes Plugin](/developer-guide/plugins). The only differences are:
+Bundled plugins are written exactly like any other Hermes plugin — see [Build a Hermes Plugin](../../developer-guide/plugins/index.md). The only differences are:
 
 - Directory lives at `<repo>/plugins/<name>/` instead of `~/.hermes/plugins/<name>/`
 - Manifest source is reported as `bundled` in `hermes plugins list`
diff --git a/website/docs/user-guide/features/code-execution.md b/website/docs/user-guide/features/code-execution.md
index 0736de5500..fea567d566 100644
--- a/website/docs/user-guide/features/code-execution.md
+++ b/website/docs/user-guide/features/code-execution.md
@@ -240,7 +240,7 @@ terminal:
     - ANOTHER_TOKEN
 ```
 
-See the [Security guide](/user-guide/security#environment-variable-passthrough) for full details.
+See the [Security guide](../security.md#environment-variable-passthrough) for full details.
 
 ### `HERMES_*` variables in the child
 
@@ -310,7 +310,7 @@ Hermes always writes the script and the auto-generated `hermes_tools.py` RPC stu
 | Running a build or test suite | ❌ | ✅ |
 | Looping over search results | ✅ | ❌ |
 | Interactive/background processes | ❌ | ✅ |
-| Needs API keys in environment | ⚠️ Only via [passthrough](/user-guide/security#environment-variable-passthrough) | ✅ (most pass through) |
+| Needs API keys in environment | ⚠️ Only via [passthrough](../security.md#environment-variable-passthrough) | ✅ (most pass through) |
 
 **Rule of thumb:** Use `execute_code` when you need to call Hermes tools programmatically with logic between calls. Use `terminal` for running shell commands, builds, and processes.
 
diff --git a/website/docs/user-guide/features/codex-app-server-runtime.md b/website/docs/user-guide/features/codex-app-server-runtime.md
index 4119697ab7..9c85c01891 100644
--- a/website/docs/user-guide/features/codex-app-server-runtime.md
+++ b/website/docs/user-guide/features/codex-app-server-runtime.md
@@ -10,7 +10,7 @@ Hermes can optionally hand `openai/*` and `openai-codex/*` turns to the [Codex C
 This is **opt-in only**. Default Hermes behavior is unchanged unless you flip the flag. Hermes never auto-routes you onto this runtime.
 
 :::tip
-Not using OpenAI Codex? `hermes setup --portal` configures a non-Codex backend with Claude/Gemini/etc. in one step. See [Nous Portal](/integrations/nous-portal).
+Not using OpenAI Codex? `hermes setup --portal` configures a non-Codex backend with Claude/Gemini/etc. in one step. See [Nous Portal](../../integrations/nous-portal.md).
 :::
 
 ## Why
diff --git a/website/docs/user-guide/features/context-files.md b/website/docs/user-guide/features/context-files.md
index aeff4cadf0..45329568e0 100644
--- a/website/docs/user-guide/features/context-files.md
+++ b/website/docs/user-guide/features/context-files.md
@@ -97,7 +97,7 @@ This is a Next.js 14 web application with a Python FastAPI backend.
 
 ## SOUL.md
 
-`SOUL.md` controls the agent's personality, tone, and communication style. See the [Personality](/user-guide/features/personality) page for full details.
+`SOUL.md` controls the agent's personality, tone, and communication style. See the [Personality](./personality.md) page for full details.
 
 **Location:**
 
diff --git a/website/docs/user-guide/features/credential-pools.md b/website/docs/user-guide/features/credential-pools.md
index 07322cf4eb..2292f0977f 100644
--- a/website/docs/user-guide/features/credential-pools.md
+++ b/website/docs/user-guide/features/credential-pools.md
@@ -16,7 +16,7 @@ Provider-side prompt caches (Anthropic, OpenAI, OpenRouter) are scoped to the ac
 :::
 
 :::tip
-Credential pools are mainly for API-key providers (OpenRouter, Anthropic). A single [Nous Portal](/integrations/nous-portal) OAuth covers 300+ models, so most users don't need a pool when on Portal.
+Credential pools are mainly for API-key providers (OpenRouter, Anthropic). A single [Nous Portal](../../integrations/nous-portal.md) OAuth covers 300+ models, so most users don't need a pool when on Portal.
 :::
 
 ## How It Works
diff --git a/website/docs/user-guide/features/cron.md b/website/docs/user-guide/features/cron.md
index 9d7681f806..f9180d2d65 100644
--- a/website/docs/user-guide/features/cron.md
+++ b/website/docs/user-guide/features/cron.md
@@ -18,7 +18,7 @@ Cron jobs can:
 - deliver results back to the origin chat, local files, or configured platform targets
 - run in fresh agent sessions with the normal static tool list
 - run in **no-agent mode** — a script on a schedule, its stdout delivered verbatim, zero LLM involvement (see the [no-agent mode](#no-agent-mode-script-only-jobs) section below)
-- fire on **external events** — a webhook route with `cron_job` set fires the job the moment something happens (a PR gets feedback, a service posts an alert) instead of waiting for the next scheduled tick. See [Event-Triggered Cron Jobs](/user-guide/messaging/webhooks#event-triggered-cron-jobs).
+- fire on **external events** — a webhook route with `cron_job` set fires the job the moment something happens (a PR gets feedback, a service posts an alert) instead of waiting for the next scheduled tick. See [Event-Triggered Cron Jobs](../messaging/webhooks.md#event-triggered-cron-jobs).
 
 All of this is available to Hermes itself through the `cronjob` tool, so you can create, pause, edit, and remove jobs by asking in plain language — no CLI required.
 
@@ -31,7 +31,7 @@ All of this is available to Hermes itself through the `cronjob` tool, so you can
 
 Whichever provider a job resolves to, its provider-specific request settings (e.g. `request_overrides` such as `extra_body`/`extra_headers` for custom providers) carry into the scheduled run just like an interactive session.
 
-`hermes setup --portal` is the lowest-friction option for unattended runs since OAuth refresh is automatic. See [Nous Portal](/integrations/nous-portal).
+`hermes setup --portal` is the lowest-friction option for unattended runs since OAuth refresh is automatic. See [Nous Portal](../../integrations/nous-portal.md).
 :::
 
 :::tip
@@ -903,7 +903,7 @@ cronjob(action="create", schedule="every 5m",
 
 It picks `no_agent=True` automatically when the message content is fully determined by the script (watchdogs, threshold alerts, heartbeats). The same tool also lets the agent pause, resume, edit, and remove jobs — so the whole lifecycle is chat-driven without anyone touching the CLI.
 
-See the [Script-Only Cron Jobs guide](/guides/cron-script-only) for worked examples.
+See the [Script-Only Cron Jobs guide](../../guides/cron-script-only.md) for worked examples.
 
 ## Chaining jobs with `context_from`
 
@@ -984,7 +984,7 @@ From the CLI: `hermes cron create "every 6h" "Scan for news" --continuity`, and
 Cron jobs inherit your configured fallback providers and credential pool rotation. If the primary API key is rate-limited or the provider returns an error, the cron agent can:
 
 - **Fall back to an alternate provider** if you have `fallback_providers` (or the legacy `fallback_model`) configured in `config.yaml`
-- **Rotate to the next credential** in your [credential pool](/user-guide/configuration#credential-pool-strategies) for the same provider
+- **Rotate to the next credential** in your [credential pool](../configuration.md#credential-pool-strategies) for the same provider
 
 This means cron jobs that run at high frequency or during peak hours are more resilient — a single rate-limited key won't fail the entire run.
 
diff --git a/website/docs/user-guide/features/curator.md b/website/docs/user-guide/features/curator.md
index 3bc5de4d66..da624362cd 100644
--- a/website/docs/user-guide/features/curator.md
+++ b/website/docs/user-guide/features/curator.md
@@ -8,7 +8,7 @@ description: "Background maintenance for agent-created skills — usage tracking
 
 The curator is a background maintenance pass for **agent-created skills**. It tracks how often each skill is viewed, used, and patched, moves long-unused skills through `active → stale → archived` states, and periodically spawns a short auxiliary-model review that proposes consolidations or patches drift.
 
-It exists so that skills created via the [self-improvement loop](/user-guide/features/skills#agent-managed-skills-skill_manage-tool) don't pile up forever. Every time the agent solves a novel problem and saves a skill, that skill lands in `~/.hermes/skills/`. Without maintenance, you end up with dozens of narrow near-duplicates that pollute the catalog and waste tokens.
+It exists so that skills created via the [self-improvement loop](./skills.md#agent-managed-skills-skill_manage-tool) don't pile up forever. Every time the agent solves a novel problem and saves a skill, that skill lands in `~/.hermes/skills/`. Without maintenance, you end up with dozens of narrow near-duplicates that pollute the catalog and waste tokens.
 
 By default (`prune_builtins: true`) the curator can archive **unused bundled built-in skills** (shipped with the repo) after `archive_after_days` of non-use, alongside the agent-created skills it primarily manages. Hub-installed skills (from [agentskills.io](https://agentskills.io)) are always off-limits. Set `curator.prune_builtins: false` to restore the old agent-created-only behavior, where bundled skills are never touched. The curator also **never auto-deletes** — the worst outcome is archival into `~/.hermes/skills/.archive/`, which is recoverable.
 
@@ -403,7 +403,7 @@ The curator also refuses to run if `min_idle_hours` hasn't elapsed, so on an act
 
 ## See also
 
-- [Skills System](/user-guide/features/skills) — how skills work in general and the self-improvement loop that creates them
-- [Memory](/user-guide/features/memory) — a parallel background review that maintains long-term memory
-- [Bundled Skills Catalog](/reference/skills-catalog)
+- [Skills System](./skills.md) — how skills work in general and the self-improvement loop that creates them
+- [Memory](./memory.md) — a parallel background review that maintains long-term memory
+- [Bundled Skills Catalog](../../reference/skills-catalog.md)
 - [Issue #7816](https://github.com/NousResearch/hermes-agent/issues/7816) — original proposal and design discussion
diff --git a/website/docs/user-guide/features/delegation.md b/website/docs/user-guide/features/delegation.md
index b699df682b..93a793abdc 100644
--- a/website/docs/user-guide/features/delegation.md
+++ b/website/docs/user-guide/features/delegation.md
@@ -451,7 +451,7 @@ Press **F7** in the Classic CLI or TUI composer to toggle the dock between its m
 
 The live transcript tail is a bounded recent excerpt, not an unlimited conversation browser. A child leaving the live registry leaves the dock; completion messages and the TUI/Desktop history views remain the place to review finished work. Latest activity is an observation, not a percentage-complete estimate.
 
-The classic CLI's `/agents` and `/tasks` commands still print a text summary; **Ctrl+T** (or **F6**) is the immediate interactive monitor, including while the parent is busy. See [TUI — Slash commands](/user-guide/tui#slash-commands).
+The classic CLI's `/agents` and `/tasks` commands still print a text summary; **Ctrl+T** (or **F6**) is the immediate interactive monitor, including while the parent is busy. See [TUI — Slash commands](../tui.md#slash-commands).
 
 On the classic CLI and every gateway platform (Telegram, Discord, Slack, ...),
 `/agents` also lists **background delegations with live per-child activity**,
@@ -491,7 +491,7 @@ Control actions run synchronously in-turn (never backgrounded), are scoped to th
 
 ### From the TUI / gateway (session-facing)
 
-`steer_subagent(subagent_id, text)` in `tools/delegate_tool_registry.py` is the redirection-side mirror of `interrupt_subagent()`: it queues text into a live child through the same mechanism as [`/steer`](/reference/slash-commands) — the text is appended to the child's last tool result at its next iteration boundary, the in-flight tool call is never cut, and the child sees it as an out-of-band user message. Programmatic hosts reach it through the session-scoped `subagent.steer` gateway RPC, which sits beside `subagent.interrupt`:
+`steer_subagent(subagent_id, text)` in `tools/delegate_tool_registry.py` is the redirection-side mirror of `interrupt_subagent()`: it queues text into a live child through the same mechanism as [`/steer`](../../reference/slash-commands.md) — the text is appended to the child's last tool result at its next iteration boundary, the in-flight tool call is never cut, and the child sees it as an out-of-band user message. Programmatic hosts reach it through the session-scoped `subagent.steer` gateway RPC, which sits beside `subagent.interrupt`:
 
 ```json
 {"method": "subagent.steer", "params": {"session_id": "owning-ui-session", "subagent_id": "sa-0-1a2b3c4d", "text": "focus on pricing instead"}}
diff --git a/website/docs/user-guide/features/extending-the-dashboard.md b/website/docs/user-guide/features/extending-the-dashboard.md
index 50f4958b12..3b63b41bee 100644
--- a/website/docs/user-guide/features/extending-the-dashboard.md
+++ b/website/docs/user-guide/features/extending-the-dashboard.md
@@ -17,7 +17,7 @@ All three are **drop-in at runtime**: no repo clone, no `npm run build`, no patc
 If you just want to use the dashboard, see [Web Dashboard](./web-dashboard). If you want to reskin the terminal CLI (not the web dashboard), see [Skins & Themes](./skins) — the CLI skin system is unrelated to dashboard themes.
 
 :::note Not the desktop app
-This page covers the **web dashboard** (`hermes dashboard`) plugin system — `window.__HERMES_PLUGIN_SDK__`, a `manifest.json`, and a pre-built JS bundle. The **native desktop app** (`hermes desktop`) has its own, unrelated SDK — `@hermes/plugin-sdk`, a single ESM file, no build step — documented at [Desktop Plugin SDK](/developer-guide/desktop-plugin-sdk). Only the backend `plugin_api.py` namespace (`/api/plugins/<name>`) is shared between them.
+This page covers the **web dashboard** (`hermes dashboard`) plugin system — `window.__HERMES_PLUGIN_SDK__`, a `manifest.json`, and a pre-built JS bundle. The **native desktop app** (`hermes desktop`) has its own, unrelated SDK — `@hermes/plugin-sdk`, a single ESM file, no build step — documented at [Desktop Plugin SDK](../../developer-guide/desktop-plugin-sdk.md). Only the backend `plugin_api.py` namespace (`/api/plugins/<name>`) is shared between them.
 :::
 
 :::note How the pieces compose
diff --git a/website/docs/user-guide/features/fallback-providers.md b/website/docs/user-guide/features/fallback-providers.md
index 6d29867222..d8cf8f73af 100644
--- a/website/docs/user-guide/features/fallback-providers.md
+++ b/website/docs/user-guide/features/fallback-providers.md
@@ -297,7 +297,7 @@ All three — auxiliary, compression, fallback — work the same way: set `provi
 
 ### Provider Options for Auxiliary Tasks
 
-These options apply to `auxiliary:`, `compression:`, and `fallback_providers:` entries only — `"main"` is **not** a valid value for your top-level `model.provider`. For custom endpoints, use `provider: custom` in your `model:` section (see [AI Providers](/integrations/providers)).
+These options apply to `auxiliary:`, `compression:`, and `fallback_providers:` entries only — `"main"` is **not** a valid value for your top-level `model.provider`. For custom endpoints, use `provider: custom` in your `model:` section (see [AI Providers](../../integrations/providers.md)).
 
 | Provider | Description | Requirements |
 |----------|-------------|-------------|
@@ -409,7 +409,7 @@ delegation:
   # api_key: "local-key"
 ```
 
-See [Subagent Delegation](/user-guide/features/delegation) for full configuration details.
+See [Subagent Delegation](./delegation.md) for full configuration details.
 
 ---
 
@@ -427,7 +427,7 @@ cronjob(
 )
 ```
 
-See [Scheduled Tasks (Cron)](/user-guide/features/cron) for full configuration details.
+See [Scheduled Tasks (Cron)](./cron.md) for full configuration details.
 
 ---
 
diff --git a/website/docs/user-guide/features/goals.md b/website/docs/user-guide/features/goals.md
index cefadfff0b..7697da97e8 100644
--- a/website/docs/user-guide/features/goals.md
+++ b/website/docs/user-guide/features/goals.md
@@ -235,7 +235,7 @@ goals:
 
 ### Choosing the judge model
 
-The judge uses the `goal_judge` auxiliary task. By default it resolves to your main model (see [Auxiliary Models](/user-guide/configuration#auxiliary-models)). If you want to route the judge to a cheap fast model to keep costs down, add an override:
+The judge uses the `goal_judge` auxiliary task. By default it resolves to your main model (see [Auxiliary Models](../configuration.md#auxiliary-models)). If you want to route the judge to a cheap fast model to keep costs down, add an override:
 
 ```yaml
 auxiliary:
diff --git a/website/docs/user-guide/features/hooks.md b/website/docs/user-guide/features/hooks.md
index f11f292b98..3cb7873bab 100644
--- a/website/docs/user-guide/features/hooks.md
+++ b/website/docs/user-guide/features/hooks.md
@@ -11,7 +11,7 @@ Hermes has four hook systems that run custom code at key lifecycle points:
 | System | Registered via | Runs in | Use case |
 |--------|---------------|---------|----------|
 | **[Gateway hooks](#gateway-event-hooks)** | `HOOK.yaml` + `handler.py` in `~/.hermes/hooks/` | Gateway only | Logging, alerts, webhooks |
-| **[Plugin hooks](#plugin-hooks)** | `ctx.register_hook()` in a [plugin](/user-guide/features/plugins) | CLI + Gateway | Tool interception, metrics, guardrails |
+| **[Plugin hooks](#plugin-hooks)** | `ctx.register_hook()` in a [plugin](./plugins.md) | CLI + Gateway | Tool interception, metrics, guardrails |
 | **[Shell hooks](#shell-hooks)** | `hooks:` block in profile `config.yaml` pointing at shell scripts | CLI + Gateway + Desktop/TUI/dashboard chat | Drop-in scripts for blocking, auto-formatting, context injection |
 | **[Outbound webhooks](#outbound-webhooks)** | `hooks.outbound:` list in `~/.hermes/config.yaml` | CLI + Gateway | Push signed lifecycle events to external HTTP endpoints — CI, dashboards, other agents |
 
@@ -360,10 +360,10 @@ Gateway hooks only fire in the **gateway** (Telegram, Discord, Slack, WhatsApp,
 
 ## Plugin Hooks
 
-[Plugins](/user-guide/features/plugins) can register hooks that fire in **both CLI and gateway** sessions. These are registered programmatically via `ctx.register_hook()` in your plugin's `register()` function.
+[Plugins](./plugins.md) can register hooks that fire in **both CLI and gateway** sessions. These are registered programmatically via `ctx.register_hook()` in your plugin's `register()` function.
 
 For plugin packaging and registration details, see
-the [Plugins guide](/docs/user-guide/features/plugins).
+the [Plugins guide](./plugins.md).
 
 ```python
 def register(ctx):
@@ -1043,7 +1043,7 @@ def my_callback(session_id: str, platform: str, **kwargs):
 
 ---
 
-See the **[Build a Plugin guide](/developer-guide/plugins)** for the full walkthrough including tool schemas, handlers, and advanced hook patterns.
+See the **[Build a Plugin guide](../../developer-guide/plugins/index.md)** for the full walkthrough including tool schemas, handlers, and advanced hook patterns.
 
 ---
 
@@ -1391,7 +1391,7 @@ def register(ctx):
 
 ### `on_room_member_activity`
 
-Fires while a hosted [Group Chat](/user-guide/bot-mode#groups-and-group-chats) member turn runs. A member executes on a hidden `Group: <room>` session that no client is attached to, so between the room log's `turn.started` and `turn.settled` the turn is a black box. This hook projects the runtime events that session already produces — tool start/complete, approval requests, streamed text and reasoning, errors — stamped with the room coordinates, so a client (Hermes Crew, a dashboard, an audit log) can render tool cards, approval prompts and live member status without inferring anything from text. The Group Chat runtime keeps ownership of execution, scheduling and the durable log; plugins only observe.
+Fires while a hosted [Group Chat](../bot-mode.md#groups-and-group-chats) member turn runs. A member executes on a hidden `Group: <room>` session that no client is attached to, so between the room log's `turn.started` and `turn.settled` the turn is a black box. This hook projects the runtime events that session already produces — tool start/complete, approval requests, streamed text and reasoning, errors — stamped with the room coordinates, so a client (Hermes Crew, a dashboard, an audit log) can render tool cards, approval prompts and live member status without inferring anything from text. The Group Chat runtime keeps ownership of execution, scheduling and the durable log; plugins only observe.
 
 **Callback signature:**
 
@@ -1458,7 +1458,7 @@ def my_callback(
 | `provider` | `str` | Resolved STT provider (`local`, `groq`, `openai`, `mistral`, `xai`, `elevenlabs`, `deepinfra`, `local_command`, a command provider name, or a plugin provider name). |
 | `model` | `str \| None` | Model resolved so far, or `None` when the backend default applies. |
 | `language` | `str \| None` | Language from the provider's config section, or `None`. |
-| `prompt` | `str \| None` | The static [`stt.prompt`](/user-guide/configuration#transcription-prompt-vocabulary-hints) value, or `None`. |
+| `prompt` | `str \| None` | The static [`stt.prompt`](../configuration.md#transcription-prompt-vocabulary-hints) value, or `None`. |
 | `source` | `str \| None` | Caller surface label (`gateway`, `voice_mode`, …). Observability only, not used for dispatch. |
 
 **Return value:** a `dict` with any of `"prompt"`, `"language"`, `"model"` mapped to strings, or `None` to leave the request unchanged. Non-string values, unknown keys, and `file_path` are ignored (`file_path` attempts are logged as a warning). Results are applied in **registration order, last-writer-wins per field**, on top of the `stt.prompt` config value. Returning `""` for `prompt` clears the configured prompt for that request.
@@ -1477,7 +1477,7 @@ def register(ctx):
     ctx.register_hook("pre_transcription", add_vocab)
 ```
 
-Not every backend accepts a prompt. `local` maps it to faster-whisper's `initial_prompt`; `openai`, `groq`, `mistral`, and `deepinfra` send it as `prompt`; `xai`, `elevenlabs`, `local_command`, and `type: command` providers log at DEBUG and transcribe without it. See the [provider support table](/user-guide/configuration#transcription-prompt-vocabulary-hints) for the full matrix and the privacy boundary. Hook-plumbing errors are fail-open: the dispatch continues with the unmodified request.
+Not every backend accepts a prompt. `local` maps it to faster-whisper's `initial_prompt`; `openai`, `groq`, `mistral`, and `deepinfra` send it as `prompt`; `xai`, `elevenlabs`, `local_command`, and `type: command` providers log at DEBUG and transcribe without it. See the [provider support table](../configuration.md#transcription-prompt-vocabulary-hints) for the full matrix and the privacy boundary. Hook-plumbing errors are fail-open: the dispatch continues with the unmodified request.
 
 ---
 
@@ -1921,7 +1921,7 @@ Both Python plugin hooks and shell hooks flow through the same `invoke_hook()` d
 
 ## Outbound Webhooks
 
-Outbound webhooks are the push-side mirror of the [inbound webhook platform](/user-guide/messaging/webhooks): inbound webhooks wake Hermes when the world changes; outbound webhooks tell the world when Hermes does something. Configure a list of HTTP endpoints and the lifecycle events they care about, and Hermes POSTs a signed JSON payload to each endpoint whenever a matching event fires — no polling on the receiving end.
+Outbound webhooks are the push-side mirror of the [inbound webhook platform](../messaging/webhooks.md): inbound webhooks wake Hermes when the world changes; outbound webhooks tell the world when Hermes does something. Configure a list of HTTP endpoints and the lifecycle events they care about, and Hermes POSTs a signed JSON payload to each endpoint whenever a matching event fires — no polling on the receiving end.
 
 Typical uses:
 
diff --git a/website/docs/user-guide/features/kanban.md b/website/docs/user-guide/features/kanban.md
index 99d45aadcf..99fd8c8c03 100644
--- a/website/docs/user-guide/features/kanban.md
+++ b/website/docs/user-guide/features/kanban.md
@@ -677,7 +677,7 @@ For the occasional quality-sensitive card, pin just that task back to a stronger
 
 ### Lifecycle plugin hooks
 
-Board transitions fire [plugin hooks](/user-guide/features/hooks#plugin-hooks): `kanban_task_claimed`, `kanban_task_completed`, and `kanban_task_blocked`, each carrying `task_id` and `profile_name`. Hooks fire **after** the board DB change commits, so callbacks always see durable state. Note the process split: `kanban_task_claimed` fires in the **dispatcher** process, while `kanban_task_completed`/`kanban_task_blocked` fire in the **worker** process — register the hook in the dispatcher profile to observe every transition centrally.
+Board transitions fire [plugin hooks](./hooks.md#plugin-hooks): `kanban_task_claimed`, `kanban_task_completed`, and `kanban_task_blocked`, each carrying `task_id` and `profile_name`. Hooks fire **after** the board DB change commits, so callbacks always see durable state. Note the process split: `kanban_task_claimed` fires in the **dispatcher** process, while `kanban_task_completed`/`kanban_task_blocked` fire in the **worker** process — register the hook in the dispatcher profile to observe every transition centrally.
 
 ```python
 def register(ctx):
@@ -1270,7 +1270,7 @@ A "wake" forges a synthetic inbound message to the destination gateway agent so
 
 In a one-gateway-per-profile deployment (one dispatcher, separate gateway
 processes for `writer`, `admin`, etc. — see the [multi-gateway
-guide](/user-guide/features/kanban-multi-gateway)),
+guide](./kanban-multi-gateway.md)),
 dispatch and delivery have separate owners:
 
 - **Dispatch stays single-owner.** Exactly one gateway keeps
diff --git a/website/docs/user-guide/features/mcp.md b/website/docs/user-guide/features/mcp.md
index fced6aaf4e..6cdca06b3e 100644
--- a/website/docs/user-guide/features/mcp.md
+++ b/website/docs/user-guide/features/mcp.md
@@ -170,7 +170,7 @@ Cursor-style context variables are also substituted (case-sensitive):
 `${userHome}` (home directory), `${workspaceFolder}` (session workspace
 root), `${workspaceFolderBasename}`, and `${pathSeparator}` / `${/}`
 (the OS path separator). See the
-[MCP config reference](/docs/reference/mcp-config-reference) for details.
+[MCP config reference](../../reference/mcp-config-reference.md) for details.
 
 Note this is distinct from `${INSTALL_DIR}` in catalog manifests, which is
 substituted at install-time with the path the catalog cloned the entry's
@@ -1003,7 +1003,7 @@ The gateway does NOT need to be running for read operations (listing conversatio
 
 ## Related docs
 
-- [Use MCP with Hermes](/guides/use-mcp-with-hermes)
-- [CLI Commands](/reference/cli-commands)
-- [Slash Commands](/reference/slash-commands)
-- [FAQ](/reference/faq)
+- [Use MCP with Hermes](../../guides/use-mcp-with-hermes.md)
+- [CLI Commands](../../reference/cli-commands.md)
+- [Slash Commands](../../reference/slash-commands.md)
+- [FAQ](../../reference/faq.md)
diff --git a/website/docs/user-guide/features/memory-providers.md b/website/docs/user-guide/features/memory-providers.md
index 4bfba6587f..6dfda6dcc1 100644
--- a/website/docs/user-guide/features/memory-providers.md
+++ b/website/docs/user-guide/features/memory-providers.md
@@ -687,7 +687,7 @@ hermes memory setup
 
 ## Profile Isolation
 
-Each provider's data is isolated per [profile](/user-guide/profiles):
+Each provider's data is isolated per [profile](../profiles.md):
 
 - **Local storage providers** (Holographic, ByteRover) use `$HERMES_HOME/` paths which differ per profile
 - **Config file providers** (Honcho, Mem0, Hindsight, Supermemory) store config in `$HERMES_HOME/` so each profile has its own credentials
@@ -697,7 +697,7 @@ Each provider's data is isolated per [profile](/user-guide/profiles):
 ## Providers Moving to the Plugin Catalog
 
 Memory providers are moving out of the Hermes tree into their maintainers' own repositories,
-published through the [plugin catalog](/user-guide/plugins). Nothing changes for you: the
+published through the [plugin catalog](./plugins.md). Nothing changes for you: the
 provider name, your `memory.<name>` settings, its data directory and its tools stay the same.
 When a provider you have configured stops shipping with Hermes, `hermes update` installs its
 catalog plugin for every profile that names it; if you update through the Desktop app, the
@@ -706,4 +706,4 @@ agent does the same the first time it starts (unless `security.allow_lazy_instal
 
 ## Building a Memory Provider
 
-See the [Developer Guide: Memory Provider Plugins](/developer-guide/memory-provider-plugin) for how to create your own.
+See the [Developer Guide: Memory Provider Plugins](../../developer-guide/memory-provider-plugin.md) for how to create your own.
diff --git a/website/docs/user-guide/features/memory.md b/website/docs/user-guide/features/memory.md
index 8eff471759..f15f752960 100644
--- a/website/docs/user-guide/features/memory.md
+++ b/website/docs/user-guide/features/memory.md
@@ -20,7 +20,7 @@ Two files make up the agent's memory:
 Both are stored in `~/.hermes/memories/` and are injected into the system prompt as a frozen snapshot at session start. The agent manages its own memory via the `memory` tool — it can add, replace, or remove entries.
 
 :::caution One agent per Hermes home
-Don't point two agent processes at the same Hermes home directory. Memory writes are automatic and load back into the system prompt at session start, so two writers sharing one home will compound each other's entries into state neither of them (nor you) authored. Memory is scoped per [profile](/user-guide/profiles) by design — give a second agent its own profile, and if they need shared memory, use an [external memory provider](/user-guide/features/memory-providers) instead.
+Don't point two agent processes at the same Hermes home directory. Memory writes are automatic and load back into the system prompt at session start, so two writers sharing one home will compound each other's entries into state neither of them (nor you) authored. Memory is scoped per [profile](../profiles.md) by design — give a second agent its own profile, and if they need shared memory, use an [external memory provider](./memory-providers.md) instead.
 :::
 
 :::info
@@ -60,7 +60,7 @@ The format includes:
 
 The whole memory system is built around the moment a session **ends**: `MEMORY.md` and `USER.md` carry the essentials into the next session, and `session_search` fills the gaps once the old context is gone. Inside a single session none of that machinery has a reason to run — everything important is still in the live context, so the agent rarely consults `session_search` and mostly compacts memory entries instead of curating them.
 
-This matters on messaging platforms (Telegram, Discord, etc.), where a chat is deliberately [one continuous session](/user-guide/sessions#session-continuity) that survives restarts, gateway crashes, and machine reboots. Shutting the machine down overnight does **not** end the session — the next message picks it up exactly where it left off. If you never reset, a chat can run for weeks as a single session: convenient, but it grows expensive (compaction runs repeatedly over an ever-longer history) and the learning loop of *forget → recall from memory → search past sessions* almost never gets to fire. Fresh memory entries also stay invisible to the running session because of the frozen snapshot above.
+This matters on messaging platforms (Telegram, Discord, etc.), where a chat is deliberately [one continuous session](../sessions.md#session-continuity) that survives restarts, gateway crashes, and machine reboots. Shutting the machine down overnight does **not** end the session — the next message picks it up exactly where it left off. If you never reset, a chat can run for weeks as a single session: convenient, but it grows expensive (compaction runs repeatedly over an ever-longer history) and the learning loop of *forget → recall from memory → search past sessions* almost never gets to fire. Fresh memory entries also stay invisible to the running session because of the frozen snapshot above.
 
 **Practice:** run `/new` at natural boundaries — a finished task, a change of topic, the start of a day. Each boundary is when memory pays off: the agent re-reads the updated `MEMORY.md`/`USER.md` snapshot, starts from a cheap short context, and reaches for `session_search` when it actually needs history. On the CLI this mostly takes care of itself (every invocation is a new session); on gateways the boundary is yours to create.
 
@@ -203,7 +203,7 @@ Beyond MEMORY.md and USER.md, the agent can search its past conversations using
 hermes sessions list    # Browse past sessions
 ```
 
-See [Session Search Tool](/user-guide/sessions#session-search-tool) for the three calling shapes (discovery / scroll / browse) and the response format.
+See [Session Search Tool](../sessions.md#session-search-tool) for the three calling shapes (discovery / scroll / browse) and the response format.
 
 ### session_search vs memory
 
@@ -449,7 +449,7 @@ inline, but the full diff stays out-of-band:
 On a messaging platform, approve a skill from its gist + metadata, or open
 `/skills diff` on the CLI / dashboard / the staged file under
 `~/.hermes/pending/skills/<id>.json` when you want to read the whole change.
-Full details in [Gating agent skill writes](/user-guide/features/skills#gating-agent-skill-writes-skillswrite_approval).
+Full details in [Gating agent skill writes](./skills.md#gating-agent-skill-writes-skillswrite_approval).
 
 
 ## External Memory Providers
diff --git a/website/docs/user-guide/features/overview.md b/website/docs/user-guide/features/overview.md
index 094b296226..c701d8ae6b 100644
--- a/website/docs/user-guide/features/overview.md
+++ b/website/docs/user-guide/features/overview.md
@@ -9,7 +9,7 @@ sidebar_position: 1
 Hermes Agent includes a rich set of capabilities that extend far beyond basic chat. From persistent memory and file-aware context to browser automation and voice conversations, these features work together to make Hermes a powerful autonomous assistant.
 
 :::tip Don't know where to start?
-`hermes setup --portal` covers a model provider plus all four Tool Gateway tools (web search, image generation, TTS, browser) in one command. See [Nous Portal](/integrations/nous-portal).
+`hermes setup --portal` covers a model provider plus all four Tool Gateway tools (web search, image generation, TTS, browser) in one command. See [Nous Portal](../../integrations/nous-portal.md).
 :::
 
 ## Core
diff --git a/website/docs/user-guide/features/personality.md b/website/docs/user-guide/features/personality.md
index e8b2beb01e..7037af11bd 100644
--- a/website/docs/user-guide/features/personality.md
+++ b/website/docs/user-guide/features/personality.md
@@ -274,10 +274,10 @@ At a high level, the prompt stack includes:
 
 ## Related docs
 
-- [Context Files](/user-guide/features/context-files)
-- [Configuration](/user-guide/configuration)
-- [Tips & Best Practices](/guides/tips)
-- [SOUL.md Guide](/guides/use-soul-with-hermes)
+- [Context Files](./context-files.md)
+- [Configuration](../configuration.md)
+- [Tips & Best Practices](../../guides/tips.md)
+- [SOUL.md Guide](../../guides/use-soul-with-hermes.md)
 
 ## CLI appearance vs conversational personality
 
diff --git a/website/docs/user-guide/features/pets.md b/website/docs/user-guide/features/pets.md
index f36f90a471..4bc9908539 100644
--- a/website/docs/user-guide/features/pets.md
+++ b/website/docs/user-guide/features/pets.md
@@ -117,7 +117,7 @@ How generation works (a two-step, cost-bounded flow):
 
 ### Image backend
 
-Generation uses the active [image-generation provider](/user-guide/features/image-generation), but it requires **reference-image grounding** so each animation row stays the same character as the base. Reference-capable backends: **Nous Portal**, **OpenRouter**, **OpenAI** (`gpt-image-2`), and **Krea**. OpenRouter/Nous run a quality-first model chain by default.
+Generation uses the active [image-generation provider](./image-generation.md), but it requires **reference-image grounding** so each animation row stays the same character as the base. Reference-capable backends: **Nous Portal**, **OpenRouter**, **OpenAI** (`gpt-image-2`), and **Krea**. OpenRouter/Nous run a quality-first model chain by default.
 
 - Resolution order prefers Nous Portal → OpenAI → OpenRouter.
 - If no reference-capable backend is configured, generation surfaces an actionable error pointing you to `hermes tools` → Image Generation. (Installing/adopting existing gallery pets needs no image backend.)
diff --git a/website/docs/user-guide/features/plugin-catalog.md b/website/docs/user-guide/features/plugin-catalog.md
index ac306de8ec..07e8d4bf74 100644
--- a/website/docs/user-guide/features/plugin-catalog.md
+++ b/website/docs/user-guide/features/plugin-catalog.md
@@ -223,5 +223,5 @@ checks out exactly the new pin.
 - [Plugins](plugins.md) — the plugin system itself: manifest format, enabling,
   configuration
 - [Built-in Plugins](built-in-plugins.md) — plugins that ship with Hermes
-- [Build a Hermes Plugin](/developer-guide/plugins) — write your own
+- [Build a Hermes Plugin](../../developer-guide/plugins/index.md) — write your own
 - [Plugin Catalog page](/plugins) — the browsable catalog
diff --git a/website/docs/user-guide/features/plugins.md b/website/docs/user-guide/features/plugins.md
index a2410c6977..b1aab7ae3f 100644
--- a/website/docs/user-guide/features/plugins.md
+++ b/website/docs/user-guide/features/plugins.md
@@ -11,10 +11,10 @@ Hermes has a plugin system for adding custom tools, hooks, and integrations with
 
 If you want to create a custom tool for yourself, your team, or one project,
 this is usually the right path. The developer guide's
-[Adding Tools](/developer-guide/adding-tools) page is for built-in Hermes
+[Adding Tools](../../developer-guide/adding-tools.md) page is for built-in Hermes
 core tools that live in `tools/` and `toolsets.py`.
 
-**→ [Build a Hermes Plugin](/developer-guide/plugins)** — step-by-step guide with a complete working example.
+**→ [Build a Hermes Plugin](../../developer-guide/plugins/index.md)** — step-by-step guide with a complete working example.
 
 ## Quick overview
 
@@ -108,26 +108,26 @@ Every `ctx.*` API below is available inside a plugin's `register(ctx)` function.
 | Bundle skills | `ctx.register_skill(name, path)` — namespaced as `plugin:skill`, loaded via `skill_view("plugin:skill")` |
 | Gate on env vars | `requires_env: [API_KEY]` in plugin.yaml — prompted during `hermes plugins install` |
 | Distribute via pip | `[project.entry-points."hermes_agent.plugins"]` |
-| Register a gateway platform (Discord, Telegram, IRC, …) | `ctx.register_platform(name, label, adapter_factory, check_fn, ...)` — see [Adding Platform Adapters](/developer-guide/adding-platform-adapters) |
-| Register an image-generation backend | `ctx.register_image_gen_provider(provider)` — see [Image Generation Provider Plugins](/developer-guide/image-gen-provider-plugin) |
-| Register a video-generation backend | `ctx.register_video_gen_provider(provider)` — see [Video Generation Provider Plugins](/developer-guide/video-gen-provider-plugin) |
-| Register a context-compression engine | `ctx.register_context_engine(engine)` — see [Context Engine Plugins](/developer-guide/context-engine-plugin) |
-| Register a terminal execution backend (cloud sandbox) | `ctx.register_terminal_environment_provider(provider)` — see [Terminal Environment Plugins](/developer-guide/terminal-environment-plugin) |
+| Register a gateway platform (Discord, Telegram, IRC, …) | `ctx.register_platform(name, label, adapter_factory, check_fn, ...)` — see [Adding Platform Adapters](../../developer-guide/adding-platform-adapters.md) |
+| Register an image-generation backend | `ctx.register_image_gen_provider(provider)` — see [Image Generation Provider Plugins](../../developer-guide/image-gen-provider-plugin.md) |
+| Register a video-generation backend | `ctx.register_video_gen_provider(provider)` — see [Video Generation Provider Plugins](../../developer-guide/video-gen-provider-plugin.md) |
+| Register a context-compression engine | `ctx.register_context_engine(engine)` — see [Context Engine Plugins](../../developer-guide/context-engine-plugin.md) |
+| Register a terminal execution backend (cloud sandbox) | `ctx.register_terminal_environment_provider(provider)` — see [Terminal Environment Plugins](../../developer-guide/terminal-environment-plugin.md) |
 | Route human approval prompts | `ctx.register_approval_transport(name, present_fn)` — see [Approval transports](#approval-transports) |
-| Register a memory backend | Subclass `MemoryProvider` in `plugins/memory/<name>/__init__.py` — see [Memory Provider Plugins](/developer-guide/memory-provider-plugin) (uses a separate discovery system) |
-| Run a host-owned LLM call | `ctx.llm.complete(...)` / `ctx.llm.complete_structured(...)` — borrow the user's active model + auth for a one-shot completion with optional JSON schema validation. See [Plugin LLM Access](/developer-guide/plugin-llm-access) |
+| Register a memory backend | Subclass `MemoryProvider` in `plugins/memory/<name>/__init__.py` — see [Memory Provider Plugins](../../developer-guide/memory-provider-plugin.md) (uses a separate discovery system) |
+| Run a host-owned LLM call | `ctx.llm.complete(...)` / `ctx.llm.complete_structured(...)` — borrow the user's active model + auth for a one-shot completion with optional JSON schema validation. See [Plugin LLM Access](../../developer-guide/plugin-llm-access.md) |
 | Call an MCP tool (capability-gated) | `ctx.call_mcp(server, tool, arguments, timeout=30)` — see [Calling MCP servers from plugins](#calling-mcp-servers-from-plugins) |
-| Register an inference backend (LLM provider) | `register_provider(ProviderProfile(...))` in `plugins/model-providers/<name>/__init__.py` — see [Model Provider Plugins](/developer-guide/model-provider-plugin) (uses a separate discovery system) |
+| Register an inference backend (LLM provider) | `register_provider(ProviderProfile(...))` in `plugins/model-providers/<name>/__init__.py` — see [Model Provider Plugins](../../developer-guide/model-provider-plugin.md) (uses a separate discovery system) |
 
 ## Plugin discovery
 
 | Source | Path | Use case |
 |--------|------|----------|
-| Bundled | `<repo>/plugins/` | Ships with Hermes — see [Built-in Plugins](/user-guide/features/built-in-plugins) |
+| Bundled | `<repo>/plugins/` | Ships with Hermes — see [Built-in Plugins](./built-in-plugins.md) |
 | User | `~/.hermes/plugins/` | Personal plugins |
 | Project | `.hermes/plugins/` | Project-specific plugins (requires `HERMES_ENABLE_PROJECT_PLUGINS=true`) |
 | pip | `hermes_agent.plugins` entry_points | Distributed packages |
-| Nix | `services.hermes-agent.extraPlugins` / `extraPythonPackages` | NixOS declarative installs — see [Nix Setup](/getting-started/nix-setup#plugins) |
+| Nix | `services.hermes-agent.extraPlugins` / `extraPythonPackages` | NixOS declarative installs — see [Nix Setup](../../getting-started/nix-setup.md#plugins) |
 
 Later sources override earlier ones on name collision, so a user plugin with the same name as a bundled plugin replaces it.
 
@@ -297,7 +297,7 @@ When you upgrade to a version of Hermes that has opt-in plugins (config schema v
 
 ## Available hooks
 
-Plugins can register the 27 lifecycle events currently accepted by `hermes_cli.plugins.VALID_HOOKS`. The **[Event Hooks catalog](/user-guide/features/hooks#shipped-plugin-hook-catalog)** is canonical for exact timing, return handling, payload fields, and privacy notes.
+Plugins can register the 27 lifecycle events currently accepted by `hermes_cli.plugins.VALID_HOOKS`. The **[Event Hooks catalog](./hooks.md#shipped-plugin-hook-catalog)** is canonical for exact timing, return handling, payload fields, and privacy notes.
 
 | Descriptive category | Shipped hooks |
 |---|---|
@@ -325,23 +325,23 @@ The table above shows the four plugin categories, but within "General plugins" t
 
 | Want to add… | How | Authoring guide |
 |---|---|---|
-| A **tool** the LLM can call | Python plugin — `ctx.register_tool()` | [Build a Hermes Plugin](/developer-guide/plugins) · [Adding Tools](/developer-guide/adding-tools) |
-| A **lifecycle hook** (pre/post LLM, session start/end, tool filter) | Python plugin — `ctx.register_hook()` | [Hooks reference](/user-guide/features/hooks) · [Build a Hermes Plugin](/developer-guide/plugins) |
-| A **slash command** for the CLI / gateway | Python plugin — `ctx.register_command()` | [Build a Hermes Plugin](/developer-guide/plugins) · [Extending the CLI](/developer-guide/extending-the-cli) |
-| A **subcommand** for `hermes <thing>` | Python plugin — `ctx.register_cli_command()` | [Extending the CLI](/developer-guide/extending-the-cli) |
-| A bundled **skill** that your plugin ships | Python plugin — `ctx.register_skill()` | [Creating Skills](/developer-guide/creating-skills) |
-| An **inference backend** (LLM provider: OpenAI-compat, Codex, Anthropic-Messages, Bedrock) | Provider plugin — `register_provider(ProviderProfile(...))` in `plugins/model-providers/<name>/` | **[Model Provider Plugins](/developer-guide/model-provider-plugin)** · [Adding Providers](/developer-guide/adding-providers) |
-| A **gateway channel** (Discord / Telegram / IRC / Teams / etc.) | Platform plugin — `ctx.register_platform()` in `plugins/platforms/<name>/` | [Adding Platform Adapters](/developer-guide/adding-platform-adapters) |
-| A **memory backend** (Honcho, Mem0, Supermemory, …) | Memory plugin — subclass `MemoryProvider` in `plugins/memory/<name>/` | [Memory Provider Plugins](/developer-guide/memory-provider-plugin) |
-| A **context-compression strategy** | Context-engine plugin — `ctx.register_context_engine()` | [Context Engine Plugins](/developer-guide/context-engine-plugin) |
-| An **image-generation backend** (DALL·E, SDXL, …) | Backend plugin — `ctx.register_image_gen_provider()` | [Image Generation Provider Plugins](/developer-guide/image-gen-provider-plugin) |
-| A **video-generation backend** (Veo, Kling, Pixverse, Grok-Imagine, Runway, …) | Backend plugin — `ctx.register_video_gen_provider()` | [Video Generation Provider Plugins](/developer-guide/video-gen-provider-plugin) |
-| A **TTS backend** (any CLI — Piper, VoxCPM, Kokoro, xtts, voice-cloning scripts, …) | Config-driven (recommended) — declare under `tts.providers.<name>` with `type: command` in `config.yaml`. OR Python backend plugin — `ctx.register_tts_provider()` for Python-SDK / streaming engines that need more than a shell template. | [TTS Setup](/user-guide/features/tts#custom-command-providers) · [Python plugin guide](/user-guide/features/tts#python-plugin-providers) |
-| An **STT backend** (any CLI — whisper.cpp, custom whisper binary, local ASR CLI) | Config-driven (recommended) — declare under `stt.providers.<name>` with `type: command` in `config.yaml`, or set `HERMES_LOCAL_STT_COMMAND` for the legacy single-command escape hatch. OR Python backend plugin — `ctx.register_transcription_provider()` for Python-SDK engines (OpenRouter, SenseAudio, Gemini-STT, etc.). | [STT Setup](/user-guide/features/tts#stt-custom-command-providers) · [Python plugin guide](/user-guide/features/tts#python-plugin-providers-stt) |
-| **External tools via MCP** (filesystem, GitHub, Linear, Notion, any MCP server) | Config-driven — declare `mcp_servers.<name>` with `command:` / `url:` in `config.yaml`. Hermes auto-discovers the server's tools and registers them alongside built-ins. | [MCP](/user-guide/features/mcp) |
-| **Additional skill sources** (custom GitHub repos, private skill indexes) | CLI — `hermes skills tap add <repo>` | [Skills Hub](/user-guide/features/skills#skills-hub) · [Publishing a custom tap](/user-guide/features/skills#publishing-a-custom-skill-tap) |
-| **Gateway event hooks** (fire on `gateway:startup`, `session:start`, `agent:end`, `command:*`) | Drop `HOOK.yaml` + `handler.py` into `~/.hermes/hooks/<name>/` | [Event Hooks](/user-guide/features/hooks#gateway-event-hooks) |
-| **Shell hooks** (run a shell command on events — notifications, audit logs, desktop alerts) | Config-driven — declare under `hooks:` in `config.yaml` | [Shell Hooks](/user-guide/features/hooks#shell-hooks) |
+| A **tool** the LLM can call | Python plugin — `ctx.register_tool()` | [Build a Hermes Plugin](../../developer-guide/plugins/index.md) · [Adding Tools](../../developer-guide/adding-tools.md) |
+| A **lifecycle hook** (pre/post LLM, session start/end, tool filter) | Python plugin — `ctx.register_hook()` | [Hooks reference](./hooks.md) · [Build a Hermes Plugin](../../developer-guide/plugins/index.md) |
+| A **slash command** for the CLI / gateway | Python plugin — `ctx.register_command()` | [Build a Hermes Plugin](../../developer-guide/plugins/index.md) · [Extending the CLI](../../developer-guide/extending-the-cli.md) |
+| A **subcommand** for `hermes <thing>` | Python plugin — `ctx.register_cli_command()` | [Extending the CLI](../../developer-guide/extending-the-cli.md) |
+| A bundled **skill** that your plugin ships | Python plugin — `ctx.register_skill()` | [Creating Skills](../../developer-guide/creating-skills.md) |
+| An **inference backend** (LLM provider: OpenAI-compat, Codex, Anthropic-Messages, Bedrock) | Provider plugin — `register_provider(ProviderProfile(...))` in `plugins/model-providers/<name>/` | **[Model Provider Plugins](../../developer-guide/model-provider-plugin.md)** · [Adding Providers](../../developer-guide/adding-providers.md) |
+| A **gateway channel** (Discord / Telegram / IRC / Teams / etc.) | Platform plugin — `ctx.register_platform()` in `plugins/platforms/<name>/` | [Adding Platform Adapters](../../developer-guide/adding-platform-adapters.md) |
+| A **memory backend** (Honcho, Mem0, Supermemory, …) | Memory plugin — subclass `MemoryProvider` in `plugins/memory/<name>/` | [Memory Provider Plugins](../../developer-guide/memory-provider-plugin.md) |
+| A **context-compression strategy** | Context-engine plugin — `ctx.register_context_engine()` | [Context Engine Plugins](../../developer-guide/context-engine-plugin.md) |
+| An **image-generation backend** (DALL·E, SDXL, …) | Backend plugin — `ctx.register_image_gen_provider()` | [Image Generation Provider Plugins](../../developer-guide/image-gen-provider-plugin.md) |
+| A **video-generation backend** (Veo, Kling, Pixverse, Grok-Imagine, Runway, …) | Backend plugin — `ctx.register_video_gen_provider()` | [Video Generation Provider Plugins](../../developer-guide/video-gen-provider-plugin.md) |
+| A **TTS backend** (any CLI — Piper, VoxCPM, Kokoro, xtts, voice-cloning scripts, …) | Config-driven (recommended) — declare under `tts.providers.<name>` with `type: command` in `config.yaml`. OR Python backend plugin — `ctx.register_tts_provider()` for Python-SDK / streaming engines that need more than a shell template. | [TTS Setup](./tts.md#custom-command-providers) · [Python plugin guide](./tts.md#python-plugin-providers) |
+| An **STT backend** (any CLI — whisper.cpp, custom whisper binary, local ASR CLI) | Config-driven (recommended) — declare under `stt.providers.<name>` with `type: command` in `config.yaml`, or set `HERMES_LOCAL_STT_COMMAND` for the legacy single-command escape hatch. OR Python backend plugin — `ctx.register_transcription_provider()` for Python-SDK engines (OpenRouter, SenseAudio, Gemini-STT, etc.). | [STT Setup](./tts.md#stt-custom-command-providers) · [Python plugin guide](./tts.md#python-plugin-providers-stt) |
+| **External tools via MCP** (filesystem, GitHub, Linear, Notion, any MCP server) | Config-driven — declare `mcp_servers.<name>` with `command:` / `url:` in `config.yaml`. Hermes auto-discovers the server's tools and registers them alongside built-ins. | [MCP](./mcp.md) |
+| **Additional skill sources** (custom GitHub repos, private skill indexes) | CLI — `hermes skills tap add <repo>` | [Skills Hub](./skills.md#skills-hub) · [Publishing a custom tap](./skills.md#publishing-a-custom-skill-tap) |
+| **Gateway event hooks** (fire on `gateway:startup`, `session:start`, `agent:end`, `command:*`) | Drop `HOOK.yaml` + `handler.py` into `~/.hermes/hooks/<name>/` | [Event Hooks](./hooks.md#gateway-event-hooks) |
+| **Shell hooks** (run a shell command on events — notifications, audit logs, desktop alerts) | Config-driven — declare under `hooks:` in `config.yaml` | [Shell Hooks](./hooks.md#shell-hooks) |
 
 :::note
 Not everything is a Python plugin. Some extension surfaces intentionally use **config-driven shell commands** (TTS, STT, shell hooks) so any CLI you already have becomes a plugin without writing Python. Others are **external servers** (MCP) the agent connects to and auto-registers tools from. And some are **drop-in directories** (gateway hooks) with their own manifest format. Pick the right surface for the integration style that fits your use case; the authoring guides in the table above each cover placeholders, discovery, and examples.
@@ -349,7 +349,7 @@ Not everything is a Python plugin. Some extension surfaces intentionally use **c
 
 ## NixOS declarative plugins
 
-On NixOS, plugins can be installed declaratively via the module options — no `hermes plugins install` needed. See the **[Nix Setup guide](/getting-started/nix-setup#plugins)** for full details.
+On NixOS, plugins can be installed declaratively via the module options — no `hermes plugins install` needed. See the **[Nix Setup guide](../../getting-started/nix-setup.md#plugins)** for full details.
 
 ```nix
 services.hermes-agent = {
@@ -452,7 +452,7 @@ Websites need no SDK — a normal anchor works:
 ```
 
 MCP servers have the equivalent link form — see
-[Add to Hermes link](/reference/mcp-config-reference#add-to-hermes-link).
+[Add to Hermes link](../../reference/mcp-config-reference.md#add-to-hermes-link).
 
 ### Plugin capabilities and consent
 
@@ -633,7 +633,7 @@ entry, the same rule as the plugin catalog. Pack installs ride the exact
 same pinned install path as `hermes plugins install --ref <sha>` and record
 the same provenance in `plugins/.install-metadata.json`, so two installs of
 the same pack resolve identically. Packs build on the
-[manifest v2 fields](/developer-guide/plugins) (`manifest_version`,
+[manifest v2 fields](../../developer-guide/plugins/index.md) (`manifest_version`,
 `api_version`, `requires_plugins`) — each plugin's own manifest still
 validates through the normal install path.
 
@@ -669,7 +669,7 @@ skill-hub ids into pack install is a documented follow-up seam.
 Every `hermes plugins install` and `hermes plugins update` runs a static
 security scan over the plugin tree before it is activated (inspired by
 Claude Cowork's skill & plugin security scanning). The scanner reuses the
-same threat-pattern engine as the [Skills Hub guard](/user-guide/features/skills)
+same threat-pattern engine as the [Skills Hub guard](./skills.md)
 — exfiltration of credential stores, reverse shells, destructive commands,
 persistence mechanisms, obfuscated execution, and prompt injection in
 documentation files — with plugin-aware exemptions: a provider plugin
@@ -853,4 +853,4 @@ plugins:
 Granting `mcp_allowlist` gives the plugin the same access to that MCP server as the model has — including any write-capable tools the server exposes (subject to the server's `trust` tier gates). Grant only servers the plugin genuinely needs.
 :::
 
-See the **[full guide](/developer-guide/plugins)** for handler contracts, schema format, hook behavior, error handling, and common mistakes.
+See the **[full guide](../../developer-guide/plugins/index.md)** for handler contracts, schema format, hook behavior, error handling, and common mistakes.
diff --git a/website/docs/user-guide/features/provider-routing.md b/website/docs/user-guide/features/provider-routing.md
index 3cd2c5c75c..ecd7c3259c 100644
--- a/website/docs/user-guide/features/provider-routing.md
+++ b/website/docs/user-guide/features/provider-routing.md
@@ -12,7 +12,7 @@ When using [OpenRouter](https://openrouter.ai) as your LLM provider, Hermes Agen
 OpenRouter routes requests to many providers (e.g., Anthropic, Google, AWS Bedrock, Together AI). Provider routing lets you optimize for cost, speed, quality, or enforce specific provider requirements.
 
 :::note
-[Nous Portal](/integrations/nous-portal) decides routing centrally per model and does not accept caller-supplied provider preferences; Hermes never sends the `provider` object to Portal, so `provider_routing` is simply ignored there.
+[Nous Portal](../../integrations/nous-portal.md) decides routing centrally per model and does not accept caller-supplied provider preferences; Hermes never sends the `provider` object to Portal, so `provider_routing` is simply ignored there.
 :::
 
 ## Configuration
@@ -225,5 +225,5 @@ provider_routing:
 When no `provider_routing` section is configured (the default), the aggregator uses its own default routing logic, which generally balances cost and availability automatically.
 
 :::tip Provider Routing vs. Fallback Models
-Provider routing controls which **sub-providers behind OpenRouter** handle your requests. For automatic failover to an entirely different provider when your primary model fails, see [Fallback Providers](/user-guide/features/fallback-providers).
+Provider routing controls which **sub-providers behind OpenRouter** handle your requests. For automatic failover to an entirely different provider when your primary model fails, see [Fallback Providers](./fallback-providers.md).
 :::
diff --git a/website/docs/user-guide/features/skills.md b/website/docs/user-guide/features/skills.md
index e6d93f75f8..07522d5e62 100644
--- a/website/docs/user-guide/features/skills.md
+++ b/website/docs/user-guide/features/skills.md
@@ -14,8 +14,8 @@ You can also point Hermes at **external skill directories** — additional folde
 
 See also:
 
-- [Bundled Skills Catalog](/reference/skills-catalog)
-- [Official Optional Skills Catalog](/reference/optional-skills-catalog)
+- [Bundled Skills Catalog](../../reference/skills-catalog.md)
+- [Official Optional Skills Catalog](../../reference/optional-skills-catalog.md)
 
 ## Browse and install in Desktop
 
@@ -328,7 +328,7 @@ required_environment_variables:
 
 When a missing value is encountered, Hermes asks for it securely only when the skill is actually loaded in the local CLI. You can skip setup and keep using the skill. Messaging surfaces never ask for secrets in chat — they tell you to use `hermes setup` or `~/.hermes/.env` locally instead.
 
-Once set, declared env vars are **automatically passed through** to `execute_code` and `terminal` sandboxes — the skill's scripts can use `$TENOR_API_KEY` directly. For non-skill env vars, use the `terminal.env_passthrough` config option. See [Environment Variable Passthrough](/user-guide/security#environment-variable-passthrough) for details.
+Once set, declared env vars are **automatically passed through** to `execute_code` and `terminal` sandboxes — the skill's scripts can use `$TENOR_API_KEY` directly. For non-skill env vars, use the `terminal.env_passthrough` config option. See [Environment Variable Passthrough](../security.md#environment-variable-passthrough) for details.
 
 ### Skill Config Settings
 
@@ -346,7 +346,7 @@ metadata:
 
 Settings are stored under `skills.config` in your config.yaml. `hermes config migrate` prompts for unconfigured settings, and `hermes config show` displays them. When a skill loads, its resolved config values are injected into the context so the agent knows the configured values automatically.
 
-See [Skill Settings](/user-guide/configuration#skill-settings) and [Creating Skills — Config Settings](/developer-guide/creating-skills#config-settings-configyaml) for details.
+See [Skill Settings](../configuration.md#skill-settings) and [Creating Skills — Config Settings](../../developer-guide/creating-skills.md#config-settings-configyaml) for details.
 
 ## Skill Directory Structure
 
@@ -673,7 +673,7 @@ The targeted `patch` is preferred for updates — it's more token-efficient than
 ### Gating agent skill writes (`skills.write_approval`)
 
 By default the agent writes skills freely — including from the [background
-self-improvement review](/user-guide/features/memory#controlling-memory-writes-write_approval)
+self-improvement review](./memory.md#controlling-memory-writes-write_approval)
 that runs after a turn. If you'd rather approve every skill write first
 (small models that misjudge what they learned, secure environments, or just
 wanting eyes on the self-improvement loop), turn on the write-approval gate:
@@ -701,11 +701,11 @@ reviewed with the same familiar approve/deny flow as dangerous commands:
 The review surface works in the interactive CLI and on messaging platforms
 (diff output is truncated for chat bubbles — read the full diff on the CLI or
 in the pending JSON file). Memory writes have the same gate under
-`memory.write_approval` — see [Controlling memory writes](/user-guide/features/memory#controlling-memory-writes-write_approval).
+`memory.write_approval` — see [Controlling memory writes](./memory.md#controlling-memory-writes-write_approval).
 
 > The separate `skills.guard_agent_created` setting is a content scanner
 > (dangerous-pattern heuristics), not an approval gate — the two are
-> independent. See [Guard on agent-created skill writes](/user-guide/configuration#guard-on-agent-created-skill-writes).
+> independent. See [Guard on agent-created skill writes](../configuration.md#guard-on-agent-created-skill-writes).
 
 ## Skills Hub
 
diff --git a/website/docs/user-guide/features/skins.md b/website/docs/user-guide/features/skins.md
index d4841eb699..eb8ecf32e1 100644
--- a/website/docs/user-guide/features/skins.md
+++ b/website/docs/user-guide/features/skins.md
@@ -259,7 +259,7 @@ npm start
 6. Click **Save** to write the skin YAML to `~/.hermes/skins/`.
 7. Click **Activate** to set it as the current skin (updates `display.skin` in `config.yaml`).
 
-Hermes Mod respects the `HERMES_HOME` environment variable, so it works with [profiles](/user-guide/profiles) too.
+Hermes Mod respects the `HERMES_HOME` environment variable, so it works with [profiles](../profiles.md) too.
 
 ## Operational notes
 
diff --git a/website/docs/user-guide/features/tools.md b/website/docs/user-guide/features/tools.md
index 94963855d8..bd3d989b0f 100644
--- a/website/docs/user-guide/features/tools.md
+++ b/website/docs/user-guide/features/tools.md
@@ -30,7 +30,7 @@ High-level categories:
 | **Automation** | `cronjob` | Scheduled tasks with create/list/update/pause/resume/run/remove actions. Outbound delivery is handled by cron's own delivery, the `hermes send` CLI, and the gateway notifier — not by an agent-callable tool. |
 | **Integrations** | `ha_*`, MCP server tools | Home Assistant, MCP, and other integrations. |
 
-For the authoritative code-derived registry, see [Built-in Tools Reference](/reference/tools-reference) and [Toolsets Reference](/reference/toolsets-reference).
+For the authoritative code-derived registry, see [Built-in Tools Reference](../../reference/tools-reference.md) and [Toolsets Reference](../../reference/toolsets-reference.md).
 
 :::tip Nous Tool Gateway
 Paid [Nous Portal](https://portal.nousresearch.com) subscribers can use web search, image generation, TTS, and browser automation through the **[Tool Gateway](tool-gateway.md)** — no separate API keys needed. Run `hermes model` to enable it, or configure individual tools with `hermes tools`.
@@ -51,7 +51,7 @@ hermes tools
 
 Common toolsets include `web`, `search`, `terminal`, `file`, `browser`, `vision`, `image_gen`, `skills`, `tts`, `todo`, `memory`, `session_search`, `cronjob`, `code_execution`, `delegation`, `clarify`, `homeassistant`, `messaging`, `spotify`, `discord`, `discord_admin`, `debugging`, and `safe`.
 
-See [Toolsets Reference](/reference/toolsets-reference) for the full set, including platform presets such as `hermes-cli`, `hermes-telegram`, and dynamic MCP toolsets like `mcp-<server>`.
+See [Toolsets Reference](../../reference/toolsets-reference.md) for the full set, including platform presets such as `hermes-cli`, `hermes-telegram`, and dynamic MCP toolsets like `mcp-<server>`.
 
 ## Tool result annotations
 
diff --git a/website/docs/user-guide/features/vision.md b/website/docs/user-guide/features/vision.md
index f8b4c38d3a..630f9055f3 100644
--- a/website/docs/user-guide/features/vision.md
+++ b/website/docs/user-guide/features/vision.md
@@ -10,7 +10,7 @@ sidebar_position: 7
 Hermes Agent supports **multimodal vision** — you can paste images from your clipboard directly into the CLI and ask the agent to analyze, describe, or work with them. Images are sent to the model as base64-encoded content blocks, so any vision-capable model can process them.
 
 :::tip
-Portal subscribers get vision-capable models (Claude, GPT-5, Gemini) in the same catalog — no extra credentials needed. See [Nous Portal](/integrations/nous-portal).
+Portal subscribers get vision-capable models (Claude, GPT-5, Gemini) in the same catalog — no extra credentials needed. See [Nous Portal](../../integrations/nous-portal.md).
 :::
 
 ## How It Works
@@ -205,7 +205,7 @@ When a user attaches an image — from the CLI clipboard, the gateway (Telegram/
 
 You don't configure this — Hermes looks up your current model's capability in the provider metadata and picks the right path automatically. The practical effect: you can switch between vision and non-vision models mid-session and image handling "just works" without changing your workflow. Text-only models get coherent context about the image rather than a broken multimodal payload they'd have to reject.
 
-Which auxiliary model handles the text-description path is configurable under `auxiliary.vision` — see [Auxiliary Models](/user-guide/configuration#auxiliary-models).
+Which auxiliary model handles the text-description path is configurable under `auxiliary.vision` — see [Auxiliary Models](../configuration.md#auxiliary-models).
 
 ### `vision_analyze` has the same dual behavior
 
diff --git a/website/docs/user-guide/features/voice-mode.md b/website/docs/user-guide/features/voice-mode.md
index 03e7572ea5..4076c1e254 100644
--- a/website/docs/user-guide/features/voice-mode.md
+++ b/website/docs/user-guide/features/voice-mode.md
@@ -10,13 +10,13 @@ Hermes Agent supports full voice interaction across CLI and messaging platforms.
 
 If you want a practical setup walkthrough with recommended configurations and real usage patterns, see [Use Voice Mode with Hermes](../../guides/use-voice-mode-with-hermes.md).
 
-For hands-free session start — saying "hey hermes" (or any phrase) to open a fresh voice session on the CLI, TUI, or desktop app — see [Wake Word](/user-guide/features/wake-word).
+For hands-free session start — saying "hey hermes" (or any phrase) to open a fresh voice session on the CLI, TUI, or desktop app — see [Wake Word](./wake-word.md).
 
 ## Prerequisites
 
 Before using voice features, make sure you have:
 
-1. **Hermes Agent installed** — via the install script (see [Installation](/getting-started/installation))
+1. **Hermes Agent installed** — via the install script (see [Installation](../../getting-started/installation.md))
 2. **An LLM provider configured** — run `hermes model` or set your preferred provider credentials in `~/.hermes/.env`
 3. **A working base setup** — run `hermes` to verify the agent responds to text before enabling voice
 
@@ -25,7 +25,7 @@ The `~/.hermes/` directory and default `config.yaml` are created automatically t
 :::
 
 :::tip Nous Portal covers both
-A paid [Nous Portal](/user-guide/features/tool-gateway) subscription supplies the LLM (step 2) **and** OpenAI TTS via the Tool Gateway — no separate OpenAI key needed. On a fresh install, `hermes setup --portal` wires both up at once.
+A paid [Nous Portal](./tool-gateway.md) subscription supplies the LLM (step 2) **and** OpenAI TTS via the Tool Gateway — no separate OpenAI key needed. On a fresh install, `hermes setup --portal` wires both up at once.
 :::
 
 ## Overview
@@ -571,7 +571,7 @@ brew install portaudio    # macOS
 sudo apt install portaudio19-dev  # Ubuntu
 ```
 
-If you are running Hermes inside Docker on a Linux desktop, the container also needs access to your host audio socket. See the [Docker audio bridge](/user-guide/docker#optional-linux-desktop-audio-bridge) notes for a PulseAudio/PipeWire-compatible setup.
+If you are running Hermes inside Docker on a Linux desktop, the container also needs access to your host audio socket. See the [Docker audio bridge](../docker.md#optional-linux-desktop-audio-bridge) notes for a PulseAudio/PipeWire-compatible setup.
 
 ### Bot doesn't respond in Discord server channels
 
diff --git a/website/docs/user-guide/features/wake-word.md b/website/docs/user-guide/features/wake-word.md
index ecf7b858b6..91b54cc326 100644
--- a/website/docs/user-guide/features/wake-word.md
+++ b/website/docs/user-guide/features/wake-word.md
@@ -9,7 +9,7 @@ description: "Hands-free 'Hey Hermes' wake word — start a voice session by spe
 The wake word turns Hermes into a hands-free assistant across the CLI, TUI, and
 desktop app: with one setting on, Hermes listens in the background for a spoken
 trigger phrase. Say it, and Hermes starts a fresh session, opens the microphone,
-captures your command via the normal [voice pipeline](/user-guide/features/voice-mode),
+captures your command via the normal [voice pipeline](./voice-mode.md),
 and answers — exactly like "Hey Siri" or "Alexa". Use `surface` to pick which
 one listens.
 
@@ -289,7 +289,7 @@ PORCUPINE_ACCESS_KEY=your-key-here
 - A working microphone and the `sounddevice` + `numpy` audio stack (shared with
   voice mode).
 - An STT provider for transcribing the spoken command — local `faster-whisper`
-  works out of the box; see [Voice Mode](/user-guide/features/voice-mode) for the
+  works out of the box; see [Voice Mode](./voice-mode.md) for the
   full provider list.
 - A TTS provider for speaking the reply (the default `edge-tts` works with no
   key). The wake flow is fully hands-free, so the toggle refuses to arm until
diff --git a/website/docs/user-guide/features/web-dashboard.md b/website/docs/user-guide/features/web-dashboard.md
index f31980d51f..ff211885b4 100644
--- a/website/docs/user-guide/features/web-dashboard.md
+++ b/website/docs/user-guide/features/web-dashboard.md
@@ -9,7 +9,7 @@ description: "Browser-based administration panel for managing configuration, API
 The web dashboard is a browser-based UI for managing your Hermes Agent installation. Instead of editing YAML files or running CLI commands, you can configure settings, manage API keys, and monitor sessions from a clean web interface.
 
 :::tip
-Hosted-mode auth uses Nous Portal OAuth; if you also want the dashboard to talk to a real backend, `hermes setup --portal` wires up the model and tool gateway too. See [Nous Portal](/integrations/nous-portal).
+Hosted-mode auth uses Nous Portal OAuth; if you also want the dashboard to talk to a real backend, `hermes setup --portal` wires up the model and tool gateway too. See [Nous Portal](../../integrations/nous-portal.md).
 :::
 
 ## Quick Start
@@ -341,7 +341,7 @@ prompt for them inline; the values go to `.env`. This is the same catalog
 
 ### Webhooks
 
-Manage dynamic [webhook subscriptions](/user-guide/messaging/webhooks). The
+Manage dynamic [webhook subscriptions](../messaging/webhooks.md). The
 webhook platform must be enabled in messaging settings first; the page shows a
 hint when it isn't.
 
@@ -1087,7 +1087,7 @@ The dashboard's React StatusPage shows the same fields under "Web server". A sid
 
 ## Connecting Hermes Desktop to a remote backend
 
-Hermes Desktop can drive a Hermes backend running on another machine (a VPS, a home server, a Mini behind Tailscale). In the app this lives under **Settings → Gateways → Remote gateway**, which asks for a **Remote URL** and a way to **Sign in**. (For the desktop app itself — install, settings, chat — see the [Hermes Desktop](/user-guide/desktop) page.)
+Hermes Desktop can drive a Hermes backend running on another machine (a VPS, a home server, a Mini behind Tailscale). In the app this lives under **Settings → Gateways → Remote gateway**, which asks for a **Remote URL** and a way to **Sign in**. (For the desktop app itself — install, settings, chat — see the [Hermes Desktop](../desktop.md) page.)
 
 You protect the remote dashboard with one of the bundled auth providers, and the desktop app signs in against whichever one the backend advertises. For a backend reachable beyond your own machine — a VPS, a public host, anything internet-facing — the recommended provider is **OAuth (Nous Portal)** (register it with [`hermes dashboard register`](#registering-a-dashboard) and sign in with *Sign in with Nous Research*). The bundled [username/password provider](#usernamepassword-provider-no-oauth-idp) is the quickest option when the backend is on a trusted LAN or reachable only over a VPN, but is **not suitable for direct public-internet exposure**. Binding the dashboard to a non-loopback address engages its auth gate; once signed in, Desktop reuses the session for the chat WebSocket automatically — there is no token to copy or paste.
 
diff --git a/website/docs/user-guide/features/x-search.md b/website/docs/user-guide/features/x-search.md
index ec06adde31..86318db7d2 100644
--- a/website/docs/user-guide/features/x-search.md
+++ b/website/docs/user-guide/features/x-search.md
@@ -23,7 +23,7 @@ Hermes can expose two different X surfaces:
 For mixed workflows, use `x_search` to discover candidate public posts, then switch to `xurl read` or another exact `xurl` command after the target post/user/action is clear. Any state-changing X action must be confirmed by `xurl` output or the X API response; an `x_search` answer is never evidence that a write happened.
 
 :::tip
-If you're paying Portal for an xAI model anyway, Live Search calls bill against the same xAI key configured for chat. See [Nous Portal](/integrations/nous-portal).
+If you're paying Portal for an xAI model anyway, Live Search calls bill against the same xAI key configured for chat. See [Nous Portal](../../integrations/nous-portal.md).
 :::
 
 ## Authentication
diff --git a/website/docs/user-guide/local-models.md b/website/docs/user-guide/local-models.md
index a224b883ff..a2202cd89d 100644
--- a/website/docs/user-guide/local-models.md
+++ b/website/docs/user-guide/local-models.md
@@ -104,8 +104,8 @@ and uses it instead of starting its own. Point a custom endpoint at any
 OpenAI-compatible server for full manual control — the managed runtime is
 a default, not a requirement. For manual setups (Ollama, MLX, custom
 builds, headless CLI machines), see
-[Run Hermes Locally with Ollama](/guides/local-ollama-setup) and
-[Run Local LLMs on Mac](/guides/local-llm-on-mac).
+[Run Hermes Locally with Ollama](../guides/local-ollama-setup.md) and
+[Run Local LLMs on Mac](../guides/local-llm-on-mac.md).
 
 ## Configuration
 
diff --git a/website/docs/user-guide/messaging/discord.md b/website/docs/user-guide/messaging/discord.md
index 1ff0ef4860..03033a526a 100644
--- a/website/docs/user-guide/messaging/discord.md
+++ b/website/docs/user-guide/messaging/discord.md
@@ -780,8 +780,8 @@ Hermes Agent supports Discord voice messages:
 - **Discord voice channels**: Hermes can also join a voice channel, listen to users speaking, and talk back in the channel.
 
 For the full setup and operational guide, see:
-- [Voice Mode](/user-guide/features/voice-mode)
-- [Use Voice Mode with Hermes](/guides/use-voice-mode-with-hermes)
+- [Voice Mode](../features/voice-mode.md)
+- [Use Voice Mode with Hermes](../../guides/use-voice-mode-with-hermes.md)
 
 ### Voice Channel Audio Effects (ambient + verbal acks)
 
diff --git a/website/docs/user-guide/messaging/email.md b/website/docs/user-guide/messaging/email.md
index 71f932d6e9..436d27caec 100644
--- a/website/docs/user-guide/messaging/email.md
+++ b/website/docs/user-guide/messaging/email.md
@@ -12,7 +12,7 @@ Hermes can receive and reply to emails using standard IMAP and SMTP protocols. S
 This page covers the Email gateway adapter, which uses Python's built-in `imaplib`, `smtplib`, and `email` modules. No additional packages or external services are required for this gateway path.
 :::
 
-This is separate from the bundled [Himalaya email skill](/docs/user-guide/skills/bundled/email/email-himalaya), which lets the agent manage email through terminal commands and requires the external `himalaya` CLI plus a Himalaya config file.
+This is separate from the bundled [Himalaya email skill](../skills/bundled/email/email-himalaya.md), which lets the agent manage email through terminal commands and requires the external `himalaya` CLI plus a Himalaya config file.
 
 | Use case | What to configure | External dependency |
 |---|---|---|
diff --git a/website/docs/user-guide/messaging/index.md b/website/docs/user-guide/messaging/index.md
index 7a02abced6..b69cd35b39 100644
--- a/website/docs/user-guide/messaging/index.md
+++ b/website/docs/user-guide/messaging/index.md
@@ -8,10 +8,10 @@ description: "Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal,
 
 Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin, BlueBubbles (iMessage), QQ, Yuanbao, Microsoft Teams, LINE, ntfy, or your browser. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages.
 
-For the full voice feature set — including CLI microphone mode, spoken replies in messaging, and Discord voice-channel conversations — see [Voice Mode](/user-guide/features/voice-mode) and [Use Voice Mode with Hermes](/guides/use-voice-mode-with-hermes).
+For the full voice feature set — including CLI microphone mode, spoken replies in messaging, and Discord voice-channel conversations — see [Voice Mode](../features/voice-mode.md) and [Use Voice Mode with Hermes](../../guides/use-voice-mode-with-hermes.md).
 
 :::tip
-Bots need both a model provider and tool providers (TTS, web). A [Nous Portal](/integrations/nous-portal) subscription bundles all of them.
+Bots need both a model provider and tool providers (TTS, web). A [Nous Portal](../../integrations/nous-portal.md) subscription bundles all of them.
 :::
 
 ## Messaging status in Desktop and the dashboard
@@ -64,7 +64,7 @@ connected. An enabled platform can correctly show **Messaging gateway stopped**.
 **Voice** = TTS audio replies and/or voice message transcription. **Images** = send/receive images. **Files** = send/receive file attachments. **Threads** = threaded conversations. **Reactions** = emoji reactions on messages. **Typing** = typing indicator while processing. **Streaming** = progressive message updates via editing.
 
 :::note Hermes Relay
-[Hermes Relay](/user-guide/messaging/relay) (experimental) is not a chat platform itself — it is a connector system that fronts platforms like Discord, Telegram, Slack, and WhatsApp through an external connector that owns the platform credentials. Capabilities (media, native approval/clarify prompts, reactions, threads, typing, streaming) are negotiated per connector at handshake rather than fixed in the table above.
+[Hermes Relay](./relay.md) (experimental) is not a chat platform itself — it is a connector system that fronts platforms like Discord, Telegram, Slack, and WhatsApp through an external connector that owns the platform credentials. Capabilities (media, native approval/clarify prompts, reactions, threads, typing, streaming) are negotiated per connector at handshake rather than fixed in the table above.
 :::
 
 ## Architecture
@@ -416,7 +416,7 @@ gateway:
 
 #### Inspecting your access
 
-Use `/whoami` from any platform to see the active scope, your tier (admin / user / unrestricted), and which slash commands you can run. See the [Telegram](/user-guide/messaging/telegram#slash-command-access-control) and [Discord](/user-guide/messaging/discord#slash-command-access-control) pages for platform-specific examples.
+Use `/whoami` from any platform to see the active scope, your tier (admin / user / unrestricted), and which slash commands you can run. See the [Telegram](./telegram.md#slash-command-access-control) and [Discord](./discord.md#slash-command-access-control) pages for platform-specific examples.
 
 ## Redirecting the Agent
 
diff --git a/website/docs/user-guide/messaging/msgraph-webhook.md b/website/docs/user-guide/messaging/msgraph-webhook.md
index eb1cb1dec9..25b359690d 100644
--- a/website/docs/user-guide/messaging/msgraph-webhook.md
+++ b/website/docs/user-guide/messaging/msgraph-webhook.md
@@ -12,7 +12,7 @@ Right now the primary consumer is the Teams meeting summary pipeline: Graph noti
 
 ## Prerequisites
 
-- Microsoft Graph application credentials — [Register a Microsoft Graph Application](/guides/microsoft-graph-app-registration)
+- Microsoft Graph application credentials — [Register a Microsoft Graph Application](../../guides/microsoft-graph-app-registration.md)
 - A **public HTTPS URL** that Microsoft Graph can reach (Graph does not call private endpoints). A dev tunnel works for testing; production needs a real domain with a valid certificate.
 - A strong shared secret to use as the `clientState` value. Generate with `openssl rand -hex 32` and put it in `~/.hermes/.env` as `MSGRAPH_WEBHOOK_CLIENT_STATE`.
 
@@ -70,7 +70,7 @@ All settings go under `platforms.msgraph_webhook.extra`:
 | `max_seen_receipts` | `5000` | Dedupe cache size for notification IDs. Oldest entries evicted when the cap is hit. |
 | `allowed_source_cidrs` | `[]` | Required for non-loopback binds. Leave empty only when the listener is bound to loopback and fronted by a local tunnel / reverse proxy. |
 
-Most settings also have an equivalent env var (`MSGRAPH_WEBHOOK_*`) that merges into the config at gateway startup (the exception is `host`, which is config-only — see the note above) — see the [environment variables reference](/reference/environment-variables#microsoft-graph-teams-meetings).
+Most settings also have an equivalent env var (`MSGRAPH_WEBHOOK_*`) that merges into the config at gateway startup (the exception is `host`, which is config-only — see the note above) — see the [environment variables reference](../../reference/environment-variables.md#microsoft-graph-teams-meetings).
 
 ## Security Hardening
 
@@ -137,6 +137,6 @@ Status code table:
 
 ## Related Docs
 
-- [Register a Microsoft Graph Application](/guides/microsoft-graph-app-registration) — Azure app registration prereq
-- [Environment Variables → Microsoft Graph](/reference/environment-variables#microsoft-graph-teams-meetings) — full env var list
-- [Microsoft Teams bot setup](/user-guide/messaging/teams) — the different platform that lets users chat with Hermes in Teams
+- [Register a Microsoft Graph Application](../../guides/microsoft-graph-app-registration.md) — Azure app registration prereq
+- [Environment Variables → Microsoft Graph](../../reference/environment-variables.md#microsoft-graph-teams-meetings) — full env var list
+- [Microsoft Teams bot setup](./teams.md) — the different platform that lets users chat with Hermes in Teams
diff --git a/website/docs/user-guide/messaging/ntfy.md b/website/docs/user-guide/messaging/ntfy.md
index c7895710fb..8dd6320064 100644
--- a/website/docs/user-guide/messaging/ntfy.md
+++ b/website/docs/user-guide/messaging/ntfy.md
@@ -85,7 +85,7 @@ cronjob(
 )
 ```
 
-Or target a specific topic explicitly via the cron job's `deliver:` field, or from a shell script with the [`hermes send` CLI](/guides/pipe-script-output):
+Or target a specific topic explicitly via the cron job's `deliver:` field, or from a shell script with the [`hermes send` CLI](../../guides/pipe-script-output.md):
 
 ```bash
 hermes send ntfy:alerts-channel "Done!"
diff --git a/website/docs/user-guide/messaging/open-webui.md b/website/docs/user-guide/messaging/open-webui.md
index c3e88e8232..d000f936b2 100644
--- a/website/docs/user-guide/messaging/open-webui.md
+++ b/website/docs/user-guide/messaging/open-webui.md
@@ -233,7 +233,7 @@ Open WebUI persists OpenAI-compatible connection settings in its own database af
 
 ## Multi-User Setup with Profiles
 
-To run separate Hermes instances per user — each with their own config, memory, and skills — use [profiles](/user-guide/profiles). Each profile runs its own API server on a different port and automatically advertises the profile name as the model in Open WebUI.
+To run separate Hermes instances per user — each with their own config, memory, and skills — use [profiles](../profiles.md). Each profile runs its own API server on a different port and automatically advertises the profile name as the model in Open WebUI.
 
 ### 1. Create profiles and configure API servers
 
diff --git a/website/docs/user-guide/messaging/relay.md b/website/docs/user-guide/messaging/relay.md
index 4ef23c6f60..2606322917 100644
--- a/website/docs/user-guide/messaging/relay.md
+++ b/website/docs/user-guide/messaging/relay.md
@@ -41,8 +41,8 @@ Relay is for deployments where a hosted or shared connector service manages
 the platform side — for example multi-tenant hosting where one shared bot
 fronts many users' agents, or setups where you don't want bot tokens on the
 gateway machine. If you run your own bots directly, use the native platform
-adapters ([Telegram](/user-guide/messaging/telegram),
-[Discord](/user-guide/messaging/discord), etc.) instead.
+adapters ([Telegram](./telegram.md),
+[Discord](./discord.md), etc.) instead.
 
 ## Enrollment
 
diff --git a/website/docs/user-guide/messaging/simplex.md b/website/docs/user-guide/messaging/simplex.md
index cffff51fe0..dc143eb372 100644
--- a/website/docs/user-guide/messaging/simplex.md
+++ b/website/docs/user-guide/messaging/simplex.md
@@ -130,7 +130,7 @@ cronjob(
 )
 ```
 
-Or target a specific contact via the cron job's `deliver:` field, or from a shell script with the [`hermes send` CLI](/guides/pipe-script-output):
+Or target a specific contact via the cron job's `deliver:` field, or from a shell script with the [`hermes send` CLI](../../guides/pipe-script-output.md):
 
 ```bash
 hermes send simplex:<contact-id> "Done!"
diff --git a/website/docs/user-guide/messaging/sms.md b/website/docs/user-guide/messaging/sms.md
index 8878cc5f0a..914f160226 100644
--- a/website/docs/user-guide/messaging/sms.md
+++ b/website/docs/user-guide/messaging/sms.md
@@ -10,7 +10,7 @@ description: "Set up Hermes Agent as an SMS chatbot via Twilio"
 Hermes connects to SMS through the [Twilio](https://www.twilio.com/) API. People text your Twilio phone number and get AI responses back — same conversational experience as Telegram or Discord, but over standard text messages.
 
 :::info Shared Credentials
-The SMS gateway shares credentials with the optional [telephony skill](/reference/skills-catalog). If you've already set up Twilio for voice calls or one-off SMS, the gateway works with the same `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, and `TWILIO_PHONE_NUMBER`.
+The SMS gateway shares credentials with the optional [telephony skill](../../reference/skills-catalog.md). If you've already set up Twilio for voice calls or one-off SMS, the gateway works with the same `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, and `TWILIO_PHONE_NUMBER`.
 :::
 
 ---
diff --git a/website/docs/user-guide/messaging/teams-meetings.md b/website/docs/user-guide/messaging/teams-meetings.md
index aca258d372..52e0223335 100644
--- a/website/docs/user-guide/messaging/teams-meetings.md
+++ b/website/docs/user-guide/messaging/teams-meetings.md
@@ -18,7 +18,7 @@ This page focuses on setup and enablement:
 - Teams delivery modes
 - pipeline config shape
 
-For day-2 operations, go-live checks, and the operator worksheet, use the dedicated guide: [Operate the Teams Meeting Pipeline](/guides/operate-teams-meeting-pipeline).
+For day-2 operations, go-live checks, and the operator worksheet, use the dedicated guide: [Operate the Teams Meeting Pipeline](../../guides/operate-teams-meeting-pipeline.md).
 
 ## What This Feature Does
 
@@ -42,7 +42,7 @@ hermes teams-pipeline maintain-subscriptions
 Before enabling the meetings pipeline, make sure you have:
 
 - a working Hermes install
-- the existing [Microsoft Teams bot setup](/user-guide/messaging/teams) if you want Teams outbound delivery
+- the existing [Microsoft Teams bot setup](./teams.md) if you want Teams outbound delivery
 - Microsoft Graph application credentials with the permissions required for the meeting resources you plan to subscribe to
 - a public HTTPS URL that Microsoft Graph can call for webhook delivery
 - `ffmpeg` installed if you want recording-plus-STT fallback
@@ -205,11 +205,11 @@ hermes teams-pipeline subscribe \
 
 :::warning Graph subscriptions expire in 72 hours
 
-Microsoft Graph caps webhook subscriptions at 72 hours and will not auto-renew them. You MUST schedule `hermes teams-pipeline maintain-subscriptions` before going live, or notifications will silently stop three days after any manual subscription creation. See [Automating subscription renewal](/guides/operate-teams-meeting-pipeline#automating-subscription-renewal-required-for-production) in the operator runbook — three options (Hermes cron, systemd timer, plain crontab).
+Microsoft Graph caps webhook subscriptions at 72 hours and will not auto-renew them. You MUST schedule `hermes teams-pipeline maintain-subscriptions` before going live, or notifications will silently stop three days after any manual subscription creation. See [Automating subscription renewal](../../guides/operate-teams-meeting-pipeline.md#automating-subscription-renewal-required-for-production) in the operator runbook — three options (Hermes cron, systemd timer, plain crontab).
 
 :::
 
-For subscription maintenance and day-2 operator flows, continue with the guide: [Operate the Teams Meeting Pipeline](/guides/operate-teams-meeting-pipeline).
+For subscription maintenance and day-2 operator flows, continue with the guide: [Operate the Teams Meeting Pipeline](../../guides/operate-teams-meeting-pipeline.md).
 
 ## Validation
 
@@ -238,5 +238,5 @@ hermes teams-pipeline subscriptions
 
 ## Related Docs
 
-- [Microsoft Teams bot setup](/user-guide/messaging/teams)
-- [Operate the Teams Meeting Pipeline](/guides/operate-teams-meeting-pipeline)
+- [Microsoft Teams bot setup](./teams.md)
+- [Operate the Teams Meeting Pipeline](../../guides/operate-teams-meeting-pipeline.md)
diff --git a/website/docs/user-guide/messaging/teams.md b/website/docs/user-guide/messaging/teams.md
index 45af6d85d1..32002637d1 100644
--- a/website/docs/user-guide/messaging/teams.md
+++ b/website/docs/user-guide/messaging/teams.md
@@ -8,7 +8,7 @@ description: "Set up Hermes Agent as a Microsoft Teams bot"
 
 Connect Hermes Agent to Microsoft Teams as a bot. Unlike Slack's Socket Mode, Teams delivers messages by calling a **public HTTPS webhook**, so your instance needs a publicly reachable endpoint — either a dev tunnel (local dev) or a real domain (production).
 
-Need meeting summaries from Microsoft Graph events rather than normal bot conversations? Use the dedicated setup page: [Teams Meetings](/user-guide/messaging/teams-meetings).
+Need meeting summaries from Microsoft Graph events rather than normal bot conversations? Use the dedicated setup page: [Teams Meetings](./teams-meetings.md).
 
 > Run `hermes gateway setup` and pick **Microsoft Teams** for a guided walk-through.
 
@@ -205,7 +205,7 @@ Clicking a button resolves the approval inline and replaces the card with the de
 
 ### Meeting Summary Delivery (Teams Meeting Pipeline)
 
-When the [Teams meeting pipeline plugin](/user-guide/messaging/msgraph-webhook) is enabled, this adapter also handles outbound delivery of meeting summaries — one Teams integration surface, not two. After a meeting's transcript is summarized, the writer posts the summary into your chosen Teams target.
+When the [Teams meeting pipeline plugin](./msgraph-webhook.md) is enabled, this adapter also handles outbound delivery of meeting summaries — one Teams integration surface, not two. After a meeting's transcript is summarized, the writer posts the summary into your chosen Teams target.
 
 Pipeline summary delivery is configured under the `teams` platform entry alongside the bot config:
 
@@ -230,7 +230,7 @@ platforms:
 | Mode | Use when | Trade-off |
 |------|----------|-----------|
 | `incoming_webhook` | Simple "post a summary into this channel" with a static Teams-generated URL. | No reply threading, no reactions, shows as the webhook's configured identity. |
-| `graph` | Threaded channel posts or 1:1/group chat posts under the bot's identity via Microsoft Graph. | Requires the [Graph app registration](/guides/microsoft-graph-app-registration) with `ChannelMessage.Send` (channel) or `Chat.ReadWrite.All` (chat) application permissions. |
+| `graph` | Threaded channel posts or 1:1/group chat posts under the bot's identity via Microsoft Graph. | Requires the [Graph app registration](../../guides/microsoft-graph-app-registration.md) with `ChannelMessage.Send` (channel) or `Chat.ReadWrite.All` (chat) application permissions. |
 
 If the `teams_pipeline` plugin is **not** enabled, these settings are inert — they only wire up when the pipeline runtime binds to the Graph webhook ingress.
 
@@ -288,5 +288,5 @@ Treat `TEAMS_CLIENT_SECRET` like a password — rotate it periodically via the A
 
 ## Related Docs
 
-- [Teams Meetings](/user-guide/messaging/teams-meetings)
-- [Operate the Teams Meeting Pipeline](/guides/operate-teams-meeting-pipeline)
+- [Teams Meetings](./teams-meetings.md)
+- [Operate the Teams Meeting Pipeline](../../guides/operate-teams-meeting-pipeline.md)
diff --git a/website/docs/user-guide/messaging/telegram.md b/website/docs/user-guide/messaging/telegram.md
index 855bd222ca..68a6e35f8c 100644
--- a/website/docs/user-guide/messaging/telegram.md
+++ b/website/docs/user-guide/messaging/telegram.md
@@ -1374,4 +1374,4 @@ Always set `TELEGRAM_ALLOWED_USERS` to restrict who can interact with your bot.
 
 Never share your bot token publicly. If compromised, revoke it immediately via BotFather's `/revoke` command.
 
-For more details, see the [Security documentation](/user-guide/security). You can also use [DM pairing](/user-guide/messaging#dm-pairing-alternative-to-allowlists) for a more dynamic approach to user authorization.
+For more details, see the [Security documentation](../security.md). You can also use [DM pairing](./index.md#dm-pairing-alternative-to-allowlists) for a more dynamic approach to user authorization.
diff --git a/website/docs/user-guide/messaging/whatsapp.md b/website/docs/user-guide/messaging/whatsapp.md
index 7fb088085f..e4d9699bd2 100644
--- a/website/docs/user-guide/messaging/whatsapp.md
+++ b/website/docs/user-guide/messaging/whatsapp.md
@@ -113,9 +113,9 @@ WHATSAPP_ALLOWED_USERS=15551234567         # Comma-separated phone numbers (with
 
 :::tip Allow-all shorthand
 Setting `WHATSAPP_ALLOWED_USERS=*` allows **all** senders (equivalent to `WHATSAPP_ALLOW_ALL_USERS=true`).
-This is consistent with [Signal group allowlists](/reference/environment-variables).
+This is consistent with [Signal group allowlists](../../reference/environment-variables.md).
 To use the pairing flow instead, remove both variables and rely on the
-[DM pairing system](/user-guide/security#dm-pairing-system).
+[DM pairing system](../security.md#dm-pairing-system).
 :::
 
 Optional behavior settings in `~/.hermes/config.yaml`:
diff --git a/website/docs/user-guide/messaging/yuanbao.md b/website/docs/user-guide/messaging/yuanbao.md
index 5ba3b56a70..fe4c666b3a 100644
--- a/website/docs/user-guide/messaging/yuanbao.md
+++ b/website/docs/user-guide/messaging/yuanbao.md
@@ -337,6 +337,6 @@ hermes chat -q "Send 'Hello from CLI' to yuanbao:group:group_code"
 ## Related Documentation
 
 - [Messaging Gateway Overview](./index.md)
-- [Slash Commands Reference](/reference/slash-commands)
-- [Cron Jobs](/user-guide/features/cron)
-- [Background Sessions](/user-guide/cli#background-sessions)
\ No newline at end of file
+- [Slash Commands Reference](../../reference/slash-commands.md)
+- [Cron Jobs](../features/cron.md)
+- [Background Sessions](../cli.md#background-sessions)
\ No newline at end of file
diff --git a/website/docs/user-guide/profiles.md b/website/docs/user-guide/profiles.md
index fb727b906e..3df26e473d 100644
--- a/website/docs/user-guide/profiles.md
+++ b/website/docs/user-guide/profiles.md
@@ -11,7 +11,7 @@ Run multiple independent Hermes agents on the same machine — each with its own
 A profile is a separate Hermes home directory. Each profile gets its own directory containing its own `config.yaml`, `.env`, `SOUL.md`, memories, sessions, skills, cron jobs, and state database. Hermes recognises a directory under `~/.hermes/profiles/` as a profile only when it carries one of those identity files (`config.yaml`, `.env`, `SOUL.md`, `profile.yaml`, `auth.json`, `state.db`); a bare directory left behind by logging or cron is ignored by `profile list`, gateways and `-p`. Profiles let you run separate agents for different purposes — a coding assistant, a personal bot, a research agent — without mixing up Hermes state.
 
 :::caution Give every agent its own profile
-Never point two agent processes at the same profile (the same Hermes home). Both write memory automatically, and each loads the other's writes into its system prompt at session start — so two writers on one home compound each other's state until it stops being anything you configured. Profiles exist exactly to prevent this; agents that need shared memory should use an [external memory provider](/user-guide/features/memory-providers) instead.
+Never point two agent processes at the same profile (the same Hermes home). Both write memory automatically, and each loads the other's writes into its system prompt at session start — so two writers on one home compound each other's state until it stops being anything you configured. Profiles exist exactly to prevent this; agents that need shared memory should use an [external memory provider](./features/memory-providers.md) instead.
 :::
 
 When you create a profile, it automatically becomes its own command. Create a profile called `coder` and you immediately have `coder chat`, `coder setup`, `coder gateway start`, etc.
@@ -55,7 +55,7 @@ That's it. `coder` is now its own Hermes profile with its own config, memory, an
 ## Creating a profile
 
 :::tip
-Quickest setup: run `hermes setup --portal` inside the new profile to wire up models + tools at once. See [Nous Portal](/integrations/nous-portal).
+Quickest setup: run `hermes setup --portal` inside the new profile to wire up models + tools at once. See [Nous Portal](../integrations/nous-portal.md).
 :::
 
 ### Blank profile
@@ -284,7 +284,7 @@ assistant gateway install     # creates hermes-gateway-assistant service
 Each profile gets its own service name. They run independently.
 
 :::note Inside the official Docker image
-Per-profile gateways are supervised by [s6-overlay](https://github.com/just-containers/s6-overlay) (PID 1 in the container), so `hermes profile create <name>` automatically registers an s6 service slot at `/run/service/gateway-<name>/`. `hermes -p <name> gateway start/stop/restart` dispatches to `s6-svc` instead of spawning a bare process — crashes are auto-restarted and `docker restart` preserves the previously-running set of gateways. See [Per-profile gateway supervision](/user-guide/docker#per-profile-gateway-supervision) for details.
+Per-profile gateways are supervised by [s6-overlay](https://github.com/just-containers/s6-overlay) (PID 1 in the container), so `hermes profile create <name>` automatically registers an s6 service slot at `/run/service/gateway-<name>/`. `hermes -p <name> gateway start/stop/restart` dispatches to `s6-svc` instead of spawning a bare process — crashes are auto-restarted and `docker restart` preserves the previously-running set of gateways. See [Per-profile gateway supervision](./docker.md#per-profile-gateway-supervision) for details.
 :::
 
 ## Configuring profiles
diff --git a/website/docs/user-guide/secrets/command.md b/website/docs/user-guide/secrets/command.md
index 04184eb95d..002e95c604 100644
--- a/website/docs/user-guide/secrets/command.md
+++ b/website/docs/user-guide/secrets/command.md
@@ -47,4 +47,4 @@ Startup is never blocked. Errors print one line plus a `→` remediation hint:
 
 ## When to use this vs a plugin
 
-The command source is the escape hatch for vaults without a bundled integration. If you find yourself wrapping a complex CLI dance in a long script, consider a proper [secret-source plugin](/developer-guide/secret-source-plugin) instead — plugins get caching, provenance labels, and typed config.
+The command source is the escape hatch for vaults without a bundled integration. If you find yourself wrapping a complex CLI dance in a long script, consider a proper [secret-source plugin](../../developer-guide/secret-source-plugin.md) instead — plugins get caching, provenance labels, and typed config.
diff --git a/website/docs/user-guide/secrets/index.md b/website/docs/user-guide/secrets/index.md
index 6c40c5fbea..f2fcb474c7 100644
--- a/website/docs/user-guide/secrets/index.md
+++ b/website/docs/user-guide/secrets/index.md
@@ -49,6 +49,6 @@ Terminal commands, `execute_code` sandboxes and [`no_agent` cron scripts](/user-
 
 ## Adding your own backend
 
-Third-party secret managers ship as standalone plugins, not core PRs. A backend subclasses `agent.secret_sources.base.SecretSource` (one required method: `fetch(cfg, home_path) -> FetchResult`) and registers via `ctx.register_secret_source(MySource())` in the plugin's `register(ctx)`. The orchestrator owns precedence, conflict handling, timeouts, and provenance — your source only fetches. Full guide with the contract rules, subprocess-safety helper, and conformance kit: [Building a Secret Source Plugin](/developer-guide/secret-source-plugin).
+Third-party secret managers ship as standalone plugins, not core PRs. A backend subclasses `agent.secret_sources.base.SecretSource` (one required method: `fetch(cfg, home_path) -> FetchResult`) and registers via `ctx.register_secret_source(MySource())` in the plugin's `register(ctx)`. The orchestrator owns precedence, conflict handling, timeouts, and provenance — your source only fetches. Full guide with the contract rules, subprocess-safety helper, and conformance kit: [Building a Secret Source Plugin](../../developer-guide/secret-source-plugin.md).
 
 The bundled set is deliberately closed (same policy as memory providers): Bitwarden and 1Password ship in-tree. Everything else — Infisical, Proton Pass, HashiCorp Vault, AWS Secrets Manager, OS keystores — belongs in plugin repos; share them in the Nous Research Discord (`#plugins-skills-and-skins`).
diff --git a/website/docs/user-guide/security.md b/website/docs/user-guide/security.md
index ba202919b7..d1e8526d53 100644
--- a/website/docs/user-guide/security.md
+++ b/website/docs/user-guide/security.md
@@ -736,7 +736,7 @@ security:
 
 When a blocked URL is requested, the tool returns an error explaining the domain is blocked by policy. The blocklist is enforced across `web_search`, `web_extract`, `browser_navigate`, and all URL-capable tools.
 
-See [Website Blocklist](/user-guide/configuration#website-blocklist) in the configuration guide for full details.
+See [Website Blocklist](./configuration.md#website-blocklist) in the configuration guide for full details.
 
 ### SSRF Protection
 
diff --git a/website/docs/user-guide/sessions.md b/website/docs/user-guide/sessions.md
index 879c1bb87e..d9f89fd0dc 100644
--- a/website/docs/user-guide/sessions.md
+++ b/website/docs/user-guide/sessions.md
@@ -606,7 +606,7 @@ Total messages: 3847
 Database size: 12.4 MB
 ```
 
-For deeper analytics — token usage, cost estimates, tool breakdown, and activity patterns — use [`hermes insights`](/reference/cli-commands#hermes-insights).
+For deeper analytics — token usage, cost estimates, tool breakdown, and activity patterns — use [`hermes insights`](../reference/cli-commands.md#hermes-insights).
 
 ### Repair Stranded Gateway Sessions
 
diff --git a/website/docs/user-guide/skills/bundled/apple/apple-apple-notes.md b/website/docs/user-guide/skills/bundled/apple/apple-apple-notes.md
index 31587b5e9f..ae4505317d 100644
--- a/website/docs/user-guide/skills/bundled/apple/apple-apple-notes.md
+++ b/website/docs/user-guide/skills/bundled/apple/apple-apple-notes.md
@@ -21,7 +21,7 @@ Manage Apple Notes via memo CLI: create, search, edit.
 | License | MIT |
 | Platforms | macos |
 | Tags | `Notes`, `Apple`, `macOS`, `note-taking` |
-| Related skills | [`obsidian`](/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian) |
+| Related skills | [`obsidian`](../note-taking/note-taking-obsidian.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md
index 544a7106d7..8c11926c86 100644
--- a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md
+++ b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md
@@ -21,7 +21,7 @@ Delegate coding to Claude Code CLI (features, PRs).
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Coding-Agent`, `Claude`, `Anthropic`, `Code-Review`, `Refactoring`, `PTY`, `Automation` |
-| Related skills | [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent), [`opencode`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode) |
+| Related skills | [`codex`](./autonomous-ai-agents-codex.md), [`hermes-agent`](./autonomous-ai-agents-hermes-agent.md), [`opencode`](./autonomous-ai-agents-opencode.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md
index 359743a65e..7103460e40 100644
--- a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md
+++ b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md
@@ -21,7 +21,7 @@ Delegate coding to OpenAI Codex CLI (features, PRs).
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Coding-Agent`, `Codex`, `OpenAI`, `Code-Review`, `Refactoring` |
-| Related skills | [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
+| Related skills | [`claude-code`](./autonomous-ai-agents-claude-code.md), [`hermes-agent`](./autonomous-ai-agents-hermes-agent.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md
index 6e31b32dc9..cbf2a01ff4 100644
--- a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md
+++ b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md
@@ -21,7 +21,7 @@ Use, configure, theme, extend, and orchestrate Hermes Agent.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `hermes`, `setup`, `configuration`, `multi-agent`, `spawning`, `cli`, `gateway`, `bots`, `bot-mode`, `features`, `themes`, `skins`, `desktop-plugins`, `tui-widgets`, `petdex`, `development` |
-| Related skills | [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`opencode`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode) |
+| Related skills | [`claude-code`](./autonomous-ai-agents-claude-code.md), [`codex`](./autonomous-ai-agents-codex.md), [`opencode`](./autonomous-ai-agents-opencode.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-merge-reconciler.md b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-merge-reconciler.md
index 4cb8e1fea8..7495e08562 100644
--- a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-merge-reconciler.md
+++ b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-merge-reconciler.md
@@ -21,7 +21,7 @@ Neutral third-party resolution of agent merge conflicts.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Multi-Agent`, `Git`, `Merge-Conflict`, `Kanban`, `Arbitration` |
-| Related skills | [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
+| Related skills | [`hermes-agent`](./autonomous-ai-agents-hermes-agent.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md
index e8a027d382..dc0626684f 100644
--- a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md
+++ b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md
@@ -21,7 +21,7 @@ Delegate coding to OpenCode CLI (features, PR review).
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Coding-Agent`, `OpenCode`, `Autonomous`, `Refactoring`, `Code-Review` |
-| Related skills | [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
+| Related skills | [`claude-code`](./autonomous-ai-agents-claude-code.md), [`codex`](./autonomous-ai-agents-codex.md), [`hermes-agent`](./autonomous-ai-agents-hermes-agent.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/creative/creative-architecture-diagram.md b/website/docs/user-guide/skills/bundled/creative/creative-architecture-diagram.md
index a4bf8cfc18..a352349efb 100644
--- a/website/docs/user-guide/skills/bundled/creative/creative-architecture-diagram.md
+++ b/website/docs/user-guide/skills/bundled/creative/creative-architecture-diagram.md
@@ -21,7 +21,7 @@ Dark-themed SVG architecture/cloud/infra diagrams as HTML.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `architecture`, `diagrams`, `SVG`, `HTML`, `visualization`, `infrastructure`, `cloud` |
-| Related skills | [`concept-diagrams`](/docs/user-guide/skills/optional/creative/creative-concept-diagrams), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw) |
+| Related skills | [`concept-diagrams`](../../optional/creative/creative-concept-diagrams.md), [`excalidraw`](../../optional/creative/creative-excalidraw.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/creative/creative-ascii-art.md b/website/docs/user-guide/skills/bundled/creative/creative-ascii-art.md
index ba08d77c05..21cdb1ff57 100644
--- a/website/docs/user-guide/skills/bundled/creative/creative-ascii-art.md
+++ b/website/docs/user-guide/skills/bundled/creative/creative-ascii-art.md
@@ -21,7 +21,7 @@ ASCII art: pyfiglet, cowsay, boxes, image-to-ascii.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `ASCII`, `Art`, `Banners`, `Creative`, `Unicode`, `Text-Art`, `pyfiglet`, `figlet`, `cowsay`, `boxes` |
-| Related skills | [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw) |
+| Related skills | [`excalidraw`](./creative-excalidraw.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/creative/creative-claude-design.md b/website/docs/user-guide/skills/bundled/creative/creative-claude-design.md
index 95fdaac6e7..29dddff99b 100644
--- a/website/docs/user-guide/skills/bundled/creative/creative-claude-design.md
+++ b/website/docs/user-guide/skills/bundled/creative/creative-claude-design.md
@@ -21,7 +21,7 @@ Design one-off HTML artifacts (landing, deck, prototype).
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `design`, `html`, `prototype`, `ux`, `ui`, `creative`, `artifact`, `deck`, `motion`, `design-system` |
-| Related skills | [`design-md`](/docs/user-guide/skills/bundled/creative/creative-design-md), [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) |
+| Related skills | [`design-md`](./creative-design-md.md), [`popular-web-designs`](./creative-popular-web-designs.md), [`excalidraw`](../../optional/creative/creative-excalidraw.md), [`architecture-diagram`](./creative-architecture-diagram.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/creative/creative-comfyui.md b/website/docs/user-guide/skills/bundled/creative/creative-comfyui.md
index 5276ffaa0d..4c8d4dcc7d 100644
--- a/website/docs/user-guide/skills/bundled/creative/creative-comfyui.md
+++ b/website/docs/user-guide/skills/bundled/creative/creative-comfyui.md
@@ -21,7 +21,7 @@ Generate images, video, and audio via diffusion workflows.
 | License | MIT |
 | Platforms | macos, linux, windows |
 | Tags | `comfyui`, `image-generation`, `stable-diffusion`, `flux`, `sd3`, `wan-video`, `hunyuan-video`, `creative`, `generative-ai`, `video-generation` |
-| Related skills | [`stable-diffusion`](/docs/user-guide/skills/optional/mlops/mlops-stable-diffusion) |
+| Related skills | [`stable-diffusion`](../../optional/mlops/mlops-stable-diffusion.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/creative/creative-design-md.md b/website/docs/user-guide/skills/bundled/creative/creative-design-md.md
index d85492d8fd..0e4453cb12 100644
--- a/website/docs/user-guide/skills/bundled/creative/creative-design-md.md
+++ b/website/docs/user-guide/skills/bundled/creative/creative-design-md.md
@@ -21,7 +21,7 @@ Author/validate/export Google's DESIGN.md token spec files.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `design`, `design-system`, `tokens`, `ui`, `accessibility`, `wcag`, `tailwind`, `dtcg`, `google` |
-| Related skills | [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) |
+| Related skills | [`popular-web-designs`](./creative-popular-web-designs.md), [`claude-design`](./creative-claude-design.md), [`excalidraw`](../../optional/creative/creative-excalidraw.md), [`architecture-diagram`](./creative-architecture-diagram.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/creative/creative-humanizer.md b/website/docs/user-guide/skills/bundled/creative/creative-humanizer.md
index e36d984c0d..63acd62c8a 100644
--- a/website/docs/user-guide/skills/bundled/creative/creative-humanizer.md
+++ b/website/docs/user-guide/skills/bundled/creative/creative-humanizer.md
@@ -21,7 +21,7 @@ Humanize text: strip AI-isms and add real voice.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `writing`, `editing`, `humanize`, `anti-ai-slop`, `voice`, `prose`, `text` |
-| Related skills | [`songwriting-and-ai-music`](/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music) |
+| Related skills | [`songwriting-and-ai-music`](./creative-songwriting-and-ai-music.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/creative/creative-p5js.md b/website/docs/user-guide/skills/bundled/creative/creative-p5js.md
index f819e3c69e..15145dfade 100644
--- a/website/docs/user-guide/skills/bundled/creative/creative-p5js.md
+++ b/website/docs/user-guide/skills/bundled/creative/creative-p5js.md
@@ -21,7 +21,7 @@ p5.js sketches: gen art, shaders, interactive, 3D.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `creative-coding`, `generative-art`, `p5js`, `canvas`, `interactive`, `visualization`, `webgl`, `shaders`, `animation` |
-| Related skills | [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw) |
+| Related skills | [`ascii-video`](./creative-ascii-video.md), [`manim-video`](./creative-manim-video.md), [`excalidraw`](../../optional/creative/creative-excalidraw.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/creative/creative-pretext.md b/website/docs/user-guide/skills/bundled/creative/creative-pretext.md
index 59cdfc8773..b90b114438 100644
--- a/website/docs/user-guide/skills/bundled/creative/creative-pretext.md
+++ b/website/docs/user-guide/skills/bundled/creative/creative-pretext.md
@@ -21,7 +21,7 @@ Build creative browser demos with DOM-free text layout.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `creative-coding`, `typography`, `pretext`, `ascii-art`, `canvas`, `generative`, `text-layout`, `kinetic-typography` |
-| Related skills | [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) |
+| Related skills | [`p5js`](./creative-p5js.md), [`claude-design`](./creative-claude-design.md), [`excalidraw`](./creative-excalidraw.md), [`architecture-diagram`](./creative-architecture-diagram.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/creative/creative-sketch.md b/website/docs/user-guide/skills/bundled/creative/creative-sketch.md
index b4f54f5417..95afee5513 100644
--- a/website/docs/user-guide/skills/bundled/creative/creative-sketch.md
+++ b/website/docs/user-guide/skills/bundled/creative/creative-sketch.md
@@ -21,7 +21,7 @@ Throwaway HTML mockups: 2-3 design variants to compare.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `sketch`, `mockup`, `design`, `ui`, `prototype`, `html`, `variants`, `exploration`, `wireframe`, `comparison` |
-| Related skills | [`spike`](/docs/user-guide/skills/bundled/software-development/software-development-spike), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw) |
+| Related skills | [`spike`](../software-development/software-development-spike.md), [`claude-design`](./creative-claude-design.md), [`popular-web-designs`](./creative-popular-web-designs.md), [`excalidraw`](./creative-excalidraw.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/email/email-email-inbox-triage.md b/website/docs/user-guide/skills/bundled/email/email-email-inbox-triage.md
index 9cfdab881e..d5690a64eb 100644
--- a/website/docs/user-guide/skills/bundled/email/email-email-inbox-triage.md
+++ b/website/docs/user-guide/skills/bundled/email/email-email-inbox-triage.md
@@ -21,7 +21,7 @@ Triage an inbox: prioritize threads, draft replies safely.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Email`, `Inbox`, `Triage`, `Replies`, `Productivity` |
-| Related skills | [`himalaya`](/docs/user-guide/skills/bundled/email/email-himalaya), [`google-workspace`](/docs/user-guide/skills/bundled/productivity/productivity-google-workspace) |
+| Related skills | [`himalaya`](./email-himalaya.md), [`google-workspace`](../productivity/productivity-google-workspace.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/github/github-codebase-inspection.md b/website/docs/user-guide/skills/bundled/github/github-codebase-inspection.md
index f727c1cd31..a9c23ab89b 100644
--- a/website/docs/user-guide/skills/bundled/github/github-codebase-inspection.md
+++ b/website/docs/user-guide/skills/bundled/github/github-codebase-inspection.md
@@ -21,7 +21,7 @@ Inspect codebases w/ pygount: LOC, languages, ratios.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `LOC`, `Code Analysis`, `pygount`, `Codebase`, `Metrics`, `Repository` |
-| Related skills | [`github-repo-management`](/docs/user-guide/skills/bundled/github/github-github-repo-management) |
+| Related skills | [`github-repo-management`](./github-github-repo-management.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/github/github-github-auth.md b/website/docs/user-guide/skills/bundled/github/github-github-auth.md
index ba58277c4e..8b38d02d29 100644
--- a/website/docs/user-guide/skills/bundled/github/github-github-auth.md
+++ b/website/docs/user-guide/skills/bundled/github/github-github-auth.md
@@ -21,7 +21,7 @@ GitHub auth setup: HTTPS tokens, SSH keys, gh CLI login.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `GitHub`, `Authentication`, `Git`, `gh-cli`, `SSH`, `Setup` |
-| Related skills | [`github-pr-workflow`](/docs/user-guide/skills/bundled/github/github-github-pr-workflow), [`github-code-review`](/docs/user-guide/skills/bundled/github/github-github-code-review), [`github-issues`](/docs/user-guide/skills/bundled/github/github-github-issues), [`github-repo-management`](/docs/user-guide/skills/bundled/github/github-github-repo-management) |
+| Related skills | [`github-pr-workflow`](./github-github-pr-workflow.md), [`github-code-review`](./github-github-code-review.md), [`github-issues`](./github-github-issues.md), [`github-repo-management`](./github-github-repo-management.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/github/github-github-code-review.md b/website/docs/user-guide/skills/bundled/github/github-github-code-review.md
index 5041886999..86d33180da 100644
--- a/website/docs/user-guide/skills/bundled/github/github-github-code-review.md
+++ b/website/docs/user-guide/skills/bundled/github/github-github-code-review.md
@@ -21,7 +21,7 @@ Review PRs: diffs, inline comments via gh or REST.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `GitHub`, `Code-Review`, `Pull-Requests`, `Git`, `Quality` |
-| Related skills | [`github-auth`](/docs/user-guide/skills/bundled/github/github-github-auth), [`github-pr-workflow`](/docs/user-guide/skills/bundled/github/github-github-pr-workflow) |
+| Related skills | [`github-auth`](./github-github-auth.md), [`github-pr-workflow`](./github-github-pr-workflow.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/github/github-github-issue-to-pr.md b/website/docs/user-guide/skills/bundled/github/github-github-issue-to-pr.md
index 3d821e45b1..dd60127115 100644
--- a/website/docs/user-guide/skills/bundled/github/github-github-issue-to-pr.md
+++ b/website/docs/user-guide/skills/bundled/github/github-github-issue-to-pr.md
@@ -21,7 +21,7 @@ Carry a GitHub issue to a verified PR with honest CI state.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `GitHub`, `Issues`, `Coding`, `Pull-Requests`, `CI` |
-| Related skills | [`github-issues`](/docs/user-guide/skills/bundled/github/github-github-issues), [`github-pr-workflow`](/docs/user-guide/skills/bundled/github/github-github-pr-workflow), [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development), [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review) |
+| Related skills | [`github-issues`](./github-github-issues.md), [`github-pr-workflow`](./github-github-pr-workflow.md), [`systematic-debugging`](../software-development/software-development-systematic-debugging.md), [`test-driven-development`](../software-development/software-development-test-driven-development.md), [`requesting-code-review`](../software-development/software-development-requesting-code-review.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/github/github-github-issues.md b/website/docs/user-guide/skills/bundled/github/github-github-issues.md
index e25ceb4cb2..917311fb10 100644
--- a/website/docs/user-guide/skills/bundled/github/github-github-issues.md
+++ b/website/docs/user-guide/skills/bundled/github/github-github-issues.md
@@ -21,7 +21,7 @@ Create, triage, label, assign GitHub issues via gh or REST.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `GitHub`, `Issues`, `Project-Management`, `Bug-Tracking`, `Triage` |
-| Related skills | [`github-auth`](/docs/user-guide/skills/bundled/github/github-github-auth), [`github-pr-workflow`](/docs/user-guide/skills/bundled/github/github-github-pr-workflow) |
+| Related skills | [`github-auth`](./github-github-auth.md), [`github-pr-workflow`](./github-github-pr-workflow.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/github/github-github-pr-workflow.md b/website/docs/user-guide/skills/bundled/github/github-github-pr-workflow.md
index 0536a0dd6a..9a7e782e37 100644
--- a/website/docs/user-guide/skills/bundled/github/github-github-pr-workflow.md
+++ b/website/docs/user-guide/skills/bundled/github/github-github-pr-workflow.md
@@ -21,7 +21,7 @@ GitHub PR lifecycle: branch, commit, open, CI, merge.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `GitHub`, `Pull-Requests`, `CI/CD`, `Git`, `Automation`, `Merge` |
-| Related skills | [`github-auth`](/docs/user-guide/skills/bundled/github/github-github-auth), [`github-code-review`](/docs/user-guide/skills/bundled/github/github-github-code-review) |
+| Related skills | [`github-auth`](./github-github-auth.md), [`github-code-review`](./github-github-code-review.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/github/github-github-repo-management.md b/website/docs/user-guide/skills/bundled/github/github-github-repo-management.md
index f540d02eb2..6116ebefb5 100644
--- a/website/docs/user-guide/skills/bundled/github/github-github-repo-management.md
+++ b/website/docs/user-guide/skills/bundled/github/github-github-repo-management.md
@@ -21,7 +21,7 @@ Clone/create/fork repos; manage remotes, releases.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `GitHub`, `Repositories`, `Git`, `Releases`, `Secrets`, `Configuration` |
-| Related skills | [`github-auth`](/docs/user-guide/skills/bundled/github/github-github-auth), [`github-pr-workflow`](/docs/user-guide/skills/bundled/github/github-github-pr-workflow), [`github-issues`](/docs/user-guide/skills/bundled/github/github-github-issues) |
+| Related skills | [`github-auth`](./github-github-auth.md), [`github-pr-workflow`](./github-github-pr-workflow.md), [`github-issues`](./github-github-issues.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-box.md b/website/docs/user-guide/skills/bundled/productivity/productivity-box.md
index 770fdc958f..a0f86516d0 100644
--- a/website/docs/user-guide/skills/bundled/productivity/productivity-box.md
+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-box.md
@@ -21,7 +21,7 @@ Box manages cloud files, sharing, search, and metadata.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Box`, `Productivity`, `Cloud Storage`, `Collaboration`, `Metadata`, `Content Extraction`, `CLI`, `SDK` |
-| Related skills | [`google-workspace`](/docs/user-guide/skills/bundled/productivity/productivity-google-workspace) |
+| Related skills | [`google-workspace`](./productivity-google-workspace.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-document-to-action-items.md b/website/docs/user-guide/skills/bundled/productivity/productivity-document-to-action-items.md
index f0a886f02e..80e0869e10 100644
--- a/website/docs/user-guide/skills/bundled/productivity/productivity-document-to-action-items.md
+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-document-to-action-items.md
@@ -21,7 +21,7 @@ Extract cited obligations, deadlines, tasks from documents.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Documents`, `OCR`, `Action-Items`, `Deadlines`, `Extraction` |
-| Related skills | [`pdf`](/docs/user-guide/skills/bundled/productivity/productivity-pdf), [`pdf`](/docs/user-guide/skills/bundled/productivity/productivity-pdf), [`docx`](/docs/user-guide/skills/bundled/productivity/productivity-docx), [`notion`](/docs/user-guide/skills/bundled/productivity/productivity-notion) |
+| Related skills | [`pdf`](./productivity-pdf.md), [`pdf`](./productivity-pdf.md), [`docx`](./productivity-docx.md), [`notion`](./productivity-notion.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-docx.md b/website/docs/user-guide/skills/bundled/productivity/productivity-docx.md
index 5b27f0f0b4..aa4ce2a6da 100644
--- a/website/docs/user-guide/skills/bundled/productivity/productivity-docx.md
+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-docx.md
@@ -21,7 +21,7 @@ Create, read, edit, template, and review Word .docx files.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `word`, `docx`, `documents`, `office`, `templates`, `revisions`, `comments` |
-| Related skills | [`pdf`](/docs/user-guide/skills/bundled/productivity/productivity-pdf), [`xlsx`](/docs/user-guide/skills/bundled/productivity/productivity-xlsx), [`powerpoint`](/docs/user-guide/skills/bundled/productivity/productivity-powerpoint) |
+| Related skills | [`pdf`](./productivity-pdf.md), [`xlsx`](./productivity-xlsx.md), [`powerpoint`](./productivity-powerpoint.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-google-workspace.md b/website/docs/user-guide/skills/bundled/productivity/productivity-google-workspace.md
index 9e8c327674..2a47729ed9 100644
--- a/website/docs/user-guide/skills/bundled/productivity/productivity-google-workspace.md
+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-google-workspace.md
@@ -21,7 +21,7 @@ Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Google`, `Gmail`, `Calendar`, `Drive`, `Sheets`, `Docs`, `Contacts`, `Email`, `OAuth` |
-| Related skills | [`himalaya`](/docs/user-guide/skills/bundled/email/email-himalaya) |
+| Related skills | [`himalaya`](../email/email-himalaya.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-meeting-action-items.md b/website/docs/user-guide/skills/bundled/productivity/productivity-meeting-action-items.md
index 1a595783f4..68177c5ca6 100644
--- a/website/docs/user-guide/skills/bundled/productivity/productivity-meeting-action-items.md
+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-meeting-action-items.md
@@ -21,7 +21,7 @@ Turn meeting notes into cited decisions, owners, tickets.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Meetings`, `Action-Items`, `Follow-Up`, `Productivity` |
-| Related skills | [`teams-meeting-pipeline`](/docs/user-guide/skills/bundled/productivity/productivity-teams-meeting-pipeline), [`google-workspace`](/docs/user-guide/skills/bundled/productivity/productivity-google-workspace), [`notion`](/docs/user-guide/skills/bundled/productivity/productivity-notion) |
+| Related skills | [`teams-meeting-pipeline`](./productivity-teams-meeting-pipeline.md), [`google-workspace`](./productivity-google-workspace.md), [`notion`](./productivity-notion.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-nano-pdf.md b/website/docs/user-guide/skills/bundled/productivity/productivity-nano-pdf.md
index acd3b12ba9..602100d582 100644
--- a/website/docs/user-guide/skills/bundled/productivity/productivity-nano-pdf.md
+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-nano-pdf.md
@@ -21,7 +21,7 @@ Edit text in existing PDFs via natural-language prompts.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `PDF`, `Documents`, `Editing`, `NLP`, `Productivity` |
-| Related skills | [`pdf`](/docs/user-guide/skills/bundled/productivity/productivity-pdf), [`ocr-and-documents`](/docs/user-guide/skills/bundled/productivity/productivity-ocr-and-documents) |
+| Related skills | [`pdf`](./productivity-pdf.md), [`ocr-and-documents`](./productivity-ocr-and-documents.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-ocr-and-documents.md b/website/docs/user-guide/skills/bundled/productivity/productivity-ocr-and-documents.md
index 9aed152a6f..69c9409821 100644
--- a/website/docs/user-guide/skills/bundled/productivity/productivity-ocr-and-documents.md
+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-ocr-and-documents.md
@@ -21,7 +21,7 @@ Extract text from PDFs/scans (pymupdf, marker-pdf).
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `PDF`, `Documents`, `Research`, `Arxiv`, `Text-Extraction`, `OCR` |
-| Related skills | [`pdf`](/docs/user-guide/skills/bundled/productivity/productivity-pdf), [`docx`](/docs/user-guide/skills/bundled/productivity/productivity-docx), [`powerpoint`](/docs/user-guide/skills/bundled/productivity/productivity-powerpoint) |
+| Related skills | [`pdf`](./productivity-pdf.md), [`docx`](./productivity-docx.md), [`powerpoint`](./productivity-powerpoint.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-pdf.md b/website/docs/user-guide/skills/bundled/productivity/productivity-pdf.md
index a375340613..bb7b601488 100644
--- a/website/docs/user-guide/skills/bundled/productivity/productivity-pdf.md
+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-pdf.md
@@ -21,7 +21,7 @@ PDF files: create, read, merge, fill, OCR, edit text.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `pdf`, `documents`, `forms`, `ocr`, `text-extraction`, `reportlab`, `pypdf`, `pdfplumber`, `pymupdf`, `marker` |
-| Related skills | [`docx`](/docs/user-guide/skills/bundled/productivity/productivity-docx), [`xlsx`](/docs/user-guide/skills/bundled/productivity/productivity-xlsx), [`powerpoint`](/docs/user-guide/skills/bundled/productivity/productivity-powerpoint) |
+| Related skills | [`docx`](./productivity-docx.md), [`xlsx`](./productivity-xlsx.md), [`powerpoint`](./productivity-powerpoint.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-powerpoint.md b/website/docs/user-guide/skills/bundled/productivity/productivity-powerpoint.md
index 72e4dc8e75..cf1a459d98 100644
--- a/website/docs/user-guide/skills/bundled/productivity/productivity-powerpoint.md
+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-powerpoint.md
@@ -21,7 +21,7 @@ Create, read, edit .pptx decks with python-pptx.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `pptx`, `powerpoint`, `presentations`, `slides`, `office`, `python-pptx` |
-| Related skills | [`docx`](/docs/user-guide/skills/bundled/productivity/productivity-docx), [`xlsx`](/docs/user-guide/skills/bundled/productivity/productivity-xlsx), [`pdf`](/docs/user-guide/skills/bundled/productivity/productivity-pdf) |
+| Related skills | [`docx`](./productivity-docx.md), [`xlsx`](./productivity-xlsx.md), [`pdf`](./productivity-pdf.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-product-price-monitor.md b/website/docs/user-guide/skills/bundled/productivity/productivity-product-price-monitor.md
index d757afe4eb..12ae99f188 100644
--- a/website/docs/user-guide/skills/bundled/productivity/productivity-product-price-monitor.md
+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-product-price-monitor.md
@@ -21,7 +21,7 @@ Watch product, flight, or listing prices; alert on target.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Prices`, `Availability`, `Shopping`, `Travel`, `Alerts` |
-| Related skills | [`maps`](/docs/user-guide/skills/bundled/productivity/productivity-maps) |
+| Related skills | [`maps`](./productivity-maps.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-session-librarian.md b/website/docs/user-guide/skills/bundled/productivity/productivity-session-librarian.md
index d1992db21e..4cf4db77f6 100644
--- a/website/docs/user-guide/skills/bundled/productivity/productivity-session-librarian.md
+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-session-librarian.md
@@ -21,7 +21,7 @@ Organize sessions by prompt: find, rename, archive, prune.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Sessions`, `Organization`, `Cleanup`, `Library`, `Productivity` |
-| Related skills | [`weekly-review-planning`](/docs/user-guide/skills/bundled/productivity/productivity-weekly-review-planning) |
+| Related skills | [`weekly-review-planning`](./productivity-weekly-review-planning.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-weekly-review-planning.md b/website/docs/user-guide/skills/bundled/productivity/productivity-weekly-review-planning.md
index 353389b4ae..cb9cfd2b9b 100644
--- a/website/docs/user-guide/skills/bundled/productivity/productivity-weekly-review-planning.md
+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-weekly-review-planning.md
@@ -21,7 +21,7 @@ Weekly reset: commitments, stalled work, next-week plan.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Weekly-Review`, `Planning`, `Tasks`, `Calendar`, `Productivity` |
-| Related skills | [`obsidian`](/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian), [`notion`](/docs/user-guide/skills/bundled/productivity/productivity-notion), [`airtable`](/docs/user-guide/skills/bundled/productivity/productivity-airtable), [`google-workspace`](/docs/user-guide/skills/bundled/productivity/productivity-google-workspace), [`email-inbox-triage`](/docs/user-guide/skills/bundled/email/email-email-inbox-triage) |
+| Related skills | [`obsidian`](../note-taking/note-taking-obsidian.md), [`notion`](./productivity-notion.md), [`airtable`](./productivity-airtable.md), [`google-workspace`](./productivity-google-workspace.md), [`email-inbox-triage`](../email/email-email-inbox-triage.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-xlsx.md b/website/docs/user-guide/skills/bundled/productivity/productivity-xlsx.md
index e0d51ec0b9..cb8f40d87f 100644
--- a/website/docs/user-guide/skills/bundled/productivity/productivity-xlsx.md
+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-xlsx.md
@@ -21,7 +21,7 @@ Create, read, edit Excel .xlsx workbooks and CSVs.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `excel`, `spreadsheet`, `xlsx`, `csv`, `openpyxl`, `productivity` |
-| Related skills | [`docx`](/docs/user-guide/skills/bundled/productivity/productivity-docx), [`pdf`](/docs/user-guide/skills/bundled/productivity/productivity-pdf), [`powerpoint`](/docs/user-guide/skills/bundled/productivity/productivity-powerpoint) |
+| Related skills | [`docx`](./productivity-docx.md), [`pdf`](./productivity-pdf.md), [`powerpoint`](./productivity-powerpoint.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/research/research-blocked-page-recovery.md b/website/docs/user-guide/skills/bundled/research/research-blocked-page-recovery.md
index 60ab28f809..9995987a36 100644
--- a/website/docs/user-guide/skills/bundled/research/research-blocked-page-recovery.md
+++ b/website/docs/user-guide/skills/bundled/research/research-blocked-page-recovery.md
@@ -21,7 +21,7 @@ Recover blocked/paywalled/WAF'd pages via archive snapshots and reader fallbacks
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Research`, `Archives`, `Wayback`, `Paywall`, `WAF`, `Fallback` |
-| Related skills | [`grounded-citations`](/docs/user-guide/skills/bundled/research/research-grounded-citations) |
+| Related skills | [`grounded-citations`](./research-grounded-citations.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/research/research-competitor-news-monitor.md b/website/docs/user-guide/skills/bundled/research/research-competitor-news-monitor.md
index d7f52e44df..d820c13b5a 100644
--- a/website/docs/user-guide/skills/bundled/research/research-competitor-news-monitor.md
+++ b/website/docs/user-guide/skills/bundled/research/research-competitor-news-monitor.md
@@ -21,7 +21,7 @@ Watch named companies for material news; cited digests.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Competitors`, `News`, `Market-Research`, `Monitoring` |
-| Related skills | [`blogwatcher`](/docs/user-guide/skills/optional/research/research-blogwatcher), [`rss-feeds`](/docs/user-guide/skills/optional/research/research-rss-feeds), [`reddit-reading`](/docs/user-guide/skills/optional/social-media/social-media-reddit-reading) |
+| Related skills | [`blogwatcher`](../../optional/research/research-blogwatcher.md), [`rss-feeds`](../../optional/research/research-rss-feeds.md), [`reddit-reading`](../../optional/social-media/social-media-reddit-reading.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/research/research-grounded-citations.md b/website/docs/user-guide/skills/bundled/research/research-grounded-citations.md
index 838d89f3cf..2768a0f365 100644
--- a/website/docs/user-guide/skills/bundled/research/research-grounded-citations.md
+++ b/website/docs/user-guide/skills/bundled/research/research-grounded-citations.md
@@ -21,7 +21,7 @@ Ground answers and documents in cited, verifiable sources.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Research`, `Citations`, `Grounding`, `Sources`, `Web`, `Reports` |
-| Related skills | [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv), [`pdf`](/docs/user-guide/skills/bundled/productivity/productivity-pdf), [`reddit-reading`](/docs/user-guide/skills/optional/social-media/social-media-reddit-reading), [`rss-feeds`](/docs/user-guide/skills/optional/research/research-rss-feeds), [`youtube-content`](/docs/user-guide/skills/bundled/media/media-youtube-content) |
+| Related skills | [`arxiv`](./research-arxiv.md), [`pdf`](../productivity/productivity-pdf.md), [`reddit-reading`](../../optional/social-media/social-media-reddit-reading.md), [`rss-feeds`](../../optional/research/research-rss-feeds.md), [`youtube-content`](../media/media-youtube-content.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/research/research-llm-wiki.md b/website/docs/user-guide/skills/bundled/research/research-llm-wiki.md
index 6d97ac2893..54e93d5045 100644
--- a/website/docs/user-guide/skills/bundled/research/research-llm-wiki.md
+++ b/website/docs/user-guide/skills/bundled/research/research-llm-wiki.md
@@ -21,7 +21,7 @@ Karpathy's LLM Wiki: build/query interlinked markdown KB.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `wiki`, `knowledge-base`, `research`, `notes`, `markdown`, `rag-alternative` |
-| Related skills | [`obsidian`](/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian), [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv) |
+| Related skills | [`obsidian`](../note-taking/note-taking-obsidian.md), [`arxiv`](./research-arxiv.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/research/research-research-paper-writing.md b/website/docs/user-guide/skills/bundled/research/research-research-paper-writing.md
index 3514a6d73f..135406d9c7 100644
--- a/website/docs/user-guide/skills/bundled/research/research-research-paper-writing.md
+++ b/website/docs/user-guide/skills/bundled/research/research-research-paper-writing.md
@@ -22,7 +22,7 @@ Write ML papers for NeurIPS/ICML/ICLR: design→submit.
 | Dependencies | `semanticscholar`, `arxiv`, `habanero`, `requests`, `scipy`, `numpy`, `matplotlib`, `SciencePlots` |
 | Platforms | linux, macos |
 | Tags | `Research`, `Paper Writing`, `Experiments`, `ML`, `AI`, `NeurIPS`, `ICML`, `ICLR`, `ACL`, `AAAI`, `COLM`, `LaTeX`, `Citations`, `Statistical Analysis` |
-| Related skills | [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development), `plan` (now the built-in `/plan` command) |
+| Related skills | [`arxiv`](./research-arxiv.md), [`subagent-driven-development`](../../optional/software-development/software-development-subagent-driven-development.md), `plan` (now the built-in `/plan` command) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-codebase-inspection.md b/website/docs/user-guide/skills/bundled/software-development/software-development-codebase-inspection.md
index e4d49e9d14..0e870c91a3 100644
--- a/website/docs/user-guide/skills/bundled/software-development/software-development-codebase-inspection.md
+++ b/website/docs/user-guide/skills/bundled/software-development/software-development-codebase-inspection.md
@@ -21,7 +21,7 @@ Inspect codebases w/ pygount: LOC, languages, ratios.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `LOC`, `Code Analysis`, `pygount`, `Codebase`, `Metrics`, `Repository` |
-| Related skills | [`github`](/docs/user-guide/skills/bundled/software-development/software-development-github) |
+| Related skills | [`github`](./software-development-github.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-github.md b/website/docs/user-guide/skills/bundled/software-development/software-development-github.md
index 6a70dc807c..7dce2fca48 100644
--- a/website/docs/user-guide/skills/bundled/software-development/software-development-github.md
+++ b/website/docs/user-guide/skills/bundled/software-development/software-development-github.md
@@ -21,7 +21,7 @@ GitHub via gh CLI: PRs, issues, reviews, repos, auth.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `github`, `gh`, `git`, `pull-requests`, `issues`, `code-review`, `repos`, `auth`, `ci` |
-| Related skills | [`codebase-inspection`](/docs/user-guide/skills/bundled/software-development/software-development-codebase-inspection), [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review) |
+| Related skills | [`codebase-inspection`](./software-development-codebase-inspection.md), [`requesting-code-review`](./software-development-requesting-code-review.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md b/website/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md
index c1d6299dfa..7e53288669 100644
--- a/website/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md
+++ b/website/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md
@@ -21,7 +21,7 @@ Author in-repo SKILL.md files: frontmatter and structure.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `skills`, `authoring`, `hermes-agent`, `conventions`, `skill-md` |
-| Related skills | [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review) |
+| Related skills | [`requesting-code-review`](./software-development-requesting-code-review.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-inspecting-hermes-desktop-dom.md b/website/docs/user-guide/skills/bundled/software-development/software-development-inspecting-hermes-desktop-dom.md
index d3f5e423cd..3ad00695e2 100644
--- a/website/docs/user-guide/skills/bundled/software-development/software-development-inspecting-hermes-desktop-dom.md
+++ b/website/docs/user-guide/skills/bundled/software-development/software-development-inspecting-hermes-desktop-dom.md
@@ -21,7 +21,7 @@ Read the live Hermes desktop DOM/CSS over CDP.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `desktop`, `electron`, `cdp`, `dom`, `ui-verification`, `self-inspection` |
-| Related skills | [`node-inspect-debugger`](/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger), [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`dogfood`](/docs/user-guide/skills/bundled/software-development/software-development-dogfood) |
+| Related skills | [`node-inspect-debugger`](./software-development-node-inspect-debugger.md), [`systematic-debugging`](./software-development-systematic-debugging.md), [`dogfood`](./software-development-dogfood.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md b/website/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md
index 18580751bc..24384cbd66 100644
--- a/website/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md
+++ b/website/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md
@@ -21,7 +21,7 @@ Debug Node.js via --inspect + Chrome DevTools Protocol CLI.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `debugging`, `nodejs`, `node-inspect`, `cdp`, `breakpoints`, `ui-tui` |
-| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`python-debugpy`](/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy) |
+| Related skills | [`systematic-debugging`](./software-development-systematic-debugging.md), [`python-debugpy`](./software-development-python-debugpy.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy.md b/website/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy.md
index e6f1120e08..d410baeab9 100644
--- a/website/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy.md
+++ b/website/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy.md
@@ -21,7 +21,7 @@ Debug Python: pdb REPL + debugpy remote (DAP).
 | License | MIT |
 | Platforms | linux, macos |
 | Tags | `debugging`, `python`, `pdb`, `debugpy`, `breakpoints`, `dap`, `post-mortem` |
-| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`node-inspect-debugger`](/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger) |
+| Related skills | [`systematic-debugging`](./software-development-systematic-debugging.md), [`node-inspect-debugger`](./software-development-node-inspect-debugger.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review.md b/website/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review.md
index dfdfb42622..5e804e4e09 100644
--- a/website/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review.md
+++ b/website/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review.md
@@ -21,7 +21,7 @@ Pre-commit review: security scan, quality gates, auto-fix.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `code-review`, `security`, `verification`, `quality`, `pre-commit`, `auto-fix` |
-| Related skills | [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development), [`github`](/docs/user-guide/skills/bundled/software-development/software-development-github) |
+| Related skills | [`subagent-driven-development`](../../optional/software-development/software-development-subagent-driven-development.md), [`test-driven-development`](./software-development-test-driven-development.md), [`github`](./software-development-github.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-simplify-code.md b/website/docs/user-guide/skills/bundled/software-development/software-development-simplify-code.md
index 59e22aa1f6..0465ae3a4a 100644
--- a/website/docs/user-guide/skills/bundled/software-development/software-development-simplify-code.md
+++ b/website/docs/user-guide/skills/bundled/software-development/software-development-simplify-code.md
@@ -21,7 +21,7 @@ Parallel 4-agent cleanup of recent code changes.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `code-review`, `cleanup`, `refactor`, `delegation`, `subagent`, `parallel`, `simplify` |
-| Related skills | [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development) |
+| Related skills | [`requesting-code-review`](./software-development-requesting-code-review.md), [`test-driven-development`](./software-development-test-driven-development.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-spike.md b/website/docs/user-guide/skills/bundled/software-development/software-development-spike.md
index b2d6342723..33f0e7c9a8 100644
--- a/website/docs/user-guide/skills/bundled/software-development/software-development-spike.md
+++ b/website/docs/user-guide/skills/bundled/software-development/software-development-spike.md
@@ -21,7 +21,7 @@ Throwaway experiments to validate an idea before build.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `spike`, `prototype`, `experiment`, `feasibility`, `throwaway`, `exploration`, `research`, `planning`, `mvp`, `proof-of-concept` |
-| Related skills | [`sketch`](/docs/user-guide/skills/optional/creative/creative-sketch), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development) |
+| Related skills | [`sketch`](../../optional/creative/creative-sketch.md), [`subagent-driven-development`](../../optional/software-development/software-development-subagent-driven-development.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging.md b/website/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging.md
index 684cbdb5bf..5417c33038 100644
--- a/website/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging.md
+++ b/website/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging.md
@@ -21,7 +21,7 @@ description: "4-phase root cause debugging: understand bugs before fixing"
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `debugging`, `troubleshooting`, `problem-solving`, `root-cause`, `investigation` |
-| Related skills | [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development) |
+| Related skills | [`test-driven-development`](./software-development-test-driven-development.md), [`subagent-driven-development`](../../optional/software-development/software-development-subagent-driven-development.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development.md b/website/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development.md
index 805782c463..710771afb5 100644
--- a/website/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development.md
+++ b/website/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development.md
@@ -21,7 +21,7 @@ TDD: enforce RED-GREEN-REFACTOR, tests before code.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `testing`, `tdd`, `development`, `quality`, `red-green-refactor` |
-| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development) |
+| Related skills | [`systematic-debugging`](./software-development-systematic-debugging.md), [`subagent-driven-development`](../../optional/software-development/software-development-subagent-driven-development.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/web/web-blocked-page-recovery.md b/website/docs/user-guide/skills/bundled/web/web-blocked-page-recovery.md
index a32d215044..c3d5f9c360 100644
--- a/website/docs/user-guide/skills/bundled/web/web-blocked-page-recovery.md
+++ b/website/docs/user-guide/skills/bundled/web/web-blocked-page-recovery.md
@@ -21,7 +21,7 @@ Use when a fetch fails: 403/429, paywall, WAF, bot wall.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Research`, `Archives`, `Wayback`, `Paywall`, `WAF`, `Fallback` |
-| Related skills | [`grounded-citations`](/docs/user-guide/skills/bundled/research/research-grounded-citations) |
+| Related skills | [`grounded-citations`](../research/research-grounded-citations.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-antigravity-cli.md b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-antigravity-cli.md
index d4e2f48b97..2cf222adea 100644
--- a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-antigravity-cli.md
+++ b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-antigravity-cli.md
@@ -21,7 +21,7 @@ Operate the Antigravity CLI (agy): plugins, auth, sandbox.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Coding-Agent`, `Antigravity`, `CLI`, `Auth`, `Plugins`, `Sandbox` |
-| Related skills | [`grok`](/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-grok), [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
+| Related skills | [`grok`](./autonomous-ai-agents-grok.md), [`codex`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md), [`claude-code`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md), [`hermes-agent`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-blackbox.md b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-blackbox.md
index a56d767bd6..aa65306b9e 100644
--- a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-blackbox.md
+++ b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-blackbox.md
@@ -21,7 +21,7 @@ Delegate coding tasks to the Blackbox AI multi-model CLI.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Coding-Agent`, `Blackbox`, `Multi-Agent`, `Judge`, `Multi-Model` |
-| Related skills | [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
+| Related skills | [`claude-code`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md), [`codex`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md), [`hermes-agent`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-dynamic-workflow.md b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-dynamic-workflow.md
index e3584c3292..6c7073faf8 100644
--- a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-dynamic-workflow.md
+++ b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-dynamic-workflow.md
@@ -21,7 +21,7 @@ Plan-in-code fan-outs, adversarial verification, waves.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `orchestration`, `fan-out`, `subagents`, `delegation`, `verification`, `migration`, `audit`, `research`, `campaign` |
-| Related skills | [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent), [`simplify-code`](/docs/user-guide/skills/bundled/software-development/software-development-simplify-code) |
+| Related skills | [`hermes-agent`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md), [`simplify-code`](../../bundled/software-development/software-development-simplify-code.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-grok.md b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-grok.md
index e57f08318b..6072540efe 100644
--- a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-grok.md
+++ b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-grok.md
@@ -21,7 +21,7 @@ Delegate coding to xAI Grok Build CLI (features, PRs).
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Coding-Agent`, `Grok`, `xAI`, `Code-Review`, `Refactoring`, `Automation` |
-| Related skills | [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
+| Related skills | [`codex`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md), [`claude-code`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md), [`hermes-agent`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho.md b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho.md
index 2bffbcdb4c..c3541f3fcb 100644
--- a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho.md
+++ b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho.md
@@ -21,7 +21,7 @@ Configure and troubleshoot Honcho memory for Hermes.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Honcho`, `Memory`, `Profiles`, `Observation`, `Dialectic`, `User-Modeling`, `Session-Summary` |
-| Related skills | [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
+| Related skills | [`hermes-agent`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands.md b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands.md
index b222bdecf7..faff6bdc3c 100644
--- a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands.md
+++ b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands.md
@@ -21,7 +21,7 @@ Delegate coding to OpenHands CLI (model-agnostic, LiteLLM).
 | License | MIT |
 | Platforms | linux, macos |
 | Tags | `Coding-Agent`, `OpenHands`, `Model-Agnostic`, `LiteLLM` |
-| Related skills | [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`opencode`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode), [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
+| Related skills | [`claude-code`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md), [`codex`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md), [`opencode`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md), [`hermes-agent`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/blockchain/blockchain-evm.md b/website/docs/user-guide/skills/optional/blockchain/blockchain-evm.md
index a065f01a8b..eaa5b860ea 100644
--- a/website/docs/user-guide/skills/optional/blockchain/blockchain-evm.md
+++ b/website/docs/user-guide/skills/optional/blockchain/blockchain-evm.md
@@ -21,7 +21,7 @@ Read-only EVM client: wallets, tokens, gas across 8 chains.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `EVM`, `Ethereum`, `BNB`, `BSC`, `Base`, `Arbitrum`, `Polygon`, `Optimism`, `Avalanche`, `zkSync`, `Blockchain`, `Crypto`, `Web3`, `DeFi`, `NFT`, `ENS`, `Whale`, `Security` |
-| Related skills | [`solana`](/docs/user-guide/skills/optional/blockchain/blockchain-solana) |
+| Related skills | [`solana`](./blockchain-solana.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-ai-presenter-video.md b/website/docs/user-guide/skills/optional/creative/creative-ai-presenter-video.md
index 3bceade1a3..935559cec6 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-ai-presenter-video.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-ai-presenter-video.md
@@ -21,7 +21,7 @@ Make a verified AI presenter video from script + image.
 | License | MIT |
 | Platforms | linux, macos |
 | Tags | `video`, `presenter`, `avatar`, `lipsync`, `tts`, `captions`, `creative` |
-| Related skills | [`hyperframes`](/docs/user-guide/skills/optional/creative/creative-hyperframes), [`kanban-video-orchestrator`](/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator), [`comfyui`](/docs/user-guide/skills/optional/creative/creative-comfyui) |
+| Related skills | [`hyperframes`](./creative-hyperframes.md), [`kanban-video-orchestrator`](./creative-kanban-video-orchestrator.md), [`comfyui`](./creative-comfyui.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-archify.md b/website/docs/user-guide/skills/optional/creative/creative-archify.md
index fca04006e4..0cef5f532d 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-archify.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-archify.md
@@ -21,7 +21,7 @@ Validated interactive HTML diagrams, upstream-maintained.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `diagram`, `architecture`, `workflow`, `sequence`, `dataflow`, `state-machine`, `mermaid`, `html`, `svg` |
-| Related skills | [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw), [`concept-diagrams`](/docs/user-guide/skills/optional/creative/creative-concept-diagrams) |
+| Related skills | [`architecture-diagram`](../../bundled/creative/creative-architecture-diagram.md), [`excalidraw`](./creative-excalidraw.md), [`concept-diagrams`](./creative-concept-diagrams.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-ascii-art.md b/website/docs/user-guide/skills/optional/creative/creative-ascii-art.md
index 7a04bb125d..e4b4d069b6 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-ascii-art.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-ascii-art.md
@@ -21,7 +21,7 @@ ASCII art: pyfiglet, cowsay, boxes, image-to-ascii.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `ASCII`, `Art`, `Banners`, `Creative`, `Unicode`, `Text-Art`, `pyfiglet`, `figlet`, `cowsay`, `boxes` |
-| Related skills | [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw) |
+| Related skills | [`excalidraw`](./creative-excalidraw.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-audiocraft-audio-generation.md b/website/docs/user-guide/skills/optional/creative/creative-audiocraft-audio-generation.md
index 3a8c99319f..643692ba3c 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-audiocraft-audio-generation.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-audiocraft-audio-generation.md
@@ -22,7 +22,7 @@ AudioCraft: MusicGen text-to-music, AudioGen text-to-sound.
 | Dependencies | `audiocraft`, `torch>=2.0.0`, `transformers>=4.30.0` |
 | Platforms | linux, macos |
 | Tags | `Multimodal`, `Audio Generation`, `Text-to-Music`, `Text-to-Audio`, `MusicGen` |
-| Related skills | [`heartmula`](/docs/user-guide/skills/optional/creative/creative-heartmula), [`songwriting-and-ai-music`](/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music) |
+| Related skills | [`heartmula`](./creative-heartmula.md), [`songwriting-and-ai-music`](../../bundled/creative/creative-songwriting-and-ai-music.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-auteur.md b/website/docs/user-guide/skills/optional/creative/creative-auteur.md
index 096e4a062c..9f1a066061 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-auteur.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-auteur.md
@@ -21,7 +21,7 @@ Design and build cinematic, award-level web pages.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `web-design`, `cinematic`, `scroll-animation`, `design-system`, `anti-slop`, `frontend` |
-| Related skills | [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`design-md`](/docs/user-guide/skills/bundled/creative/creative-design-md), [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js) |
+| Related skills | [`popular-web-designs`](../../bundled/creative/creative-popular-web-designs.md), [`design-md`](../../bundled/creative/creative-design-md.md), [`p5js`](../../bundled/creative/creative-p5js.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-comfyui.md b/website/docs/user-guide/skills/optional/creative/creative-comfyui.md
index 418bf365c5..a2bbc49131 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-comfyui.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-comfyui.md
@@ -21,7 +21,7 @@ Generate images, video, and audio via diffusion workflows.
 | License | MIT |
 | Platforms | macos, linux, windows |
 | Tags | `comfyui`, `image-generation`, `stable-diffusion`, `flux`, `sd3`, `wan-video`, `hunyuan-video`, `creative`, `generative-ai`, `video-generation` |
-| Related skills | [`stable-diffusion`](/docs/user-guide/skills/optional/mlops/mlops-stable-diffusion) |
+| Related skills | [`stable-diffusion`](../mlops/mlops-stable-diffusion.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-concept-diagrams.md b/website/docs/user-guide/skills/optional/creative/creative-concept-diagrams.md
index cc0bc64a8b..84a229f7ea 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-concept-diagrams.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-concept-diagrams.md
@@ -21,7 +21,7 @@ Generate flat, minimal educational SVG visuals as HTML.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `diagrams`, `svg`, `visualization`, `education`, `physics`, `chemistry`, `engineering` |
-| Related skills | [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw) |
+| Related skills | [`architecture-diagram`](../../bundled/creative/creative-architecture-diagram.md), [`excalidraw`](./creative-excalidraw.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-draw-your-font.md b/website/docs/user-guide/skills/optional/creative/creative-draw-your-font.md
index e5fcdda279..0ea2f90104 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-draw-your-font.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-draw-your-font.md
@@ -21,7 +21,7 @@ Turn a handwriting photo into an installable TTF font.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `font`, `handwriting`, `typography`, `ttf`, `woff`, `vision`, `creative` |
-| Related skills | [`pixel-art`](/docs/user-guide/skills/optional/creative/creative-pixel-art) |
+| Related skills | [`pixel-art`](./creative-pixel-art.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-dream-loop.md b/website/docs/user-guide/skills/optional/creative/creative-dream-loop.md
index bb93667137..47f9bf160a 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-dream-loop.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-dream-loop.md
@@ -21,7 +21,7 @@ Build stunning 3D scenes via a concept-art fidelity loop.
 | License | MIT |
 | Platforms | linux, macos |
 | Tags | `3d`, `games`, `webgl`, `threejs`, `image-generation`, `visual-fidelity`, `creative` |
-| Related skills | [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video) |
+| Related skills | [`p5js`](../../bundled/creative/creative-p5js.md), [`claude-design`](../../bundled/creative/creative-claude-design.md), [`manim-video`](../../bundled/creative/creative-manim-video.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-heartmula.md b/website/docs/user-guide/skills/optional/creative/creative-heartmula.md
index 53ab90502d..4131e473df 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-heartmula.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-heartmula.md
@@ -21,7 +21,7 @@ HeartMuLa: Suno-like song generation from lyrics + tags.
 | License | MIT |
 | Platforms | linux, macos |
 | Tags | `music`, `audio`, `generation`, `ai`, `heartmula`, `heartcodec`, `lyrics`, `songs` |
-| Related skills | [`audiocraft-audio-generation`](/docs/user-guide/skills/optional/creative/creative-audiocraft-audio-generation), [`songwriting-and-ai-music`](/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music) |
+| Related skills | [`audiocraft-audio-generation`](./creative-audiocraft-audio-generation.md), [`songwriting-and-ai-music`](../../bundled/creative/creative-songwriting-and-ai-music.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-hyperframes.md b/website/docs/user-guide/skills/optional/creative/creative-hyperframes.md
index 1a8afaa9e1..d57b076dca 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-hyperframes.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-hyperframes.md
@@ -21,7 +21,7 @@ Render MP4/WebM videos from HTML compositions.
 | License | Apache-2.0 |
 | Platforms | linux, macos, windows |
 | Tags | `creative`, `video`, `animation`, `html`, `gsap`, `motion-graphics` |
-| Related skills | [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video), [`meme-generation`](/docs/user-guide/skills/optional/creative/creative-meme-generation) |
+| Related skills | [`manim-video`](../../bundled/creative/creative-manim-video.md), [`meme-generation`](./creative-meme-generation.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-impeccable.md b/website/docs/user-guide/skills/optional/creative/creative-impeccable.md
index a94647e8f7..fd6b730fb2 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-impeccable.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-impeccable.md
@@ -21,7 +21,7 @@ Frontend design guidance, upstream-maintained (impeccable).
 | License | Apache-2.0 |
 | Platforms | linux, macos, windows |
 | Tags | `design`, `frontend`, `ui`, `ux`, `web-design`, `anti-slop` |
-| Related skills | [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs) |
+| Related skills | [`claude-design`](../../bundled/creative/creative-claude-design.md), [`popular-web-designs`](../../bundled/creative/creative-popular-web-designs.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-ip-as-logo.md b/website/docs/user-guide/skills/optional/creative/creative-ip-as-logo.md
index 90ed792310..39256d7f01 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-ip-as-logo.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-ip-as-logo.md
@@ -21,7 +21,7 @@ Design minimal cute IP mascot marks readable at 32px.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `logo`, `mascot`, `branding`, `ip-character`, `image-generation`, `creative` |
-| Related skills | [`pixel-art`](/docs/user-guide/skills/optional/creative/creative-pixel-art) |
+| Related skills | [`pixel-art`](./creative-pixel-art.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md b/website/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md
index 32c7341a2d..438d737845 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md
@@ -21,7 +21,7 @@ Plan and run multi-agent video production pipelines.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `video`, `kanban`, `multi-agent`, `orchestration`, `production-pipeline` |
-| Related skills | [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video), [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js), [`comfyui`](/docs/user-guide/skills/optional/creative/creative-comfyui), [`pixel-art`](/docs/user-guide/skills/optional/creative/creative-pixel-art), [`ascii-art`](/docs/user-guide/skills/optional/creative/creative-ascii-art), [`songwriting-and-ai-music`](/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music), [`heartmula`](/docs/user-guide/skills/optional/creative/creative-heartmula), [`songsee`](/docs/user-guide/skills/bundled/media/media-songsee), [`youtube-content`](/docs/user-guide/skills/bundled/media/media-youtube-content), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram), [`concept-diagrams`](/docs/user-guide/skills/optional/creative/creative-concept-diagrams), [`baoyu-comic`](/docs/user-guide/skills/optional/creative/creative-baoyu-comic), [`baoyu-infographic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic), [`humanizer`](/docs/user-guide/skills/bundled/creative/creative-humanizer), [`gif-search`](/docs/user-guide/skills/bundled/media/media-gif-search), [`meme-generation`](/docs/user-guide/skills/optional/creative/creative-meme-generation) |
+| Related skills | [`ascii-video`](../../bundled/creative/creative-ascii-video.md), [`manim-video`](../../bundled/creative/creative-manim-video.md), [`p5js`](../../bundled/creative/creative-p5js.md), [`comfyui`](./creative-comfyui.md), [`pixel-art`](./creative-pixel-art.md), [`ascii-art`](./creative-ascii-art.md), [`songwriting-and-ai-music`](../../bundled/creative/creative-songwriting-and-ai-music.md), [`heartmula`](./creative-heartmula.md), [`songsee`](../../bundled/media/media-songsee.md), [`youtube-content`](../../bundled/media/media-youtube-content.md), [`claude-design`](../../bundled/creative/creative-claude-design.md), [`excalidraw`](./creative-excalidraw.md), [`architecture-diagram`](../../bundled/creative/creative-architecture-diagram.md), [`concept-diagrams`](./creative-concept-diagrams.md), [`baoyu-comic`](./creative-baoyu-comic.md), [`baoyu-infographic`](../../bundled/creative/creative-baoyu-infographic.md), [`humanizer`](../../bundled/creative/creative-humanizer.md), [`gif-search`](../../bundled/media/media-gif-search.md), [`meme-generation`](./creative-meme-generation.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-meme-generation.md b/website/docs/user-guide/skills/optional/creative/creative-meme-generation.md
index f7b61f10f9..2aeb574a71 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-meme-generation.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-meme-generation.md
@@ -21,7 +21,7 @@ Create meme PNGs from templates with Pillow text overlay.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `creative`, `memes`, `humor`, `images` |
-| Related skills | [`ascii-art`](/docs/user-guide/skills/optional/creative/creative-ascii-art) |
+| Related skills | [`ascii-art`](./creative-ascii-art.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-mono-color.md b/website/docs/user-guide/skills/optional/creative/creative-mono-color.md
index 9c7f0c782c..e24f0b6aa4 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-mono-color.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-mono-color.md
@@ -21,7 +21,7 @@ Generate one- or two-ink editorial print poster images.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `design`, `poster`, `print`, `duotone`, `risograph`, `editorial`, `image-generation` |
-| Related skills | [`baoyu-infographic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic), [`meme-generation`](/docs/user-guide/skills/optional/creative/creative-meme-generation), [`pixel-art`](/docs/user-guide/skills/optional/creative/creative-pixel-art) |
+| Related skills | [`baoyu-infographic`](../../bundled/creative/creative-baoyu-infographic.md), [`meme-generation`](./creative-meme-generation.md), [`pixel-art`](./creative-pixel-art.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-pretext.md b/website/docs/user-guide/skills/optional/creative/creative-pretext.md
index 7688aadcbc..55ac2a6e89 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-pretext.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-pretext.md
@@ -21,7 +21,7 @@ Build creative browser demos with DOM-free text layout.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `creative-coding`, `typography`, `pretext`, `ascii-art`, `canvas`, `generative`, `text-layout`, `kinetic-typography` |
-| Related skills | [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) |
+| Related skills | [`p5js`](../../bundled/creative/creative-p5js.md), [`claude-design`](../../bundled/creative/creative-claude-design.md), [`excalidraw`](./creative-excalidraw.md), [`architecture-diagram`](../../bundled/creative/creative-architecture-diagram.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-simple-english.md b/website/docs/user-guide/skills/optional/creative/creative-simple-english.md
index a00e0623c8..0a64375bdf 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-simple-english.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-simple-english.md
@@ -21,7 +21,7 @@ Rewrite text to ASD-STE100 Simplified Technical English.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `writing`, `documentation`, `ste`, `asd-ste100`, `technical-writing`, `editing`, `anti-ai-slop` |
-| Related skills | [`humanizer`](/docs/user-guide/skills/bundled/creative/creative-humanizer) |
+| Related skills | [`humanizer`](../../bundled/creative/creative-humanizer.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-sketch.md b/website/docs/user-guide/skills/optional/creative/creative-sketch.md
index 88f2fcfacd..adeb913330 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-sketch.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-sketch.md
@@ -21,7 +21,7 @@ Throwaway HTML mockups: 2-3 design variants to compare.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `sketch`, `mockup`, `design`, `ui`, `prototype`, `html`, `variants`, `exploration`, `wireframe`, `comparison` |
-| Related skills | [`spike`](/docs/user-guide/skills/bundled/software-development/software-development-spike), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw) |
+| Related skills | [`spike`](../../bundled/software-development/software-development-spike.md), [`claude-design`](../../bundled/creative/creative-claude-design.md), [`popular-web-designs`](../../bundled/creative/creative-popular-web-designs.md), [`excalidraw`](./creative-excalidraw.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-social-media-content-calendar.md b/website/docs/user-guide/skills/optional/creative/creative-social-media-content-calendar.md
index eaf72464eb..0a8fc7d4af 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-social-media-content-calendar.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-social-media-content-calendar.md
@@ -21,7 +21,7 @@ Plan multi-platform social campaigns: briefs to posting.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Social-Media`, `Content-Calendar`, `Campaigns`, `Publishing` |
-| Related skills | [`xurl`](/docs/user-guide/skills/bundled/social-media/social-media-xurl), [`humanizer`](/docs/user-guide/skills/bundled/creative/creative-humanizer) |
+| Related skills | [`xurl`](../../bundled/social-media/social-media-xurl.md), [`humanizer`](../../bundled/creative/creative-humanizer.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-system-atlas.md b/website/docs/user-guide/skills/optional/creative/creative-system-atlas.md
index 27f08b0f2b..a43d82a7c3 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-system-atlas.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-system-atlas.md
@@ -21,7 +21,7 @@ Build explorable isometric architecture atlases as HTML.
 | License | MIT |
 | Platforms | linux, macos |
 | Tags | `architecture`, `diagrams`, `isometric`, `documentation` |
-| Related skills | [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw) |
+| Related skills | [`architecture-diagram`](../../bundled/creative/creative-architecture-diagram.md), [`excalidraw`](./creative-excalidraw.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/devops/devops-hermes-s6-container-supervision.md b/website/docs/user-guide/skills/optional/devops/devops-hermes-s6-container-supervision.md
index 76b34e9c3e..e957e7bdb4 100644
--- a/website/docs/user-guide/skills/optional/devops/devops-hermes-s6-container-supervision.md
+++ b/website/docs/user-guide/skills/optional/devops/devops-hermes-s6-container-supervision.md
@@ -21,7 +21,7 @@ Modify or debug s6 services in the Hermes Docker image.
 | License | MIT |
 | Platforms | linux |
 | Tags | `docker`, `s6`, `supervision`, `gateway`, `profiles` |
-| Related skills | [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
+| Related skills | [`hermes-agent`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/dogfood/dogfood-adversarial-ux-test.md b/website/docs/user-guide/skills/optional/dogfood/dogfood-adversarial-ux-test.md
index 4bef37dab1..69d00e0529 100644
--- a/website/docs/user-guide/skills/optional/dogfood/dogfood-adversarial-ux-test.md
+++ b/website/docs/user-guide/skills/optional/dogfood/dogfood-adversarial-ux-test.md
@@ -21,7 +21,7 @@ Roleplay a hostile user to find and triage UX pain points.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `qa`, `ux`, `testing`, `adversarial`, `dogfood`, `personas`, `user-testing` |
-| Related skills | [`dogfood`](/docs/user-guide/skills/bundled/software-development/software-development-dogfood) |
+| Related skills | [`dogfood`](../../bundled/software-development/software-development-dogfood.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/finance/finance-3-statement-model.md b/website/docs/user-guide/skills/optional/finance/finance-3-statement-model.md
index 250d7fadf4..383055f21e 100644
--- a/website/docs/user-guide/skills/optional/finance/finance-3-statement-model.md
+++ b/website/docs/user-guide/skills/optional/finance/finance-3-statement-model.md
@@ -21,7 +21,7 @@ Build integrated IS/BS/CF financial workbooks in Excel.
 | License | Apache-2.0 |
 | Platforms | linux, macos, windows |
 | Tags | `finance`, `three-statement`, `income-statement`, `balance-sheet`, `cash-flow`, `excel`, `openpyxl`, `modeling` |
-| Related skills | [`excel-author`](/docs/user-guide/skills/optional/finance/finance-excel-author), [`pptx-author`](/docs/user-guide/skills/optional/finance/finance-pptx-author), [`dcf-model`](/docs/user-guide/skills/optional/finance/finance-dcf-model), [`lbo-model`](/docs/user-guide/skills/optional/finance/finance-lbo-model) |
+| Related skills | [`excel-author`](./finance-excel-author.md), [`pptx-author`](./finance-pptx-author.md), [`dcf-model`](./finance-dcf-model.md), [`lbo-model`](./finance-lbo-model.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/finance/finance-comps-analysis.md b/website/docs/user-guide/skills/optional/finance/finance-comps-analysis.md
index de8d1aa2e4..5a17a99c59 100644
--- a/website/docs/user-guide/skills/optional/finance/finance-comps-analysis.md
+++ b/website/docs/user-guide/skills/optional/finance/finance-comps-analysis.md
@@ -21,7 +21,7 @@ Build comparable-company valuation workbooks in Excel.
 | License | Apache-2.0 |
 | Platforms | linux, macos, windows |
 | Tags | `finance`, `valuation`, `comps`, `excel`, `openpyxl`, `modeling`, `investment-banking` |
-| Related skills | [`excel-author`](/docs/user-guide/skills/optional/finance/finance-excel-author), [`pptx-author`](/docs/user-guide/skills/optional/finance/finance-pptx-author), [`dcf-model`](/docs/user-guide/skills/optional/finance/finance-dcf-model), [`lbo-model`](/docs/user-guide/skills/optional/finance/finance-lbo-model) |
+| Related skills | [`excel-author`](./finance-excel-author.md), [`pptx-author`](./finance-pptx-author.md), [`dcf-model`](./finance-dcf-model.md), [`lbo-model`](./finance-lbo-model.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/finance/finance-dcf-model.md b/website/docs/user-guide/skills/optional/finance/finance-dcf-model.md
index 689df50dd3..6ce0f1bb6e 100644
--- a/website/docs/user-guide/skills/optional/finance/finance-dcf-model.md
+++ b/website/docs/user-guide/skills/optional/finance/finance-dcf-model.md
@@ -21,7 +21,7 @@ Build discounted cash flow valuation workbooks in Excel.
 | License | Apache-2.0 |
 | Platforms | linux, macos, windows |
 | Tags | `finance`, `valuation`, `dcf`, `excel`, `openpyxl`, `modeling`, `investment-banking` |
-| Related skills | [`excel-author`](/docs/user-guide/skills/optional/finance/finance-excel-author), [`pptx-author`](/docs/user-guide/skills/optional/finance/finance-pptx-author), [`comps-analysis`](/docs/user-guide/skills/optional/finance/finance-comps-analysis), [`lbo-model`](/docs/user-guide/skills/optional/finance/finance-lbo-model), [`3-statement-model`](/docs/user-guide/skills/optional/finance/finance-3-statement-model) |
+| Related skills | [`excel-author`](./finance-excel-author.md), [`pptx-author`](./finance-pptx-author.md), [`comps-analysis`](./finance-comps-analysis.md), [`lbo-model`](./finance-lbo-model.md), [`3-statement-model`](./finance-3-statement-model.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/finance/finance-excel-author.md b/website/docs/user-guide/skills/optional/finance/finance-excel-author.md
index 50e1e36f80..2a88d22a5c 100644
--- a/website/docs/user-guide/skills/optional/finance/finance-excel-author.md
+++ b/website/docs/user-guide/skills/optional/finance/finance-excel-author.md
@@ -21,7 +21,7 @@ Build auditable financial workbooks headless via openpyxl.
 | License | Apache-2.0 |
 | Platforms | linux, macos, windows |
 | Tags | `excel`, `openpyxl`, `finance`, `spreadsheet`, `modeling` |
-| Related skills | [`xlsx`](/docs/user-guide/skills/bundled/productivity/productivity-xlsx), [`pptx-author`](/docs/user-guide/skills/optional/finance/finance-pptx-author), [`dcf-model`](/docs/user-guide/skills/optional/finance/finance-dcf-model), [`comps-analysis`](/docs/user-guide/skills/optional/finance/finance-comps-analysis), [`lbo-model`](/docs/user-guide/skills/optional/finance/finance-lbo-model), [`3-statement-model`](/docs/user-guide/skills/optional/finance/finance-3-statement-model) |
+| Related skills | [`xlsx`](../../bundled/productivity/productivity-xlsx.md), [`pptx-author`](./finance-pptx-author.md), [`dcf-model`](./finance-dcf-model.md), [`comps-analysis`](./finance-comps-analysis.md), [`lbo-model`](./finance-lbo-model.md), [`3-statement-model`](./finance-3-statement-model.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/finance/finance-lbo-model.md b/website/docs/user-guide/skills/optional/finance/finance-lbo-model.md
index 2746010729..51519cf98d 100644
--- a/website/docs/user-guide/skills/optional/finance/finance-lbo-model.md
+++ b/website/docs/user-guide/skills/optional/finance/finance-lbo-model.md
@@ -21,7 +21,7 @@ Build leveraged buyout workbooks with IRR/MOIC in Excel.
 | License | Apache-2.0 |
 | Platforms | linux, macos, windows |
 | Tags | `finance`, `valuation`, `lbo`, `private-equity`, `excel`, `openpyxl`, `modeling` |
-| Related skills | [`excel-author`](/docs/user-guide/skills/optional/finance/finance-excel-author), [`pptx-author`](/docs/user-guide/skills/optional/finance/finance-pptx-author), [`dcf-model`](/docs/user-guide/skills/optional/finance/finance-dcf-model), [`3-statement-model`](/docs/user-guide/skills/optional/finance/finance-3-statement-model) |
+| Related skills | [`excel-author`](./finance-excel-author.md), [`pptx-author`](./finance-pptx-author.md), [`dcf-model`](./finance-dcf-model.md), [`3-statement-model`](./finance-3-statement-model.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/finance/finance-merger-model.md b/website/docs/user-guide/skills/optional/finance/finance-merger-model.md
index 89c34a2cf1..a37a7400d6 100644
--- a/website/docs/user-guide/skills/optional/finance/finance-merger-model.md
+++ b/website/docs/user-guide/skills/optional/finance/finance-merger-model.md
@@ -21,7 +21,7 @@ Build M&A accretion/dilution workbooks in Excel.
 | License | Apache-2.0 |
 | Platforms | linux, macos, windows |
 | Tags | `finance`, `m-and-a`, `merger`, `accretion-dilution`, `excel`, `openpyxl`, `modeling`, `investment-banking` |
-| Related skills | [`excel-author`](/docs/user-guide/skills/optional/finance/finance-excel-author), [`pptx-author`](/docs/user-guide/skills/optional/finance/finance-pptx-author), [`dcf-model`](/docs/user-guide/skills/optional/finance/finance-dcf-model), [`3-statement-model`](/docs/user-guide/skills/optional/finance/finance-3-statement-model) |
+| Related skills | [`excel-author`](./finance-excel-author.md), [`pptx-author`](./finance-pptx-author.md), [`dcf-model`](./finance-dcf-model.md), [`3-statement-model`](./finance-3-statement-model.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/finance/finance-pptx-author.md b/website/docs/user-guide/skills/optional/finance/finance-pptx-author.md
index 4f5b5f28c3..169aad660c 100644
--- a/website/docs/user-guide/skills/optional/finance/finance-pptx-author.md
+++ b/website/docs/user-guide/skills/optional/finance/finance-pptx-author.md
@@ -21,7 +21,7 @@ Build PowerPoint decks headless with python-pptx.
 | License | Apache-2.0 |
 | Platforms | linux, macos, windows |
 | Tags | `powerpoint`, `pptx`, `python-pptx`, `presentation`, `finance` |
-| Related skills | [`excel-author`](/docs/user-guide/skills/optional/finance/finance-excel-author), [`powerpoint`](/docs/user-guide/skills/bundled/productivity/productivity-powerpoint) |
+| Related skills | [`excel-author`](./finance-excel-author.md), [`powerpoint`](../../bundled/productivity/productivity-powerpoint.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/finance/finance-stocks.md b/website/docs/user-guide/skills/optional/finance/finance-stocks.md
index b855ca4ac3..115c432aa8 100644
--- a/website/docs/user-guide/skills/optional/finance/finance-stocks.md
+++ b/website/docs/user-guide/skills/optional/finance/finance-stocks.md
@@ -21,7 +21,7 @@ Stock quotes, history, search, compare, crypto via Yahoo.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Stocks`, `Finance`, `Market`, `Crypto`, `Investing` |
-| Related skills | [`dcf-model`](/docs/user-guide/skills/optional/finance/finance-dcf-model), [`comps-analysis`](/docs/user-guide/skills/optional/finance/finance-comps-analysis), [`lbo-model`](/docs/user-guide/skills/optional/finance/finance-lbo-model) |
+| Related skills | [`dcf-model`](./finance-dcf-model.md), [`comps-analysis`](./finance-comps-analysis.md), [`lbo-model`](./finance-lbo-model.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/mcp/mcp-fastmcp.md b/website/docs/user-guide/skills/optional/mcp/mcp-fastmcp.md
index 2665417067..5268be09cc 100644
--- a/website/docs/user-guide/skills/optional/mcp/mcp-fastmcp.md
+++ b/website/docs/user-guide/skills/optional/mcp/mcp-fastmcp.md
@@ -21,7 +21,7 @@ Build, test, and deploy Python MCP servers.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `MCP`, `FastMCP`, `Python`, `Tools`, `Resources`, `Prompts`, `Deployment` |
-| Related skills | [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent), [`mcporter`](/docs/user-guide/skills/optional/mcp/mcp-mcporter) |
+| Related skills | [`hermes-agent`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md), [`mcporter`](./mcp-mcporter.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/mcp/mcp-mcp-oauth-remote-gateway.md b/website/docs/user-guide/skills/optional/mcp/mcp-mcp-oauth-remote-gateway.md
index 6e43ce44d1..710c13365f 100644
--- a/website/docs/user-guide/skills/optional/mcp/mcp-mcp-oauth-remote-gateway.md
+++ b/website/docs/user-guide/skills/optional/mcp/mcp-mcp-oauth-remote-gateway.md
@@ -21,7 +21,7 @@ Manual OAuth for remote MCP servers on headless gateways.
 | License | MIT |
 | Platforms | linux, macos |
 | Tags | `MCP`, `OAuth`, `PKCE`, `Remote-Deployment` |
-| Related skills | [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent), [`mcporter`](/docs/user-guide/skills/optional/mcp/mcp-mcporter), [`fastmcp`](/docs/user-guide/skills/optional/mcp/mcp-fastmcp) |
+| Related skills | [`hermes-agent`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md), [`mcporter`](./mcp-mcporter.md), [`fastmcp`](./mcp-fastmcp.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/migration/migration-openclaw-migration.md b/website/docs/user-guide/skills/optional/migration/migration-openclaw-migration.md
index 43519fcac5..216182efec 100644
--- a/website/docs/user-guide/skills/optional/migration/migration-openclaw-migration.md
+++ b/website/docs/user-guide/skills/optional/migration/migration-openclaw-migration.md
@@ -21,7 +21,7 @@ Import an OpenClaw setup (memories, skills) into Hermes.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Migration`, `OpenClaw`, `Hermes`, `Memory`, `Persona`, `Import` |
-| Related skills | [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
+| Related skills | [`hermes-agent`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-obliteratus.md b/website/docs/user-guide/skills/optional/mlops/mlops-obliteratus.md
index 0562055dad..e8b0ea9267 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-obliteratus.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-obliteratus.md
@@ -22,7 +22,7 @@ OBLITERATUS: abliterate LLM refusals (diff-in-means).
 | Dependencies | `obliteratus`, `torch`, `transformers`, `bitsandbytes`, `accelerate`, `safetensors` |
 | Platforms | linux, macos |
 | Tags | `Abliteration`, `Uncensoring`, `Refusal-Removal`, `LLM`, `Weight-Projection`, `SVD`, `Mechanistic-Interpretability`, `HuggingFace`, `Model-Surgery` |
-| Related skills | [`serving-llms-vllm`](/docs/user-guide/skills/optional/mlops/mlops-inference-serving-llms-vllm), [`llama-cpp`](/docs/user-guide/skills/optional/mlops/mlops-inference-llama-cpp), [`huggingface-tokenizers`](/docs/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers) |
+| Related skills | [`serving-llms-vllm`](./mlops-inference-serving-llms-vllm.md), [`llama-cpp`](./mlops-inference-llama-cpp.md), [`huggingface-tokenizers`](./mlops-huggingface-tokenizers.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/payments/payments-mpp-agent.md b/website/docs/user-guide/skills/optional/payments/payments-mpp-agent.md
index c20c9d84e5..9cd7c78fa4 100644
--- a/website/docs/user-guide/skills/optional/payments/payments-mpp-agent.md
+++ b/website/docs/user-guide/skills/optional/payments/payments-mpp-agent.md
@@ -21,7 +21,7 @@ Pay HTTP 402 APIs via Machine Payments Protocol (MPP).
 | License | MIT |
 | Platforms | linux, macos |
 | Tags | `Payments`, `MPP`, `HTTP-402`, `Tempo`, `Stripe` |
-| Related skills | [`stripe-link-cli`](/docs/user-guide/skills/optional/payments/payments-stripe-link-cli), [`stripe-projects`](/docs/user-guide/skills/optional/payments/payments-stripe-projects) |
+| Related skills | [`stripe-link-cli`](./payments-stripe-link-cli.md), [`stripe-projects`](./payments-stripe-projects.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/payments/payments-stripe-link-cli.md b/website/docs/user-guide/skills/optional/payments/payments-stripe-link-cli.md
index 569ad6f420..7e0c5b2581 100644
--- a/website/docs/user-guide/skills/optional/payments/payments-stripe-link-cli.md
+++ b/website/docs/user-guide/skills/optional/payments/payments-stripe-link-cli.md
@@ -21,7 +21,7 @@ Agent payments via Stripe Link — cards, SPT, approvals.
 | License | MIT |
 | Platforms | linux, macos |
 | Tags | `Payments`, `Stripe`, `Link`, `Checkout`, `MPP` |
-| Related skills | [`mpp-agent`](/docs/user-guide/skills/optional/payments/payments-mpp-agent), [`stripe-projects`](/docs/user-guide/skills/optional/payments/payments-stripe-projects) |
+| Related skills | [`mpp-agent`](./payments-mpp-agent.md), [`stripe-projects`](./payments-stripe-projects.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/payments/payments-stripe-projects.md b/website/docs/user-guide/skills/optional/payments/payments-stripe-projects.md
index 7f2b60032c..c1a7279403 100644
--- a/website/docs/user-guide/skills/optional/payments/payments-stripe-projects.md
+++ b/website/docs/user-guide/skills/optional/payments/payments-stripe-projects.md
@@ -21,7 +21,7 @@ Provision SaaS services + sync creds via Stripe Projects.
 | License | MIT |
 | Platforms | linux, macos |
 | Tags | `Payments`, `Stripe`, `Projects`, `Provisioning`, `Infrastructure` |
-| Related skills | [`stripe-link-cli`](/docs/user-guide/skills/optional/payments/payments-stripe-link-cli), [`mpp-agent`](/docs/user-guide/skills/optional/payments/payments-mpp-agent) |
+| Related skills | [`stripe-link-cli`](./payments-stripe-link-cli.md), [`mpp-agent`](./payments-mpp-agent.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/productivity/productivity-decision-questionnaire.md b/website/docs/user-guide/skills/optional/productivity/productivity-decision-questionnaire.md
index 73669a6920..01ee2251a0 100644
--- a/website/docs/user-guide/skills/optional/productivity/productivity-decision-questionnaire.md
+++ b/website/docs/user-guide/skills/optional/productivity/productivity-decision-questionnaire.md
@@ -21,7 +21,7 @@ Turn an unanswerable decision into a questionnaire doc.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `questionnaire`, `decision`, `async`, `stakeholder`, `discovery`, `communication` |
-| Related skills | [`meeting-action-items`](/docs/user-guide/skills/bundled/productivity/productivity-meeting-action-items), [`document-to-action-items`](/docs/user-guide/skills/bundled/productivity/productivity-document-to-action-items) |
+| Related skills | [`meeting-action-items`](../../bundled/productivity/productivity-meeting-action-items.md), [`document-to-action-items`](../../bundled/productivity/productivity-document-to-action-items.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/productivity/productivity-live-dashboard.md b/website/docs/user-guide/skills/optional/productivity/productivity-live-dashboard.md
index 978f70e5c5..9640b311fb 100644
--- a/website/docs/user-guide/skills/optional/productivity/productivity-live-dashboard.md
+++ b/website/docs/user-guide/skills/optional/productivity/productivity-live-dashboard.md
@@ -21,7 +21,7 @@ Build self-updating dashboards from live sources.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `dashboards`, `monitoring`, `status`, `automation`, `reporting` |
-| Related skills | [`product-price-monitor`](/docs/user-guide/skills/bundled/productivity/productivity-product-price-monitor), [`competitor-news-monitor`](/docs/user-guide/skills/bundled/research/research-competitor-news-monitor), [`email-inbox-triage`](/docs/user-guide/skills/bundled/email/email-email-inbox-triage), [`google-workspace`](/docs/user-guide/skills/bundled/productivity/productivity-google-workspace) |
+| Related skills | [`product-price-monitor`](../../bundled/productivity/productivity-product-price-monitor.md), [`competitor-news-monitor`](../../bundled/research/research-competitor-news-monitor.md), [`email-inbox-triage`](../../bundled/email/email-email-inbox-triage.md), [`google-workspace`](../../bundled/productivity/productivity-google-workspace.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/productivity/productivity-shop.md b/website/docs/user-guide/skills/optional/productivity/productivity-shop.md
index 9fde16b2d4..aec2c1399a 100644
--- a/website/docs/user-guide/skills/optional/productivity/productivity-shop.md
+++ b/website/docs/user-guide/skills/optional/productivity/productivity-shop.md
@@ -21,7 +21,7 @@ Shop catalog search, checkout, order tracking, returns.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Shopping`, `E-commerce`, `Shop`, `Products`, `Orders`, `Returns`, `Checkout`, `Reorder` |
-| Related skills | [`shopify`](/docs/user-guide/skills/optional/productivity/productivity-shopify), [`maps`](/docs/user-guide/skills/bundled/productivity/productivity-maps) |
+| Related skills | [`shopify`](./productivity-shopify.md), [`maps`](../../bundled/productivity/productivity-maps.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/productivity/productivity-shopify.md b/website/docs/user-guide/skills/optional/productivity/productivity-shopify.md
index 622860fe72..fbd68f3d05 100644
--- a/website/docs/user-guide/skills/optional/productivity/productivity-shopify.md
+++ b/website/docs/user-guide/skills/optional/productivity/productivity-shopify.md
@@ -21,7 +21,7 @@ Query Shopify Admin/Storefront GraphQL APIs via curl.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Shopify`, `E-commerce`, `Commerce`, `API`, `GraphQL` |
-| Related skills | [`airtable`](/docs/user-guide/skills/bundled/productivity/productivity-airtable), [`xurl`](/docs/user-guide/skills/bundled/social-media/social-media-xurl) |
+| Related skills | [`airtable`](../../bundled/productivity/productivity-airtable.md), [`xurl`](../../bundled/social-media/social-media-xurl.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/productivity/productivity-siyuan.md b/website/docs/user-guide/skills/optional/productivity/productivity-siyuan.md
index d14d3cc2bb..8c939a290d 100644
--- a/website/docs/user-guide/skills/optional/productivity/productivity-siyuan.md
+++ b/website/docs/user-guide/skills/optional/productivity/productivity-siyuan.md
@@ -21,7 +21,7 @@ Query and edit a SiYuan knowledge base via its API.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `SiYuan`, `Notes`, `Knowledge Base`, `PKM`, `API` |
-| Related skills | [`obsidian`](/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian), [`notion`](/docs/user-guide/skills/bundled/productivity/productivity-notion) |
+| Related skills | [`obsidian`](../../bundled/note-taking/note-taking-obsidian.md), [`notion`](../../bundled/productivity/productivity-notion.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/productivity/productivity-telephony.md b/website/docs/user-guide/skills/optional/productivity/productivity-telephony.md
index db27beb31c..49c4858f41 100644
--- a/website/docs/user-guide/skills/optional/productivity/productivity-telephony.md
+++ b/website/docs/user-guide/skills/optional/productivity/productivity-telephony.md
@@ -21,7 +21,7 @@ Provision Twilio numbers, SMS/MMS, and AI outbound calls.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `telephony`, `phone`, `sms`, `mms`, `voice`, `twilio`, `bland.ai`, `vapi`, `calling`, `texting` |
-| Related skills | [`maps`](/docs/user-guide/skills/bundled/productivity/productivity-maps), [`google-workspace`](/docs/user-guide/skills/bundled/productivity/productivity-google-workspace), [`agentmail`](/docs/user-guide/skills/optional/email/email-agentmail) |
+| Related skills | [`maps`](../../bundled/productivity/productivity-maps.md), [`google-workspace`](../../bundled/productivity/productivity-google-workspace.md), [`agentmail`](../email/email-agentmail.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/research/research-darwinian-evolver.md b/website/docs/user-guide/skills/optional/research/research-darwinian-evolver.md
index edaa29f447..78107b8103 100644
--- a/website/docs/user-guide/skills/optional/research/research-darwinian-evolver.md
+++ b/website/docs/user-guide/skills/optional/research/research-darwinian-evolver.md
@@ -21,7 +21,7 @@ Evolve prompts/regex/SQL/code with Imbue's evolution loop.
 | License | MIT |
 | Platforms | linux, macos |
 | Tags | `evolution`, `optimization`, `prompt-engineering`, `research` |
-| Related skills | [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv), [`jupyter-notebook`](/docs/user-guide/skills/optional/data-science/data-science-jupyter-notebook) |
+| Related skills | [`arxiv`](../../bundled/research/research-arxiv.md), [`jupyter-notebook`](../data-science/data-science-jupyter-notebook.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/research/research-duckduckgo-search.md b/website/docs/user-guide/skills/optional/research/research-duckduckgo-search.md
index a299c47452..5786b31414 100644
--- a/website/docs/user-guide/skills/optional/research/research-duckduckgo-search.md
+++ b/website/docs/user-guide/skills/optional/research/research-duckduckgo-search.md
@@ -21,7 +21,7 @@ Free keyless web, news, and image search via ddgs.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `search`, `duckduckgo`, `web-search`, `free`, `fallback` |
-| Related skills | [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv) |
+| Related skills | [`arxiv`](../../bundled/research/research-arxiv.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/research/research-gitnexus-explorer.md b/website/docs/user-guide/skills/optional/research/research-gitnexus-explorer.md
index 7829a44327..80f92a69f6 100644
--- a/website/docs/user-guide/skills/optional/research/research-gitnexus-explorer.md
+++ b/website/docs/user-guide/skills/optional/research/research-gitnexus-explorer.md
@@ -21,7 +21,7 @@ Serve an interactive codebase knowledge graph web UI.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `gitnexus`, `code-intelligence`, `knowledge-graph`, `visualization` |
-| Related skills | [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent), [`codebase-inspection`](/docs/user-guide/skills/bundled/software-development/software-development-codebase-inspection) |
+| Related skills | [`hermes-agent`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md), [`codebase-inspection`](../../bundled/software-development/software-development-codebase-inspection.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/research/research-osint-investigation.md b/website/docs/user-guide/skills/optional/research/research-osint-investigation.md
index 983315afef..7287b65f9e 100644
--- a/website/docs/user-guide/skills/optional/research/research-osint-investigation.md
+++ b/website/docs/user-guide/skills/optional/research/research-osint-investigation.md
@@ -21,7 +21,7 @@ Follow the money via public records and sanctions data.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `osint`, `investigation`, `public-records`, `sec`, `sanctions`, `corporate-registry`, `property`, `courts`, `due-diligence`, `journalism` |
-| Related skills | [`domain-intel`](/docs/user-guide/skills/optional/research/research-domain-intel), [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv) |
+| Related skills | [`domain-intel`](./research-domain-intel.md), [`arxiv`](../../bundled/research/research-arxiv.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/research/research-parallel-cli.md b/website/docs/user-guide/skills/optional/research/research-parallel-cli.md
index 844c62a213..c09419c522 100644
--- a/website/docs/user-guide/skills/optional/research/research-parallel-cli.md
+++ b/website/docs/user-guide/skills/optional/research/research-parallel-cli.md
@@ -21,7 +21,7 @@ Agent-native web search, deep research, and enrichment.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Research`, `Web`, `Search`, `Deep-Research`, `Enrichment`, `CLI` |
-| Related skills | [`duckduckgo-search`](/docs/user-guide/skills/optional/research/research-duckduckgo-search), [`mcporter`](/docs/user-guide/skills/optional/mcp/mcp-mcporter) |
+| Related skills | [`duckduckgo-search`](./research-duckduckgo-search.md), [`mcporter`](../mcp/mcp-mcporter.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/research/research-qmd.md b/website/docs/user-guide/skills/optional/research/research-qmd.md
index 4b0dc1373c..ddc21fc076 100644
--- a/website/docs/user-guide/skills/optional/research/research-qmd.md
+++ b/website/docs/user-guide/skills/optional/research/research-qmd.md
@@ -21,7 +21,7 @@ Hybrid local search over notes, docs, and transcripts.
 | License | MIT |
 | Platforms | macos, linux |
 | Tags | `Search`, `Knowledge-Base`, `RAG`, `Notes`, `MCP`, `Local-AI` |
-| Related skills | [`obsidian`](/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian), [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent), [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv) |
+| Related skills | [`obsidian`](../../bundled/note-taking/note-taking-obsidian.md), [`hermes-agent`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md), [`arxiv`](../../bundled/research/research-arxiv.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/research/research-research-paper-writing.md b/website/docs/user-guide/skills/optional/research/research-research-paper-writing.md
index f6fd04e6ba..ead1781cce 100644
--- a/website/docs/user-guide/skills/optional/research/research-research-paper-writing.md
+++ b/website/docs/user-guide/skills/optional/research/research-research-paper-writing.md
@@ -22,7 +22,7 @@ Write ML papers for NeurIPS/ICML/ICLR: design→submit.
 | Dependencies | `semanticscholar`, `arxiv`, `habanero`, `requests`, `scipy`, `numpy`, `matplotlib`, `SciencePlots` |
 | Platforms | linux, macos |
 | Tags | `Research`, `Paper Writing`, `Experiments`, `ML`, `AI`, `NeurIPS`, `ICML`, `ICLR`, `ACL`, `AAAI`, `COLM`, `LaTeX`, `Citations`, `Statistical Analysis` |
-| Related skills | [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development) |
+| Related skills | [`arxiv`](../../bundled/research/research-arxiv.md), [`subagent-driven-development`](../software-development/software-development-subagent-driven-development.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/research/research-rss-feeds.md b/website/docs/user-guide/skills/optional/research/research-rss-feeds.md
index e5e951d1f5..20bab27f46 100644
--- a/website/docs/user-guide/skills/optional/research/research-rss-feeds.md
+++ b/website/docs/user-guide/skills/optional/research/research-rss-feeds.md
@@ -21,7 +21,7 @@ Read RSS, Atom, JSON feeds; discover feeds behind a page.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `RSS`, `Atom`, `Feeds`, `Monitoring`, `Research`, `Blogs`, `Releases` |
-| Related skills | [`reddit-reading`](/docs/user-guide/skills/optional/social-media/social-media-reddit-reading), [`competitor-news-monitor`](/docs/user-guide/skills/bundled/research/research-competitor-news-monitor), [`grounded-citations`](/docs/user-guide/skills/bundled/research/research-grounded-citations), [`youtube-content`](/docs/user-guide/skills/bundled/media/media-youtube-content), [`blogwatcher`](/docs/user-guide/skills/optional/research/research-blogwatcher) |
+| Related skills | [`reddit-reading`](../social-media/social-media-reddit-reading.md), [`competitor-news-monitor`](../../bundled/research/research-competitor-news-monitor.md), [`grounded-citations`](../../bundled/research/research-grounded-citations.md), [`youtube-content`](../../bundled/media/media-youtube-content.md), [`blogwatcher`](./research-blogwatcher.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/research/research-scrapling.md b/website/docs/user-guide/skills/optional/research/research-scrapling.md
index 778906aa94..2ed170d5d1 100644
--- a/website/docs/user-guide/skills/optional/research/research-scrapling.md
+++ b/website/docs/user-guide/skills/optional/research/research-scrapling.md
@@ -21,7 +21,7 @@ Scrape sites with stealth browsing and Cloudflare bypass.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Web Scraping`, `Browser`, `Cloudflare`, `Stealth`, `Crawling`, `Spider` |
-| Related skills | [`duckduckgo-search`](/docs/user-guide/skills/optional/research/research-duckduckgo-search), [`domain-intel`](/docs/user-guide/skills/optional/research/research-domain-intel) |
+| Related skills | [`duckduckgo-search`](./research-duckduckgo-search.md), [`domain-intel`](./research-domain-intel.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/research/research-searxng-search.md b/website/docs/user-guide/skills/optional/research/research-searxng-search.md
index 29dbe8f80b..dca2c40bf2 100644
--- a/website/docs/user-guide/skills/optional/research/research-searxng-search.md
+++ b/website/docs/user-guide/skills/optional/research/research-searxng-search.md
@@ -21,7 +21,7 @@ Free keyless meta-search aggregating 70+ engines.
 | License | MIT |
 | Platforms | linux, macos |
 | Tags | `search`, `searxng`, `meta-search`, `self-hosted`, `free`, `fallback` |
-| Related skills | [`duckduckgo-search`](/docs/user-guide/skills/optional/research/research-duckduckgo-search), [`domain-intel`](/docs/user-guide/skills/optional/research/research-domain-intel) |
+| Related skills | [`duckduckgo-search`](./research-duckduckgo-search.md), [`domain-intel`](./research-domain-intel.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/security/security-godmode.md b/website/docs/user-guide/skills/optional/security/security-godmode.md
index 07eb995afb..bb2451cc9e 100644
--- a/website/docs/user-guide/skills/optional/security/security-godmode.md
+++ b/website/docs/user-guide/skills/optional/security/security-godmode.md
@@ -21,7 +21,7 @@ Jailbreak LLMs: Parseltongue, GODMODE, ULTRAPLINIAN.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `jailbreak`, `red-teaming`, `G0DM0D3`, `Parseltongue`, `GODMODE`, `uncensoring`, `safety-bypass`, `prompt-engineering`, `L1B3RT4S` |
-| Related skills | [`obliteratus`](/docs/user-guide/skills/optional/mlops/mlops-obliteratus) |
+| Related skills | [`obliteratus`](../mlops/mlops-obliteratus.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/security/security-unbroker.md b/website/docs/user-guide/skills/optional/security/security-unbroker.md
index 3e8ea8d8fa..9cfeea1e90 100644
--- a/website/docs/user-guide/skills/optional/security/security-unbroker.md
+++ b/website/docs/user-guide/skills/optional/security/security-unbroker.md
@@ -21,7 +21,7 @@ Autonomously remove your info from data-broker sites.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `privacy`, `data-broker`, `opt-out`, `ccpa`, `gdpr`, `security`, `doxxing` |
-| Related skills | [`google-workspace`](/docs/user-guide/skills/bundled/productivity/productivity-google-workspace), [`agentmail`](/docs/user-guide/skills/optional/email/email-agentmail), [`himalaya`](/docs/user-guide/skills/bundled/email/email-himalaya), [`scrapling`](/docs/user-guide/skills/optional/research/research-scrapling), [`osint-investigation`](/docs/user-guide/skills/optional/research/research-osint-investigation) |
+| Related skills | [`google-workspace`](../../bundled/productivity/productivity-google-workspace.md), [`agentmail`](../email/email-agentmail.md), [`himalaya`](../../bundled/email/email-himalaya.md), [`scrapling`](../research/research-scrapling.md), [`osint-investigation`](../research/research-osint-investigation.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/social-media/social-media-reddit-reading.md b/website/docs/user-guide/skills/optional/social-media/social-media-reddit-reading.md
index 3d299ff235..f3c4e12ecb 100644
--- a/website/docs/user-guide/skills/optional/social-media/social-media-reddit-reading.md
+++ b/website/docs/user-guide/skills/optional/social-media/social-media-reddit-reading.md
@@ -21,7 +21,7 @@ Read Reddit: subreddits, search, threads, users. No browser.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Reddit`, `Social Media`, `Research`, `Discussions`, `Community` |
-| Related skills | [`rss-feeds`](/docs/user-guide/skills/optional/research/research-rss-feeds), [`grounded-citations`](/docs/user-guide/skills/bundled/research/research-grounded-citations), [`blocked-page-recovery`](/docs/user-guide/skills/bundled/web/web-blocked-page-recovery), [`xurl`](/docs/user-guide/skills/bundled/social-media/social-media-xurl) |
+| Related skills | [`rss-feeds`](../research/research-rss-feeds.md), [`grounded-citations`](../../bundled/research/research-grounded-citations.md), [`blocked-page-recovery`](../../bundled/web/web-blocked-page-recovery.md), [`xurl`](../../bundled/social-media/social-media-xurl.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/software-development/software-development-ast-grep.md b/website/docs/user-guide/skills/optional/software-development/software-development-ast-grep.md
index 5d02d37d11..ae2582e9d0 100644
--- a/website/docs/user-guide/skills/optional/software-development/software-development-ast-grep.md
+++ b/website/docs/user-guide/skills/optional/software-development/software-development-ast-grep.md
@@ -21,7 +21,7 @@ AST-aware structural code search and rewrite via ast-grep.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `ast`, `codemod`, `refactoring`, `structural-search`, `code-search`, `rewrite`, `tree-sitter` |
-| Related skills | [`simplify-code`](/docs/user-guide/skills/bundled/software-development/software-development-simplify-code), [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging) |
+| Related skills | [`simplify-code`](../../bundled/software-development/software-development-simplify-code.md), [`systematic-debugging`](../../bundled/software-development/software-development-systematic-debugging.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/software-development/software-development-code-wiki.md b/website/docs/user-guide/skills/optional/software-development/software-development-code-wiki.md
index 1ee750b2a7..0dbe7cc06c 100644
--- a/website/docs/user-guide/skills/optional/software-development/software-development-code-wiki.md
+++ b/website/docs/user-guide/skills/optional/software-development/software-development-code-wiki.md
@@ -21,7 +21,7 @@ Generate wiki docs + Mermaid diagrams for any codebase.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Documentation`, `Mermaid`, `Architecture`, `Diagrams`, `Wiki`, `Code-Analysis` |
-| Related skills | [`codebase-inspection`](/docs/user-guide/skills/bundled/software-development/software-development-codebase-inspection), `github-repo-management` |
+| Related skills | [`codebase-inspection`](../../bundled/software-development/software-development-codebase-inspection.md), `github-repo-management` |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/software-development/software-development-grill-me.md b/website/docs/user-guide/skills/optional/software-development/software-development-grill-me.md
index 1890f819a5..e28f7fb7ac 100644
--- a/website/docs/user-guide/skills/optional/software-development/software-development-grill-me.md
+++ b/website/docs/user-guide/skills/optional/software-development/software-development-grill-me.md
@@ -21,7 +21,7 @@ Adversarial plan interview before implementation.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `planning`, `adversarial`, `interview`, `decision-tree`, `pre-implementation`, `review`, `alignment` |
-| Related skills | [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development) |
+| Related skills | [`requesting-code-review`](../../bundled/software-development/software-development-requesting-code-review.md), [`subagent-driven-development`](./software-development-subagent-driven-development.md), [`test-driven-development`](../../bundled/software-development/software-development-test-driven-development.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/software-development/software-development-rest-graphql-debug.md b/website/docs/user-guide/skills/optional/software-development/software-development-rest-graphql-debug.md
index 616274754c..e1d1b7a2d4 100644
--- a/website/docs/user-guide/skills/optional/software-development/software-development-rest-graphql-debug.md
+++ b/website/docs/user-guide/skills/optional/software-development/software-development-rest-graphql-debug.md
@@ -21,7 +21,7 @@ Debug REST/GraphQL APIs: status codes, auth, schemas, repro.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `api`, `rest`, `graphql`, `http`, `debugging`, `testing`, `curl`, `integration` |
-| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development) |
+| Related skills | [`systematic-debugging`](../../bundled/software-development/software-development-systematic-debugging.md), [`test-driven-development`](../../bundled/software-development/software-development-test-driven-development.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development.md b/website/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development.md
index 5e42f93712..7403e38e5a 100644
--- a/website/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development.md
+++ b/website/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development.md
@@ -21,7 +21,7 @@ Execute plans via delegate_task subagents (2-stage review).
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `delegation`, `subagent`, `implementation`, `workflow`, `parallel` |
-| Related skills | [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development) |
+| Related skills | [`requesting-code-review`](../../bundled/software-development/software-development-requesting-code-review.md), [`test-driven-development`](../../bundled/software-development/software-development-test-driven-development.md) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/tui.md b/website/docs/user-guide/tui.md
index 6027ab1da6..d2e22a81ad 100644
--- a/website/docs/user-guide/tui.md
+++ b/website/docs/user-guide/tui.md
@@ -102,7 +102,7 @@ The directory must contain `dist/entry.js`.
 
 Keybindings match the [Classic CLI](cli.md#keybindings) exactly. The only behavioral differences:
 
-- **`Ctrl+T`** expands the automatic live-subagent dock into the full-height `/agents` roster. Select a worker and press **Enter** (or **`t`**) for its live transcript, **`d`** for rich details, **`e`** to steer, or **`x`** to stop it. The dock fits its row count to terminal height and preserves your composer draft. See [Monitoring subagents](/user-guide/features/delegation#monitoring-running-subagents-agents).
+- **`Ctrl+T`** expands the automatic live-subagent dock into the full-height `/agents` roster. Select a worker and press **Enter** (or **`t`**) for its live transcript, **`d`** for rich details, **`e`** to steer, or **`x`** to stop it. The dock fits its row count to terminal height and preserves your composer draft. See [Monitoring subagents](./features/delegation.md#monitoring-running-subagents-agents).
 - **`F7`** toggles the live dock between its default preview and one summary line. This does not open the monitor or move composer focus; the choice lasts for this TUI process without changing config.
 - **Mouse drag** highlights text with a uniform selection background.
 - **`Cmd+V` / `Ctrl+V`** first tries normal text paste, then falls back to OSC52/native clipboard reads, and finally image attach when the clipboard or pasted payload resolves to an image.
diff --git a/website/docs/user-guide/which-file-does-what.md b/website/docs/user-guide/which-file-does-what.md
index 153e2648db..fdd9f43de5 100644
--- a/website/docs/user-guide/which-file-does-what.md
+++ b/website/docs/user-guide/which-file-does-what.md
@@ -6,7 +6,7 @@ description: "SOUL.md vs USER.md vs MEMORY.md vs AGENTS.md — a one-page map of
 
 # Which File Does What?
 
-"I told my agent something and it forgot." "Which file is my agent's brain?" "I edited SOUL.md — why doesn't it know my name?" These questions all come down to the same thing: Hermes Agent is shaped by several markdown files, and each one has a different job. This page maps them all in one place. For depth on any of them, follow the links to [Persistent Memory](/user-guide/features/memory), [Personality & SOUL.md](/user-guide/features/personality), and [Context Files](/user-guide/features/context-files).
+"I told my agent something and it forgot." "Which file is my agent's brain?" "I edited SOUL.md — why doesn't it know my name?" These questions all come down to the same thing: Hermes Agent is shaped by several markdown files, and each one has a different job. This page maps them all in one place. For depth on any of them, follow the links to [Persistent Memory](./features/memory.md), [Personality & SOUL.md](./features/personality.md), and [Context Files](./features/context-files.md).
 
 ## The Master Table
 
@@ -19,7 +19,7 @@ description: "SOUL.md vs USER.md vs MEMORY.md vs AGENTS.md — a one-page map of
 | **.hermes.md** / **HERMES.md** | Project instructions, like AGENTS.md but Hermes-specific and highest priority | You | Loaded into the system prompt at startup (first match wins over AGENTS.md) | Your project — discovery walks up to the git root |
 
 :::info One project context file per session
-Only **one** project context type is loaded per session, first match wins: `.hermes.md` → `AGENTS.md` → `CLAUDE.md` → `.cursorrules`. `SOUL.md` is always loaded independently as the agent identity — it is not part of that priority chain. See [Context Files](/user-guide/features/context-files) for the full list, including `CLAUDE.md` and `.cursorrules` compatibility.
+Only **one** project context type is loaded per session, first match wins: `.hermes.md` → `AGENTS.md` → `CLAUDE.md` → `.cursorrules`. `SOUL.md` is always loaded independently as the agent identity — it is not part of that priority chain. See [Context Files](./features/context-files.md) for the full list, including `CLAUDE.md` and `.cursorrules` compatibility.
 :::
 
 A useful shorthand:
@@ -31,27 +31,27 @@ A useful shorthand:
 
 ## "Why did it forget what I just said?"
 
-Memory (MEMORY.md and USER.md) is injected into the system prompt as a **frozen snapshot** captured once at session start — when the agent saves something mid-session, the change is persisted to disk immediately but won't appear in the system prompt until the next session starts. This is intentional: it preserves the LLM's prefix cache for performance, and tool responses always show the live state, so nothing is lost — start a new session and the updated memory is there. Full details in [How Memory Appears in the System Prompt](/user-guide/features/memory#how-memory-appears-in-the-system-prompt).
+Memory (MEMORY.md and USER.md) is injected into the system prompt as a **frozen snapshot** captured once at session start — when the agent saves something mid-session, the change is persisted to disk immediately but won't appear in the system prompt until the next session starts. This is intentional: it preserves the LLM's prefix cache for performance, and tool responses always show the live state, so nothing is lost — start a new session and the updated memory is there. Full details in [How Memory Appears in the System Prompt](./features/memory.md#how-memory-appears-in-the-system-prompt).
 
 ## Common Mix-Ups
 
 ### "I put facts about myself in SOUL.md, but USER.md stayed empty"
 
-`SOUL.md` and `USER.md` are separate systems that never feed each other. `SOUL.md` is a personality file **you** edit directly — it shapes tone and identity, and its content is injected verbatim as slot #1 of the prompt. `USER.md` is part of persistent memory and is written by **the agent** through the `memory` tool. If you want facts about yourself in USER.md, tell the agent ("remember that I prefer concise answers") and it saves them — editing SOUL.md won't populate memory, and memory entries won't change the persona. Use SOUL.md for durable voice and personality guidance; leave preferences and profile facts to memory. See [What should go in SOUL.md?](/user-guide/features/personality#what-should-go-in-soulmd) and [Two Targets Explained](/user-guide/features/memory#two-targets-explained).
+`SOUL.md` and `USER.md` are separate systems that never feed each other. `SOUL.md` is a personality file **you** edit directly — it shapes tone and identity, and its content is injected verbatim as slot #1 of the prompt. `USER.md` is part of persistent memory and is written by **the agent** through the `memory` tool. If you want facts about yourself in USER.md, tell the agent ("remember that I prefer concise answers") and it saves them — editing SOUL.md won't populate memory, and memory entries won't change the persona. Use SOUL.md for durable voice and personality guidance; leave preferences and profile facts to memory. See [What should go in SOUL.md?](./features/personality.md#what-should-go-in-soulmd) and [Two Targets Explained](./features/memory.md#two-targets-explained).
 
 ### "I told it my name mid-session and it acted like it never heard it"
 
 If the agent saved your name to memory, the save worked — check with the `memory` tool's responses or `hermes journey list`. What you're seeing is the frozen-snapshot rule above: the system prompt doesn't refresh mid-session, so the *injected* memory block still shows the session-start state. The agent can still use what you told it within the current conversation (it's in the context), and the saved entry will be in the system prompt from the next session onward. The same applies to edits you make to `SOUL.md` or `AGENTS.md` while a session is running: context is assembled at session start, so restart the session to pick up changes.
 
 :::tip Quick decision guide
-- Want to change how the agent **talks**? Edit `~/.hermes/SOUL.md` — [Personality & SOUL.md](/user-guide/features/personality).
-- Want the agent to **remember a fact**? Just tell it — it saves to memory itself. [Persistent Memory](/user-guide/features/memory).
-- Want to set **project rules**? Put an `AGENTS.md` (or `.hermes.md`) in the project — [Context Files](/user-guide/features/context-files).
+- Want to change how the agent **talks**? Edit `~/.hermes/SOUL.md` — [Personality & SOUL.md](./features/personality.md).
+- Want the agent to **remember a fact**? Just tell it — it saves to memory itself. [Persistent Memory](./features/memory.md).
+- Want to set **project rules**? Put an `AGENTS.md` (or `.hermes.md`) in the project — [Context Files](./features/context-files.md).
 - Need a **temporary** personality change? Use `/personality` — it's a session-level overlay, no file edits needed.
 :::
 
 ## Related Docs
 
-- [Persistent Memory](/user-guide/features/memory) — MEMORY.md, USER.md, the `memory` tool, capacity limits, `write_approval`
-- [Personality & SOUL.md](/user-guide/features/personality) — SOUL.md content guidance, `/personality` presets, the prompt stack
-- [Context Files](/user-guide/features/context-files) — AGENTS.md, `.hermes.md`, progressive discovery, security scanning
+- [Persistent Memory](./features/memory.md) — MEMORY.md, USER.md, the `memory` tool, capacity limits, `write_approval`
+- [Personality & SOUL.md](./features/personality.md) — SOUL.md content guidance, `/personality` presets, the prompt stack
+- [Context Files](./features/context-files.md) — AGENTS.md, `.hermes.md`, progressive discovery, security scanning
diff --git a/website/docs/user-guide/windows-native.md b/website/docs/user-guide/windows-native.md
index 99cb490a8f..42d26afea1 100644
--- a/website/docs/user-guide/windows-native.md
+++ b/website/docs/user-guide/windows-native.md
@@ -9,7 +9,7 @@ sidebar_position: 3
 
 Hermes runs natively on Windows 10 and Windows 11 — no WSL, no Cygwin, no Docker. This page is the deep dive: what works natively, what's WSL-only, what the installer actually does, and the Windows-specific knobs you might need to touch.
 
-If you just want to install, the one-liner on the [landing page](/) or [Installation page](../getting-started/installation#windows-native) is all you need. Come back here when something surprises you.
+If you just want to install, the one-liner on the [landing page](../index.mdx) or [Installation page](../getting-started/installation#windows-native) is all you need. Come back here when something surprises you.
 
 :::tip Want WSL instead?
 If you prefer a real POSIX environment (for the dashboard's embedded terminal, `fork` semantics, Linux-style file watchers, etc.), see the **[Windows (WSL2) Guide](./windows-wsl-quickstart.md)**. Both coexist cleanly: native data lives under `%LOCALAPPDATA%\hermes`, WSL data lives under `~/.hermes`.
@@ -79,7 +79,7 @@ Top-to-bottom, in order:
 10. **Runs `hermes setup`** — the normal first-run wizard (model, provider, toolsets). Skip with `-SkipSetup`.
 
 :::tip Skip provider hunting on Windows
-On Windows, per-tool API key setup (Firecrawl, FAL, Browser Use, OpenAI TTS) is the highest-friction part of getting a useful agent. A [Nous Portal](/user-guide/features/tool-gateway) subscription covers the model **and** all of those tools through one OAuth login. After the installer finishes, run `hermes setup --portal` to wire everything up.
+On Windows, per-tool API key setup (Firecrawl, FAL, Browser Use, OpenAI TTS) is the highest-friction part of getting a useful agent. A [Nous Portal](./features/tool-gateway.md) subscription covers the model **and** all of those tools through one OAuth login. After the installer finishes, run `hermes setup --portal` to wire everything up.
 :::
 
 ## Feature matrix
diff --git a/website/docs/user-guide/windows-wsl-quickstart.md b/website/docs/user-guide/windows-wsl-quickstart.md
index 2128b3be91..9cf804af52 100644
--- a/website/docs/user-guide/windows-wsl-quickstart.md
+++ b/website/docs/user-guide/windows-wsl-quickstart.md
@@ -65,7 +65,7 @@ Hermes does not work reliably on WSL1 — WSL1 translates Linux syscalls on the
 
 ### Distro choice
 
-Ubuntu (LTS) is what we test against. Debian works. Arch and NixOS work for people who want them, but the one-line installer assumes a Debian-derived `apt` system — see the [Nix setup guide](/getting-started/nix-setup) for that path.
+Ubuntu (LTS) is what we test against. Debian works. Arch and NixOS work for people who want them, but the one-line installer assumes a Debian-derived `apt` system — see the [Nix setup guide](../getting-started/nix-setup.md) for that path.
 
 ### Enable systemd (recommended)
 
@@ -105,7 +105,7 @@ source ~/.bashrc
 hermes
 ```
 
-The installer treats WSL2 as plain Linux — nothing WSL-specific is needed. See [Installation](/getting-started/installation) for the full layout.
+The installer treats WSL2 as plain Linux — nothing WSL-specific is needed. See [Installation](../getting-started/installation.md) for the full layout.
 
 ## Filesystem: crossing the Windows ↔ WSL2 boundary
 
@@ -188,7 +188,7 @@ dos2unix path/to/script.sh
 
 Clone inside WSL. Always, unless you have a specific reason not to. A typical Hermes workflow (`hermes chat`, tool calls that `rg`/`ripgrep` the repo, file watchers, background gateway) will be dramatically faster and more reliable against `~/code/myrepo` than `/mnt/c/Users/you/myrepo`.
 
-One exception: **MCP bridges that launch Windows binaries.** If you're using `chrome-devtools-mcp` through `cmd.exe` (see [MCP guide: WSL → Windows Chrome](/guides/use-mcp-with-hermes#wsl2-bridge-hermes-in-wsl-to-windows-chrome)), Windows may complain with a `UNC` warning if Hermes's current working directory is `~`. In that case, start Hermes from somewhere under `/mnt/c/` so the Windows process has a drive-letter cwd.
+One exception: **MCP bridges that launch Windows binaries.** If you're using `chrome-devtools-mcp` through `cmd.exe` (see [MCP guide: WSL → Windows Chrome](../guides/use-mcp-with-hermes.md#wsl2-bridge-hermes-in-wsl-to-windows-chrome)), Windows may complain with a `UNC` warning if Hermes's current working directory is `~`. In that case, start Hermes from somewhere under `/mnt/c/` so the Windows process has a drive-letter cwd.
 
 ## Networking: WSL ↔ Windows
 
@@ -200,7 +200,7 @@ Two cases come up constantly.
 
 Most common: you're running **Ollama, LM Studio, or a llama-server on Windows**, and Hermes (inside WSL) needs to hit it.
 
-The canonical how-to for this lives in the providers guide: **[WSL2 Networking for Local Models →](/integrations/providers#wsl2-networking-windows-users)**
+The canonical how-to for this lives in the providers guide: **[WSL2 Networking for Local Models →](../integrations/providers.md#wsl2-networking-windows-users)**
 
 Short version:
 
@@ -214,7 +214,7 @@ For the full table (Ollama / LM Studio / vLLM / SGLang bind addresses, firewall
 This is the reverse direction and is less documented elsewhere, but it's what you need for:
 
 - Using the Hermes **web dashboard** from a Windows browser.
-- Using the **OpenAI-compatible API server** (exposed by `hermes gateway` when `API_SERVER_ENABLED=true`) from a Windows-side tool. See the [API Server feature page](/user-guide/features/api-server).
+- Using the **OpenAI-compatible API server** (exposed by `hermes gateway` when `API_SERVER_ENABLED=true`) from a Windows-side tool. See the [API Server feature page](./features/api-server.md).
 - Testing a **messaging gateway** (Telegram, Discord, etc.) where the platform pings a local webhook URL — usually you'd use `cloudflared`/`ngrok` rather than raw port forwarding.
 
 #### Subcase 2a: from the Windows host itself
@@ -254,11 +254,11 @@ This is the real pain. Traffic flows **LAN device → Windows host → WSL VM**,
 
 Because the WSL VM IP drifts on each restart in NAT mode, a one-shot rule survives only until the next `wsl --shutdown`. For anything persistent, either use mirrored mode or put the port-proxy step in a script that runs at Windows login.
 
-For webhooks from cloud messaging providers (Telegram `setWebhook`, Slack events, etc.), don't fight port-forwarding — use `cloudflared` tunnels. See the [webhooks guide](/user-guide/messaging/webhooks).
+For webhooks from cloud messaging providers (Telegram `setWebhook`, Slack events, etc.), don't fight port-forwarding — use `cloudflared` tunnels. See the [webhooks guide](./messaging/webhooks.md).
 
 ## Running Hermes services long-term on Windows
 
-The Hermes [Tool Gateway](/user-guide/features/tool-gateway) and the API server are long-lived processes. In WSL2 you have a few options for keeping them up.
+The Hermes [Tool Gateway](./features/tool-gateway.md) and the API server are long-lived processes. In WSL2 you have a few options for keeping them up.
 
 ### Desktop shortcut for opening Hermes quickly
 
@@ -318,7 +318,7 @@ If you're running a **Windows-native** local-model server (Ollama for Windows, L
 ## Common pitfalls
 
 **"Connection refused" to my Windows-hosted Ollama / LM Studio.**
-See [WSL2 Networking](/integrations/providers#wsl2-networking-windows-users). Ninety percent of the time the server is bound to `127.0.0.1` and needs `0.0.0.0` (Ollama: `OLLAMA_HOST=0.0.0.0`), or you're missing a firewall rule.
+See [WSL2 Networking](../integrations/providers.md#wsl2-networking-windows-users). Ninety percent of the time the server is bound to `127.0.0.1` and needs `0.0.0.0` (Ollama: `OLLAMA_HOST=0.0.0.0`), or you're missing a firewall rule.
 
 **Massive slowness on `git status` / `hermes chat` in a repo.**
 You're probably working under `/mnt/c/...`. Move the repo to `~/code/...` (Linux side). Order-of-magnitude faster.
@@ -352,7 +352,7 @@ WSL2 stores its VM disk as a sparse VHDX under `%LOCALAPPDATA%\Packages\...`. It
 
 ## Where to go next
 
-- **[Installation](/getting-started/installation)** — actual install steps (Linux/WSL2/Termux all use the same installer).
-- **[Integrations → Providers → WSL2 Networking](/integrations/providers#wsl2-networking-windows-users)** — the canonical networking deep-dive for local model servers.
-- **[MCP guide → WSL → Windows Chrome](/guides/use-mcp-with-hermes#wsl2-bridge-hermes-in-wsl-to-windows-chrome)** — controlling your signed-in Windows Chrome from Hermes in WSL.
-- **[Tool Gateway](/user-guide/features/tool-gateway)** and **[Web Dashboard](/user-guide/features/web-dashboard)** — the long-lived services you'll most often want to expose from WSL to the rest of your network.
+- **[Installation](../getting-started/installation.md)** — actual install steps (Linux/WSL2/Termux all use the same installer).
+- **[Integrations → Providers → WSL2 Networking](../integrations/providers.md#wsl2-networking-windows-users)** — the canonical networking deep-dive for local model servers.
+- **[MCP guide → WSL → Windows Chrome](../guides/use-mcp-with-hermes.md#wsl2-bridge-hermes-in-wsl-to-windows-chrome)** — controlling your signed-in Windows Chrome from Hermes in WSL.
+- **[Tool Gateway](./features/tool-gateway.md)** and **[Web Dashboard](./features/web-dashboard.md)** — the long-lived services you'll most often want to expose from WSL to the rest of your network.
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/adding-providers.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/adding-providers.md
index 638f47df2e..b3a8635639 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/adding-providers.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/adding-providers.md
@@ -121,7 +121,7 @@ Hermes 已经可以通过自定义 provider 路径与任何 OpenAI 兼容的端
 
 位于 `$HERMES_HOME/plugins/model-providers/<name>/` 的用户插件会覆盖同名的捆绑插件（`register_provider()` 中后写者获胜）——因此第三方可以在不编辑本仓库的情况下对任何内置 profile 进行 monkey-patch 或替换。
 
-参见 `plugins/model-providers/nvidia/` 或 `plugins/model-providers/gmi/` 作为模板，以及完整的 [Model Provider Plugin 指南](/developer-guide/model-provider-plugin)，了解字段参考、hook 用法和端到端示例。
+参见 `plugins/model-providers/nvidia/` 或 `plugins/model-providers/gmi/` 作为模板，以及完整的 [Model Provider Plugin 指南](./model-provider-plugin.md)，了解字段参考、hook 用法和端到端示例。
 
 ## 完整路径：OAuth 和复杂 provider
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/adding-tools.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/adding-tools.md
index bc9eb457ec..face057e75 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/adding-tools.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/adding-tools.md
@@ -12,8 +12,8 @@ description: "如何向 Hermes Agent 添加新工具——schema、handler、注
 本页面用于向仓库本身添加 **Hermes 内置工具**。
 如果你想要个人专用、项目本地或其他自定义工具，而不修改 Hermes 核心，请使用插件方式：
 
-- [插件](/user-guide/features/plugins)
-- [构建 Hermes 插件](/developer-guide/plugins)
+- [插件](../user-guide/features/plugins.md)
+- [构建 Hermes 插件](./plugins/index.md)
 
 大多数自定义工具创建场景默认使用插件。只有当你明确希望在 `tools/` 和 `toolsets.py` 中发布新的内置工具时，才遵循本页面。
 :::
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/architecture.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/architecture.md
index 0c66f496fa..51bafa46c8 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/architecture.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/architecture.md
@@ -231,7 +231,7 @@ CLI、gateway、cron、ACP 及辅助调用共用的运行时解析器。将 `(pr
 
 三种发现来源：`~/.hermes/plugins/`（用户级）、`.hermes/plugins/`（项目级）和 pip entry point。插件通过上下文 API 注册工具、hook 和 CLI 命令。存在两种专用插件类型：记忆提供者（`plugins/memory/`）和上下文引擎（`plugins/context_engine/`）。两者均为单选——每种同时只能激活一个，通过 `hermes plugins` 或 `config.yaml` 配置。
 
-→ [插件指南](/developer-guide/plugins)，[记忆提供者插件](./memory-provider-plugin.md)
+→ [插件指南](./plugins/index.md)，[记忆提供者插件](./memory-provider-plugin.md)
 
 ### Cron
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/context-compression-and-caching.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/context-compression-and-caching.md
index 5917b50c86..76ecb04485 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/context-compression-and-caching.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/context-compression-and-caching.md
@@ -36,7 +36,7 @@ context:
 
 通过 `hermes plugins` → Provider Plugins → Context Engine 进行配置，或直接编辑 `config.yaml`。
 
-关于构建上下文引擎插件，请参阅 [Context Engine 插件](/developer-guide/context-engine-plugin)。
+关于构建上下文引擎插件，请参阅 [Context Engine 插件](./context-engine-plugin.md)。
 
 ## 双重压缩系统
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/context-engine-plugin.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/context-engine-plugin.md
index 3356bf64e4..980b0147b1 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/context-engine-plugin.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/context-engine-plugin.md
@@ -188,6 +188,6 @@ def test_compress_returns_valid_messages():
 
 ## 另请参阅
 
-- [上下文压缩与缓存](/developer-guide/context-compression-and-caching) — 内置压缩器的工作原理
-- [Memory Provider 插件](/developer-guide/memory-provider-plugin) — 类似的单选插件系统（用于内存）
-- [插件](/user-guide/features/plugins) — 通用插件系统概述
\ No newline at end of file
+- [上下文压缩与缓存](./context-compression-and-caching.md) — 内置压缩器的工作原理
+- [Memory Provider 插件](./memory-provider-plugin.md) — 类似的单选插件系统（用于内存）
+- [插件](../user-guide/features/plugins.md) — 通用插件系统概述
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/creating-skills.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/creating-skills.md
index 728e24ac4b..05f94d421c 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/creating-skills.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/creating-skills.md
@@ -173,7 +173,7 @@ required_environment_variables:
 用户可以跳过配置并继续加载 skill。Hermes 不会将原始密钥值暴露给模型。Gateway 和消息会话会显示本地配置指引，而不是在带内收集密钥。
 
 :::tip 沙箱透传
-加载 skill 时，已设置的 `required_environment_variables` 会**自动透传**到 `execute_code` 和 `terminal` 沙箱——包括 Docker 和 Modal 等远程后端。Skill 的脚本无需用户额外配置即可访问 `$TENOR_API_KEY`（或 Python 中的 `os.environ["TENOR_API_KEY"]`）。详见 [环境变量透传](/user-guide/security#environment-variable-passthrough)。
+加载 skill 时，已设置的 `required_environment_variables` 会**自动透传**到 `execute_code` 和 `terminal` 沙箱——包括 Docker 和 Modal 等远程后端。Skill 的脚本无需用户额外配置即可访问 `$TENOR_API_KEY`（或 Python 中的 `os.environ["TENOR_API_KEY"]`）。详见 [环境变量透传](../user-guide/security.md#environment-variable-passthrough)。
 :::
 
 旧版 `prerequisites.env_vars` 作为向后兼容的别名仍受支持。
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/cron-internals.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/cron-internals.md
index 71f91fdbb3..9ccb812c6d 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/cron-internals.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/cron-internals.md
@@ -231,6 +231,6 @@ hermes cron remove <job_id>         # 删除任务
 
 ## 相关文档
 
-- [Cron 功能指南](/user-guide/features/cron)
+- [Cron 功能指南](../user-guide/features/cron.md)
 - [Gateway 内部机制](./gateway-internals.md)
 - [Agent 循环内部机制](./agent-loop.md)
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/gateway-internals.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/gateway-internals.md
index b67a6c872e..8e385859fe 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/gateway-internals.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/gateway-internals.md
@@ -193,7 +193,7 @@ gateway/platforms/                  # 核心 base 与旧的直接适配器
 
 - **直接回复** — 将响应发回原始聊天
 - **主频道投递** — 将 cron 任务输出和后台结果路由至已配置的主频道
-- **显式目标投递** — `send_message` 工具指定 `telegram:-1001234567890`，或通过 [`hermes send` CLI](/guides/pipe-script-output) 封装同一工具供 shell 脚本使用
+- **显式目标投递** — `send_message` 工具指定 `telegram:-1001234567890`，或通过 [`hermes send` CLI](../guides/pipe-script-output.md) 封装同一工具供 shell 脚本使用
 - **跨平台投递** — 投递至与原始消息不同的平台
 
 Cron 任务投递**不会**镜像到 gateway 会话历史中 — 它们仅存在于各自的 cron 会话中。这是有意为之的设计选择，以避免消息交替违规。
@@ -264,4 +264,4 @@ Gateway 作为长期运行进程运行，管理方式如下：
 - [Cron 内部机制](./cron-internals.md)
 - [ACP 内部机制](./acp-internals.md)
 - [Agent 循环内部机制](./agent-loop.md)
-- [消息 Gateway（用户指南）](/user-guide/messaging)
\ No newline at end of file
+- [消息 Gateway（用户指南）](../user-guide/messaging/index.md)
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/image-gen-provider-plugin.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/image-gen-provider-plugin.md
index 60dc44bc31..a106f52182 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/image-gen-provider-plugin.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/image-gen-provider-plugin.md
@@ -9,7 +9,7 @@ description: "如何为 Hermes Agent 构建图像生成后端插件"
 图像生成 provider 插件注册一个后端，用于处理所有 `image_generate` 工具调用——DALL·E、gpt-image、Grok、Flux、Imagen、Stable Diffusion、fal、Replicate、本地 ComfyUI 装置，任何后端均可。内置 provider（OpenAI、OpenAI-Codex、xAI）均以插件形式提供。你可以通过在 `plugins/image_gen/<name>/` 目录下放置一个目录来添加新的 provider，或覆盖内置 provider。
 
 :::tip
-图像生成是 Hermes 支持的多种**后端插件**之一。其他插件（各有更专用的 ABC）包括：[Memory Provider 插件](/developer-guide/memory-provider-plugin)、[Context Engine 插件](/developer-guide/context-engine-plugin) 和 [Model Provider 插件](/developer-guide/model-provider-plugin)。通用工具/hook/CLI 插件请参阅 [构建 Hermes 插件](/developer-guide/plugins)。
+图像生成是 Hermes 支持的多种**后端插件**之一。其他插件（各有更专用的 ABC）包括：[Memory Provider 插件](./memory-provider-plugin.md)、[Context Engine 插件](./context-engine-plugin.md) 和 [Model Provider 插件](./model-provider-plugin.md)。通用工具/hook/CLI 插件请参阅 [构建 Hermes 插件](./plugins/index.md)。
 :::
 
 ## 发现机制
@@ -279,10 +279,10 @@ hermes -z "Generate an image of a corgi in a spacesuit"
 my-backend-imggen = "my_backend_imggen_package"
 ```
 
-`my_backend_imggen_package` 必须暴露一个顶层 `register` 函数。完整配置请参阅通用插件指南中的 [通过 pip 分发](/developer-guide/plugins#distribute-via-pip)。
+`my_backend_imggen_package` 必须暴露一个顶层 `register` 函数。完整配置请参阅通用插件指南中的 [通过 pip 分发](./plugins/index.md#distribute-via-pip)。
 
 ## 相关页面
 
-- [图像生成](/user-guide/features/image-generation) — 面向用户的功能文档
-- [插件概览](/user-guide/features/plugins) — 所有插件类型一览
-- [构建 Hermes 插件](/developer-guide/plugins) — 通用工具/hook/斜杠命令指南
\ No newline at end of file
+- [图像生成](../user-guide/features/image-generation.md) — 面向用户的功能文档
+- [插件概览](../user-guide/features/plugins.md) — 所有插件类型一览
+- [构建 Hermes 插件](./plugins/index.md) — 通用工具/hook/斜杠命令指南
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/memory-provider-plugin.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/memory-provider-plugin.md
index 2b681c8114..d95661c6f3 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/memory-provider-plugin.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/memory-provider-plugin.md
@@ -9,7 +9,7 @@ description: "如何为 Hermes Agent 构建 memory provider 插件"
 Memory provider 插件为 Hermes Agent 提供跨会话的持久化知识，超越内置的 MEMORY.md 和 USER.md。本指南介绍如何构建一个 memory provider 插件。
 
 :::tip
-Memory provider 是两种 **provider 插件**类型之一。另一种是 [Context Engine 插件](/developer-guide/context-engine-plugin)，用于替换内置的上下文压缩器。两者遵循相同的模式：单选、配置驱动、通过 `hermes plugins` 管理。
+Memory provider 是两种 **provider 插件**类型之一。另一种是 [Context Engine 插件](./context-engine-plugin.md)，用于替换内置的上下文压缩器。两者遵循相同的模式：单选、配置驱动、通过 `hermes plugins` 管理。
 :::
 
 ## 目录结构
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/model-provider-plugin.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/model-provider-plugin.md
index 3f9829c80a..9940782d6c 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/model-provider-plugin.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/model-provider-plugin.md
@@ -9,7 +9,7 @@ description: "如何为 Hermes Agent 构建模型提供商（推理后端）插
 模型提供商插件声明一个推理后端——兼容 OpenAI 的端点、Anthropic Messages 服务器、Codex 风格的 Responses API，或 Bedrock 原生接口——Hermes 可通过这些后端路由 `AIAgent` 调用。每个内置提供商（OpenRouter、Anthropic、GMI、DeepSeek、Nvidia……）都以此类插件形式提供。第三方可通过在 `$HERMES_HOME/plugins/model-providers/` 下放置一个目录来添加自己的提供商，无需对仓库做任何修改。
 
 :::tip
-模型提供商插件是**提供商插件**的第三种类型。其他两种分别是 [Memory Provider 插件](/developer-guide/memory-provider-plugin)（跨会话知识）和 [Context Engine 插件](/developer-guide/context-engine-plugin)（上下文压缩策略）。三者均遵循相同的"放入目录、声明 profile、无需编辑仓库"模式。
+模型提供商插件是**提供商插件**的第三种类型。其他两种分别是 [Memory Provider 插件](./memory-provider-plugin.md)（跨会话知识）和 [Context Engine 插件](./context-engine-plugin.md)（上下文压缩策略）。三者均遵循相同的"放入目录、声明 profile、无需编辑仓库"模式。
 :::
 
 ## 发现机制
@@ -256,12 +256,12 @@ acme-inference = "acme_hermes_plugin:register"
 
 ……其中 `acme_hermes_plugin:register` 是一个调用 `register_provider(profile)` 的函数。通用 PluginManager 在 `discover_and_load()` 期间会拾取入口点插件。对于 `kind: model-provider` 的 pip 插件，你仍需在 manifest 中声明 kind（或依赖源码文本启发式检测）。
 
-完整的入口点设置请参阅 [构建 Hermes 插件](/developer-guide/plugins#distribute-via-pip)。
+完整的入口点设置请参阅 [构建 Hermes 插件](./plugins/index.md#distribute-via-pip)。
 
 ## 相关页面
 
-- [Provider Runtime](/developer-guide/provider-runtime) — 解析优先级及各层读取 profile 的位置
-- [添加提供商](/developer-guide/adding-providers) — 新推理后端的端到端检查清单（涵盖快速插件路径和完整 CLI/auth 集成）
-- [Memory Provider 插件](/developer-guide/memory-provider-plugin)
-- [Context Engine 插件](/developer-guide/context-engine-plugin)
-- [构建 Hermes 插件](/developer-guide/plugins) — 通用插件编写指南
\ No newline at end of file
+- [Provider Runtime](./provider-runtime.md) — 解析优先级及各层读取 profile 的位置
+- [添加提供商](./adding-providers.md) — 新推理后端的端到端检查清单（涵盖快速插件路径和完整 CLI/auth 集成）
+- [Memory Provider 插件](./memory-provider-plugin.md)
+- [Context Engine 插件](./context-engine-plugin.md)
+- [构建 Hermes 插件](./plugins/index.md) — 通用插件编写指南
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/plugin-llm-access.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/plugin-llm-access.md
index e628617a05..cfb3eefafb 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/plugin-llm-access.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/plugin-llm-access.md
@@ -398,4 +398,4 @@ Plugin id 对于扁平 plugin 是 manifest 中的 `name:` 字段，对于嵌套
   * [`plugin-llm-example`](https://github.com/NousResearch/hermes-example-plugins/tree/main/plugin-llm-example) — 带图像输入的同步结构化提取
   * [`plugin-llm-async-example`](https://github.com/NousResearch/hermes-example-plugins/tree/main/plugin-llm-async-example) — 使用 `asyncio.gather()` 的异步示例
 * 辅助客户端（底层引擎）：参见
-  [Provider 运行时](/developer-guide/provider-runtime)。
+  [Provider 运行时](./provider-runtime.md)。
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/plugins/index.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/plugins/index.md
index 91759dbf55..bacfccdf66 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/plugins/index.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/plugins/index.md
@@ -14,25 +14,25 @@ Hermes 有多种不同的可插拔接口——有些使用 Python `register_*` A
 | 如果你想添加… | 请阅读 |
 |---|---|
 | 自定义工具、钩子、斜杠命令、技能或 CLI 子命令 | **本指南**（通用插件接口） |
-| **LLM / 推理后端**（新提供商） | [模型提供商插件](/developer-guide/model-provider-plugin) |
-| **网关频道**（Discord/Telegram/IRC/Teams 等） | [添加平台适配器](/developer-guide/adding-platform-adapters) |
-| **记忆后端**（Honcho/Mem0/Supermemory 等） | [记忆提供商插件](/developer-guide/memory-provider-plugin) |
-| **上下文压缩引擎** | [上下文引擎插件](/developer-guide/context-engine-plugin) |
-| **图像生成后端** | [图像生成提供商插件](/developer-guide/image-gen-provider-plugin) |
-| **视频生成后端** | [视频生成提供商插件](/developer-guide/video-gen-provider-plugin) |
-| **网页搜索/提取后端** | [网页搜索提供商插件](/developer-guide/web-search-provider-plugin) |
-| **云浏览器后端**（Browserbase 类 CDP 会话提供商） | [浏览器提供商插件](/developer-guide/browser-provider-plugin) |
-| **密钥管理器后端**（保险库 / 密码管理器 / 系统钥匙串） | [密钥源插件](/developer-guide/secret-source-plugin) |
-| **仪表盘 OIDC/认证提供商** | [Web 仪表盘 — 自定义提供商](/user-guide/features/web-dashboard#custom-providers) — `ctx.register_dashboard_auth_provider()` |
-| **TTS 后端**（任意 CLI——Piper、VoxCPM、Kokoro、声音克隆等） | [TTS 自定义命令提供商](/user-guide/features/tts#custom-command-providers)——配置驱动，无需 Python |
-| **STT 后端**（自定义 whisper / ASR CLI） | [语音消息转录](/user-guide/features/tts#voice-message-transcription-stt)——将 `HERMES_LOCAL_STT_COMMAND` 设置为 shell 模板 |
-| **通过 MCP 接入外部工具**（文件系统、GitHub、Linear、任意 MCP 服务器） | [MCP](/user-guide/features/mcp)——在 `config.yaml` 中声明 `mcp_servers.<name>` |
-| **网关事件钩子**（在启动、会话事件、命令时触发） | [事件钩子](/user-guide/features/hooks#gateway-event-hooks)——将 `HOOK.yaml` + `handler.py` 放入 `~/.hermes/hooks/<name>/` |
-| **Shell 钩子**（在事件发生时运行 shell 命令） | [Shell 钩子](/user-guide/features/hooks#shell-hooks)——在 `config.yaml` 的 `hooks:` 下声明 |
-| **额外技能来源**（自定义 GitHub 仓库、私有技能索引） | [技能](/user-guide/features/skills)——`hermes skills tap add <repo>` · [发布 tap](/user-guide/features/skills#publishing-a-custom-skill-tap) |
-| 一流的**核心**推理提供商（非插件） | [添加提供商](/developer-guide/adding-providers) |
+| **LLM / 推理后端**（新提供商） | [模型提供商插件](../model-provider-plugin.md) |
+| **网关频道**（Discord/Telegram/IRC/Teams 等） | [添加平台适配器](../adding-platform-adapters.md) |
+| **记忆后端**（Honcho/Mem0/Supermemory 等） | [记忆提供商插件](../memory-provider-plugin.md) |
+| **上下文压缩引擎** | [上下文引擎插件](../context-engine-plugin.md) |
+| **图像生成后端** | [图像生成提供商插件](../image-gen-provider-plugin.md) |
+| **视频生成后端** | [视频生成提供商插件](../video-gen-provider-plugin.md) |
+| **网页搜索/提取后端** | [网页搜索提供商插件](../web-search-provider-plugin.md) |
+| **云浏览器后端**（Browserbase 类 CDP 会话提供商） | [浏览器提供商插件](../browser-provider-plugin.md) |
+| **密钥管理器后端**（保险库 / 密码管理器 / 系统钥匙串） | [密钥源插件](../secret-source-plugin.md) |
+| **仪表盘 OIDC/认证提供商** | [Web 仪表盘 — 自定义提供商](../../user-guide/features/web-dashboard.md#custom-providers) — `ctx.register_dashboard_auth_provider()` |
+| **TTS 后端**（任意 CLI——Piper、VoxCPM、Kokoro、声音克隆等） | [TTS 自定义命令提供商](../../user-guide/features/tts.md#custom-command-providers)——配置驱动，无需 Python |
+| **STT 后端**（自定义 whisper / ASR CLI） | [语音消息转录](../../user-guide/features/tts.md#voice-message-transcription-stt)——将 `HERMES_LOCAL_STT_COMMAND` 设置为 shell 模板 |
+| **通过 MCP 接入外部工具**（文件系统、GitHub、Linear、任意 MCP 服务器） | [MCP](../../user-guide/features/mcp.md)——在 `config.yaml` 中声明 `mcp_servers.<name>` |
+| **网关事件钩子**（在启动、会话事件、命令时触发） | [事件钩子](../../user-guide/features/hooks.md#gateway-event-hooks)——将 `HOOK.yaml` + `handler.py` 放入 `~/.hermes/hooks/<name>/` |
+| **Shell 钩子**（在事件发生时运行 shell 命令） | [Shell 钩子](../../user-guide/features/hooks.md#shell-hooks)——在 `config.yaml` 的 `hooks:` 下声明 |
+| **额外技能来源**（自定义 GitHub 仓库、私有技能索引） | [技能](../../user-guide/features/skills.md)——`hermes skills tap add <repo>` · [发布 tap](../../user-guide/features/skills.md#publishing-a-custom-skill-tap) |
+| 一流的**核心**推理提供商（非插件） | [添加提供商](../adding-providers.md) |
 
-查看完整的[可插拔接口表](/user-guide/features/plugins#pluggable-interfaces--where-to-go-for-each)，获取每种扩展接口的汇总视图，包括配置驱动（TTS、STT、MCP、shell 钩子）和放入目录（网关钩子）两种方式。
+查看完整的[可插拔接口表](../../user-guide/features/plugins.md#pluggable-interfaces--where-to-go-for-each)，获取每种扩展接口的汇总视图，包括配置驱动（TTS、STT、MCP、shell 钩子）和放入目录（网关钩子）两种方式。
 :::
 
 ## 你将构建什么
@@ -527,18 +527,18 @@ def register(ctx):
 
 ### 钩子参考
 
-每个钩子的完整文档见**[事件钩子参考](/user-guide/features/hooks#plugin-hooks)**——回调签名、参数表、触发时机和示例。以下是摘要：
+每个钩子的完整文档见**[事件钩子参考](../../user-guide/features/hooks.md#plugin-hooks)**——回调签名、参数表、触发时机和示例。以下是摘要：
 
 | 钩子 | 触发时机 | 回调签名 | 返回值 |
 |------|-----------|-------------------|---------|
-| [`pre_tool_call`](/user-guide/features/hooks#pre_tool_call) | 任意工具执行前 | `tool_name: str, args: dict, task_id: str` | 忽略 |
-| [`post_tool_call`](/user-guide/features/hooks#post_tool_call) | 任意工具返回后 | `tool_name: str, args: dict, result: str, task_id: str, duration_ms: int` | 忽略 |
-| [`pre_llm_call`](/user-guide/features/hooks#pre_llm_call) | 每轮一次，工具调用循环前 | `session_id: str, user_message: str, conversation_history: list, is_first_turn: bool, model: str, platform: str` | [上下文注入](#pre_llm_call-context-injection) |
-| [`post_llm_call`](/user-guide/features/hooks#post_llm_call) | 每轮一次，工具调用循环后（仅成功轮次） | `session_id: str, user_message: str, assistant_response: str, conversation_history: list, model: str, platform: str` | 忽略 |
-| [`on_session_start`](/user-guide/features/hooks#on_session_start) | 新会话创建（仅第一轮） | `session_id: str, model: str, platform: str` | 忽略 |
-| [`on_session_end`](/user-guide/features/hooks#on_session_end) | 每次 `run_conversation` 调用结束 + CLI 退出 | `session_id: str, completed: bool, interrupted: bool, model: str, platform: str` | 忽略 |
-| [`on_session_finalize`](/user-guide/features/hooks#on_session_finalize) | CLI/网关销毁活跃会话 | `session_id: str \| None, platform: str` | 忽略 |
-| [`on_session_reset`](/user-guide/features/hooks#on_session_reset) | 网关切换新会话键（`/new`、`/reset`） | `session_id: str, platform: str` | 忽略 |
+| [`pre_tool_call`](../../user-guide/features/hooks.md#pre_tool_call) | 任意工具执行前 | `tool_name: str, args: dict, task_id: str` | 忽略 |
+| [`post_tool_call`](../../user-guide/features/hooks.md#post_tool_call) | 任意工具返回后 | `tool_name: str, args: dict, result: str, task_id: str, duration_ms: int` | 忽略 |
+| [`pre_llm_call`](../../user-guide/features/hooks.md#pre_llm_call) | 每轮一次，工具调用循环前 | `session_id: str, user_message: str, conversation_history: list, is_first_turn: bool, model: str, platform: str` | [上下文注入](#pre_llm_call-context-injection) |
+| [`post_llm_call`](../../user-guide/features/hooks.md#post_llm_call) | 每轮一次，工具调用循环后（仅成功轮次） | `session_id: str, user_message: str, assistant_response: str, conversation_history: list, model: str, platform: str` | 忽略 |
+| [`on_session_start`](../../user-guide/features/hooks.md#on_session_start) | 新会话创建（仅第一轮） | `session_id: str, model: str, platform: str` | 忽略 |
+| [`on_session_end`](../../user-guide/features/hooks.md#on_session_end) | 每次 `run_conversation` 调用结束 + CLI 退出 | `session_id: str, completed: bool, interrupted: bool, model: str, platform: str` | 忽略 |
+| [`on_session_finalize`](../../user-guide/features/hooks.md#on_session_finalize) | CLI/网关销毁活跃会话 | `session_id: str \| None, platform: str` | 忽略 |
+| [`on_session_reset`](../../user-guide/features/hooks.md#on_session_reset) | 网关切换新会话键（`/new`、`/reset`） | `session_id: str, platform: str` | 忽略 |
 
 大多数钩子是即发即忘的观察者——其返回值被忽略。例外是 `pre_llm_call`，它可以向对话中注入上下文。
 
@@ -675,7 +675,7 @@ def register(ctx):
 
 注册后，用户可以运行 `hermes my-plugin status`、`hermes my-plugin config` 等命令。
 
-**记忆提供商插件**使用基于约定的方式：在插件的 `cli.py` 文件中添加 `register_cli(subparser)` 函数。记忆插件发现系统会自动找到它——无需调用 `ctx.register_cli_command()`。详见[记忆提供商插件指南](/developer-guide/memory-provider-plugin#adding-cli-commands)。
+**记忆提供商插件**使用基于约定的方式：在插件的 `cli.py` 文件中添加 `register_cli(subparser)` 函数。记忆插件发现系统会自动找到它——无需调用 `ctx.register_cli_command()`。详见[记忆提供商插件指南](../memory-provider-plugin.md#adding-cli-commands)。
 
 **活跃提供商限制：** 记忆插件 CLI 命令仅在其提供商是配置中活跃的 `memory.provider` 时才会出现。如果用户尚未设置你的提供商，你的 CLI 命令不会出现在帮助输出中。
 
@@ -808,7 +808,7 @@ description: Acme Inference — OpenAI-compatible direct API
 
 在任何调用 `get_provider_profile()` 或 `list_providers()` 的地方首次使用时懒加载发现——`auth.py`、`config.py`、`doctor.py`、`models.py`、`runtime_provider.py` 和 chat_completions 传输层会自动连接。用户插件按名称覆盖内置插件。
 
-**完整指南：** [模型提供商插件](/developer-guide/model-provider-plugin)——字段参考、可覆盖钩子（`prepare_messages`、`build_extra_body`、`build_api_kwargs_extras`、`fetch_models`）、api_mode 选择、认证类型、测试。
+**完整指南：** [模型提供商插件](../model-provider-plugin.md)——字段参考、可覆盖钩子（`prepare_messages`、`build_extra_body`、`build_api_kwargs_extras`、`fetch_models`）、api_mode 选择、认证类型、测试。
 
 ### 平台插件——添加网关频道
 
@@ -868,7 +868,7 @@ optional_env:
     password: false
 ```
 
-**完整指南：** [添加平台适配器](/developer-guide/adding-platform-adapters)——完整的 `BasePlatformAdapter` 约定、消息路由、认证限制、设置向导集成。参考 `plugins/platforms/irc/` 获取仅使用标准库的可用示例。
+**完整指南：** [添加平台适配器](../adding-platform-adapters.md)——完整的 `BasePlatformAdapter` 约定、消息路由、认证限制、设置向导集成。参考 `plugins/platforms/irc/` 获取仅使用标准库的可用示例。
 
 ### 记忆提供商插件——添加跨会话知识后端
 
@@ -902,7 +902,7 @@ def register(ctx):
 
 记忆提供商是单选的——同一时间只有一个处于活跃状态，通过 `config.yaml` 中的 `memory.provider` 选择。
 
-**完整指南：** [记忆提供商插件](/developer-guide/memory-provider-plugin)——完整的 `MemoryProvider` ABC、线程约定、配置文件隔离、通过 `cli.py` 注册 CLI 命令。
+**完整指南：** [记忆提供商插件](../memory-provider-plugin.md)——完整的 `MemoryProvider` ABC、线程约定、配置文件隔离、通过 `cli.py` 注册 CLI 命令。
 
 ### 上下文引擎插件——替换上下文压缩器
 
@@ -924,7 +924,7 @@ def register(ctx):
 
 上下文引擎是单选的——通过 `config.yaml` 中的 `context.engine` 选择。
 
-**完整指南：** [上下文引擎插件](/developer-guide/context-engine-plugin)。
+**完整指南：** [上下文引擎插件](../context-engine-plugin.md)。
 
 ### 图像生成后端
 
@@ -954,13 +954,13 @@ version: 1.0.0
 description: Custom image generation backend
 ```
 
-**完整指南：** [图像生成提供商插件](/developer-guide/image-gen-provider-plugin)——完整的 `ImageGenProvider` ABC、`list_models()` / `get_setup_schema()` 元数据、`success_response()`/`error_response()` 辅助函数、base64 与 URL 输出、用户覆盖、pip 分发。
+**完整指南：** [图像生成提供商插件](../image-gen-provider-plugin.md)——完整的 `ImageGenProvider` ABC、`list_models()` / `get_setup_schema()` 元数据、`success_response()`/`error_response()` 辅助函数、base64 与 URL 输出、用户覆盖、pip 分发。
 
 **参考示例：** `plugins/image_gen/openai/`（DALL-E / GPT-Image via OpenAI SDK）、`plugins/image_gen/openai-codex/`、`plugins/image_gen/xai/`（Grok 图像生成）。
 
 ## 非 Python 扩展接口
 
-Hermes 也接受完全不是 Python 插件的扩展。这些在[可插拔接口表](/user-guide/features/plugins#pluggable-interfaces--where-to-go-for-each)中有所展示；以下各节简要介绍每种编写方式。
+Hermes 也接受完全不是 Python 插件的扩展。这些在[可插拔接口表](../../user-guide/features/plugins.md#pluggable-interfaces--where-to-go-for-each)中有所展示；以下各节简要介绍每种编写方式。
 
 ### MCP 服务器——注册外部工具
 
@@ -979,7 +979,7 @@ mcp_servers:
       type: "oauth"
 ```
 
-Hermes 在启动时连接到每个服务器，列出其工具，并与内置工具一起注册。LLM 看到它们的方式与其他工具完全相同。**完整指南：** [MCP](/user-guide/features/mcp)。
+Hermes 在启动时连接到每个服务器，列出其工具，并与内置工具一起注册。LLM 看到它们的方式与其他工具完全相同。**完整指南：** [MCP](../../user-guide/features/mcp.md)。
 
 ### 网关事件钩子——在生命周期事件时触发
 
@@ -1003,7 +1003,7 @@ async def handle(event_type: str, context: dict) -> None:
 
 事件包括 `gateway:startup`、`session:start`、`session:end`、`session:reset`、`agent:start`、`agent:step`、`agent:end` 以及通配符 `command:*`。钩子中的错误会被捕获并记录日志——它们不会阻塞主流程。
 
-**完整指南：** [网关事件钩子](/user-guide/features/hooks#gateway-event-hooks)。
+**完整指南：** [网关事件钩子](../../user-guide/features/hooks.md#gateway-event-hooks)。
 
 ### Shell 钩子——在工具调用时运行 shell 命令
 
@@ -1019,7 +1019,7 @@ hooks:
 
 支持与 Python 插件钩子相同的所有事件（`pre_tool_call`、`post_tool_call`、`pre_llm_call`、`post_llm_call`、`on_session_start`、`on_session_end`、`pre_gateway_dispatch`），以及用于 `pre_tool_call` 阻断决策的结构化 JSON 输出。
 
-**完整指南：** [Shell 钩子](/user-guide/features/hooks#shell-hooks)。
+**完整指南：** [Shell 钩子](../../user-guide/features/hooks.md#shell-hooks)。
 
 ### 技能来源——添加自定义技能注册表
 
@@ -1033,7 +1033,7 @@ hermes skills install myorg/skills-repo/my-workflow
 
 发布你自己的 tap 只需一个包含 `skills/<skill-name>/SKILL.md` 目录的 GitHub 仓库——无需服务器或注册表注册。
 
-**完整指南：** [技能中心](/user-guide/features/skills#skills-hub) · [发布自定义 tap](/user-guide/features/skills#publishing-a-custom-skill-tap)（仓库结构、最小示例、非默认路径、信任级别）。
+**完整指南：** [技能中心](../../user-guide/features/skills.md#skills-hub) · [发布自定义 tap](../../user-guide/features/skills.md#publishing-a-custom-skill-tap)（仓库结构、最小示例、非默认路径、信任级别）。
 
 ### 通过命令模板接入 TTS / STT
 
@@ -1052,7 +1052,7 @@ tts:
 
 对于 STT，将 `HERMES_LOCAL_STT_COMMAND` 指向一个 shell 模板。支持的占位符：`{input_path}`、`{output_path}`、`{format}`、`{voice}`、`{model}`、`{speed}`（TTS）；`{input_path}`、`{output_dir}`、`{language}`、`{model}`（STT）。任何与路径交互的 CLI 都自动成为插件。
 
-**完整指南：** [TTS 自定义命令提供商](/user-guide/features/tts#custom-command-providers) · [STT](/user-guide/features/tts#voice-message-transcription-stt)。
+**完整指南：** [TTS 自定义命令提供商](../../user-guide/features/tts.md#custom-command-providers) · [STT](../../user-guide/features/tts.md#voice-message-transcription-stt)。
 
 ## 通过 pip 分发
 
@@ -1104,7 +1104,7 @@ services.hermes-agent.extraPlugins = [
 ];
 ```
 
-完整文档（包括 overlay 用法和冲突检查）见 [Nix 设置指南](/getting-started/nix-setup#plugins)。
+完整文档（包括 overlay 用法和冲突检查）见 [Nix 设置指南](../../getting-started/nix-setup.md#plugins)。
 
 ## 常见错误
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/video-gen-provider-plugin.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/video-gen-provider-plugin.md
index 49c07c3b97..4a602e2814 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/video-gen-provider-plugin.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/video-gen-provider-plugin.md
@@ -9,7 +9,7 @@ description: "如何为 Hermes Agent 构建视频生成后端插件"
 视频生成 provider 插件注册一个后端，用于处理所有 `video_generate` 工具调用。内置 provider（xAI、FAL）以插件形式提供。将目录放入 `plugins/video_gen/<name>/` 即可添加新 provider 或覆盖内置 provider。
 
 :::tip
-视频生成与[图像生成 Provider 插件](/developer-guide/image-gen-provider-plugin)几乎一一对应——如果你已构建过图像生成后端，对其结构应已了然于胸。主要区别在于：`capabilities()` 方法用于声明模态（modality）/宽高比/时长，以及路由约定（传入 `image_url` 则使用图生视频，省略则使用文生视频——provider 在内部选择正确的端点）。
+视频生成与[图像生成 Provider 插件](./image-gen-provider-plugin.md)几乎一一对应——如果你已构建过图像生成后端，对其结构应已了然于胸。主要区别在于：`capabilities()` 方法用于声明模态（modality）/宽高比/时长，以及路由约定（传入 `image_url` 则使用图生视频，省略则使用文生视频——provider 在内部选择正确的端点）。
 :::
 
 ## 统一接口（一个工具，两种模态）
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/web-search-provider-plugin.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/web-search-provider-plugin.md
index 6d69c569f8..af0c527a0d 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/web-search-provider-plugin.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/web-search-provider-plugin.md
@@ -9,7 +9,7 @@ description: "如何为 Hermes Agent 构建网页搜索/提取/爬取后端插
 网页搜索提供商插件注册一个后端，用于处理 `web_search`、`web_extract` 以及（可选的）深度爬取工具调用。内置提供商——Firecrawl、SearXNG、Tavily、Exa、Parallel、Brave Search（免费层）和 DDGS——均以插件形式存放于 `plugins/web/<name>/` 目录下。你可以在该目录旁新建一个目录来添加新提供商，或覆盖已有的内置提供商。
 
 :::tip
-网页搜索是 Hermes 支持的多种**后端插件**之一。其他插件（各有其 ABC）包括：[图像生成提供商插件](/developer-guide/image-gen-provider-plugin)、[视频生成提供商插件](/developer-guide/video-gen-provider-plugin)、[记忆提供商插件](/developer-guide/memory-provider-plugin)、[上下文引擎插件](/developer-guide/context-engine-plugin)和[模型提供商插件](/developer-guide/model-provider-plugin)。通用工具/hook/CLI 插件请参阅[构建 Hermes 插件](/developer-guide/plugins)。
+网页搜索是 Hermes 支持的多种**后端插件**之一。其他插件（各有其 ABC）包括：[图像生成提供商插件](./image-gen-provider-plugin.md)、[视频生成提供商插件](./video-gen-provider-plugin.md)、[记忆提供商插件](./memory-provider-plugin.md)、[上下文引擎插件](./context-engine-plugin.md)和[模型提供商插件](./model-provider-plugin.md)。通用工具/hook/CLI 插件请参阅[构建 Hermes 插件](./plugins/index.md)。
 :::
 
 ## 发现机制
@@ -141,7 +141,7 @@ requires_env:
 |---|---|
 | `kind: backend` | 将插件路由至后端加载路径 |
 | `provides_web_providers` | 该插件注册的提供商 `name` 列表——在 `register()` 运行之前，加载器即可通过此字段在 `hermes tools` 中公示插件 |
-| `requires_env` | 在 `hermes plugins install` 期间进行交互式凭据提示（富格式说明参见[构建 Hermes 插件](/developer-guide/plugins#gate-on-environment-variables)） |
+| `requires_env` | 在 `hermes plugins install` 期间进行交互式凭据提示（富格式说明参见[构建 Hermes 插件](./plugins/index.md#gate-on-environment-variables)） |
 
 ## ABC 参考
 
@@ -233,7 +233,7 @@ web:
 
 ## 懒加载可选依赖
 
-如果你的提供商封装了第三方 SDK（如 DDGS 封装了 `ddgs` 包），请勿在模块顶层 `import`。在 `is_available()` 或 `search()` 内部使用 `tools.lazy_deps.ensure(...)` ——Hermes 将在首次使用时安装该包，并受 `security.allow_lazy_installs` 控制。安全模型详见[构建 Hermes 插件 → 懒加载](/developer-guide/plugins#lazy-install-optional-python-dependencies)。
+如果你的提供商封装了第三方 SDK（如 DDGS 封装了 `ddgs` 包），请勿在模块顶层 `import`。在 `is_available()` 或 `search()` 内部使用 `tools.lazy_deps.ensure(...)` ——Hermes 将在首次使用时安装该包，并受 `security.allow_lazy_installs` 控制。安全模型详见[构建 Hermes 插件 → 懒加载](./plugins/index.md#lazy-install-optional-python-dependencies)。
 
 ## 参考实现
 
@@ -251,10 +251,10 @@ web:
 my-backend-web = "my_backend_web_package"
 ```
 
-`my_backend_web_package` 必须暴露顶层 `register` 函数。完整配置说明参见通用插件指南中的[通过 pip 分发](/developer-guide/plugins#distribute-via-pip)。
+`my_backend_web_package` 必须暴露顶层 `register` 函数。完整配置说明参见通用插件指南中的[通过 pip 分发](./plugins/index.md#distribute-via-pip)。
 
 ## 相关页面
 
-- [网页搜索](/user-guide/features/web-search) — 面向用户的功能文档及各后端配置说明
-- [插件概览](/user-guide/features/plugins) — 所有插件类型一览
-- [构建 Hermes 插件](/developer-guide/plugins) — 通用工具/hook/斜杠命令指南
\ No newline at end of file
+- [网页搜索](../user-guide/features/web-search.md) — 面向用户的功能文档及各后端配置说明
+- [插件概览](../user-guide/features/plugins.md) — 所有插件类型一览
+- [构建 Hermes 插件](./plugins/index.md) — 通用工具/hook/斜杠命令指南
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/installation.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/installation.md
index 87804be07c..939592d4ac 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/installation.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/installation.md
@@ -110,7 +110,7 @@ hermes setup          # 或运行完整的设置向导一次性配置所有内
 ```
 
 :::tip 最快路径：Nous Portal
-一个订阅涵盖 300+ 个模型以及 [Tool Gateway](/user-guide/features/tool-gateway)（网络搜索、图像生成、TTS、云端浏览器）。无需逐一管理各工具的密钥：
+一个订阅涵盖 300+ 个模型以及 [Tool Gateway](../user-guide/features/tool-gateway.md)（网络搜索、图像生成、TTS、云端浏览器）。无需逐一管理各工具的密钥：
 
 ```bash
 hermes setup --portal
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/learning-path.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/learning-path.md
index fe6bb448ff..9bc175464f 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/learning-path.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/learning-path.md
@@ -9,7 +9,7 @@ description: '根据您的经验水平和目标，选择适合您的 Hermes Agen
 Hermes Agent 功能丰富——CLI 助手、Telegram/Discord 机器人、任务自动化、强化学习训练等。本页帮助您根据自身经验水平和目标，确定从哪里开始、阅读哪些内容。
 
 :::tip 从这里开始
-如果您尚未安装 Hermes Agent，请先阅读[安装指南](/getting-started/installation)，然后完成[快速入门](/getting-started/quickstart)。以下内容均假设您已完成安装。
+如果您尚未安装 Hermes Agent，请先阅读[安装指南](./installation.md)，然后完成[快速入门](./quickstart.md)。以下内容均假设您已完成安装。
 :::
 
 ## 如何使用本页
@@ -22,9 +22,9 @@ Hermes Agent 功能丰富——CLI 助手、Telegram/Discord 机器人、任务
 
 | 水平 | 目标 | 推荐阅读 | 预计时间 |
 |---|---|---|---|
-| **初级** | 快速上手，进行基本对话，使用内置工具 | [安装](/getting-started/installation) → [快速入门](/getting-started/quickstart) → [CLI 用法](/user-guide/cli) → [配置](/user-guide/configuration) | 约 1 小时 |
-| **中级** | 搭建消息机器人，使用记忆、cron 任务、技能等高级功能 | [会话](/user-guide/sessions) → [消息](/user-guide/messaging) → [工具](/user-guide/features/tools) → [技能](/user-guide/features/skills) → [记忆](/user-guide/features/memory) → [Cron](/user-guide/features/cron) | 约 2–3 小时 |
-| **高级** | 构建自定义工具、创建技能、使用强化学习训练模型、参与项目贡献 | [架构](/developer-guide/architecture) → [添加工具](/developer-guide/adding-tools) → [创建技能](/developer-guide/creating-skills) → [强化学习训练](/user-guide/features/rl-training) → [贡献指南](/developer-guide/contributing) | 约 4–6 小时 |
+| **初级** | 快速上手，进行基本对话，使用内置工具 | [安装](./installation.md) → [快速入门](./quickstart.md) → [CLI 用法](../user-guide/cli.md) → [配置](../user-guide/configuration.md) | 约 1 小时 |
+| **中级** | 搭建消息机器人，使用记忆、cron 任务、技能等高级功能 | [会话](../user-guide/sessions.md) → [消息](../user-guide/messaging/index.md) → [工具](../user-guide/features/tools.md) → [技能](../user-guide/features/skills.md) → [记忆](../user-guide/features/memory.md) → [Cron](../user-guide/features/cron.md) | 约 2–3 小时 |
+| **高级** | 构建自定义工具、创建技能、使用强化学习训练模型、参与项目贡献 | [架构](../developer-guide/architecture.md) → [添加工具](../developer-guide/adding-tools.md) → [创建技能](../developer-guide/creating-skills.md) → [贡献指南](../developer-guide/contributing.md) | 约 4–6 小时 |
 
 ## 按使用场景
 
@@ -34,12 +34,12 @@ Hermes Agent 功能丰富——CLI 助手、Telegram/Discord 机器人、任务
 
 将 Hermes Agent 用作交互式终端助手，用于编写、审查和运行代码。
 
-1. [安装](/getting-started/installation)
-2. [快速入门](/getting-started/quickstart)
-3. [CLI 用法](/user-guide/cli)
-4. [代码执行](/user-guide/features/code-execution)
-5. [上下文文件](/user-guide/features/context-files)
-6. [技巧与窍门](/guides/tips)
+1. [安装](./installation.md)
+2. [快速入门](./quickstart.md)
+3. [CLI 用法](../user-guide/cli.md)
+4. [代码执行](../user-guide/features/code-execution.md)
+5. [上下文文件](../user-guide/features/context-files.md)
+6. [技巧与窍门](../guides/tips.md)
 
 :::tip
 通过上下文文件将文件直接传入对话。Hermes Agent 可以读取、编辑并运行您项目中的代码。
@@ -49,28 +49,28 @@ Hermes Agent 功能丰富——CLI 助手、Telegram/Discord 机器人、任务
 
 将 Hermes Agent 部署为您常用消息平台上的机器人。
 
-1. [安装](/getting-started/installation)
-2. [配置](/user-guide/configuration)
-3. [消息概览](/user-guide/messaging)
-4. [Telegram 配置](/user-guide/messaging/telegram)
-5. [Discord 配置](/user-guide/messaging/discord)
-6. [语音模式](/user-guide/features/voice-mode)
-7. [在 Hermes 中使用语音模式](/guides/use-voice-mode-with-hermes)
-8. [安全](/user-guide/security)
+1. [安装](./installation.md)
+2. [配置](../user-guide/configuration.md)
+3. [消息概览](../user-guide/messaging/index.md)
+4. [Telegram 配置](../user-guide/messaging/telegram.md)
+5. [Discord 配置](../user-guide/messaging/discord.md)
+6. [语音模式](../user-guide/features/voice-mode.md)
+7. [在 Hermes 中使用语音模式](../guides/use-voice-mode-with-hermes.md)
+8. [安全](../user-guide/security.md)
 
 完整项目示例请参阅：
-- [每日简报机器人](/guides/daily-briefing-bot)
-- [团队 Telegram 助手](/guides/team-telegram-assistant)
+- [每日简报机器人](../guides/daily-briefing-bot.md)
+- [团队 Telegram 助手](../guides/team-telegram-assistant.md)
 
 ### "我想自动化任务"
 
 调度周期性任务、运行批处理作业，或将多个 agent 动作串联起来。
 
-1. [快速入门](/getting-started/quickstart)
-2. [Cron 调度](/user-guide/features/cron)
-3. [批处理](/user-guide/features/batch-processing)
-4. [委派](/user-guide/features/delegation)
-5. [Hooks](/user-guide/features/hooks)
+1. [快速入门](./quickstart.md)
+2. [Cron 调度](../user-guide/features/cron.md)
+3. [批处理](../user-guide/features/batch-processing.md)
+4. [委派](../user-guide/features/delegation.md)
+5. [Hooks](../user-guide/features/hooks.md)
 
 :::tip
 Cron 任务让 Hermes Agent 按计划执行任务——每日摘要、定期检查、自动报告——无需您在场。
@@ -80,28 +80,28 @@ Cron 任务让 Hermes Agent 按计划执行任务——每日摘要、定期检
 
 通过自定义工具和可复用技能包扩展 Hermes Agent。
 
-1. [插件](/user-guide/features/plugins)
-2. [构建 Hermes 插件](/developer-guide/plugins)
-3. [工具概览](/user-guide/features/tools)
-4. [技能概览](/user-guide/features/skills)
-5. [MCP（模型上下文协议）](/user-guide/features/mcp)
-6. [架构](/developer-guide/architecture)
-7. [添加工具](/developer-guide/adding-tools)
-8. [创建技能](/developer-guide/creating-skills)
+1. [插件](../user-guide/features/plugins.md)
+2. [构建 Hermes 插件](../developer-guide/plugins/index.md)
+3. [工具概览](../user-guide/features/tools.md)
+4. [技能概览](../user-guide/features/skills.md)
+5. [MCP（模型上下文协议）](../user-guide/features/mcp.md)
+6. [架构](../developer-guide/architecture.md)
+7. [添加工具](../developer-guide/adding-tools.md)
+8. [创建技能](../developer-guide/creating-skills.md)
 
 :::tip
-对于大多数自定义工具的创建，建议从插件开始。[添加工具](/developer-guide/adding-tools)页面面向 Hermes 核心内置开发，而非常规用户/自定义工具路径。
+对于大多数自定义工具的创建，建议从插件开始。[添加工具](../developer-guide/adding-tools.md)页面面向 Hermes 核心内置开发，而非常规用户/自定义工具路径。
 :::
 
 ### "我想训练模型"
 
 使用强化学习（RL）通过 Hermes Agent 内置的 RL 训练流水线对模型行为进行微调。
 
-1. [快速入门](/getting-started/quickstart)
-2. [配置](/user-guide/configuration)
-3. [强化学习训练](/user-guide/features/rl-training)
-4. [Provider 路由](/user-guide/features/provider-routing)
-5. [架构](/developer-guide/architecture)
+1. [快速入门](./quickstart.md)
+2. [配置](../user-guide/configuration.md)
+3. [Atropos 强化学习环境](https://github.com/NousResearch/atropos)（外部）
+4. [Provider 路由](../user-guide/features/provider-routing.md)
+5. [架构](../developer-guide/architecture.md)
 
 :::tip
 强化学习训练在您已了解 Hermes Agent 如何处理对话和工具调用的基础上效果最佳。如果您是新手，请先完成初级路径。
@@ -111,12 +111,12 @@ Cron 任务让 Hermes Agent 按计划执行任务——每日摘要、定期检
 
 以编程方式将 Hermes Agent 集成到您自己的 Python 应用中。
 
-1. [安装](/getting-started/installation)
-2. [快速入门](/getting-started/quickstart)
-3. [Python 库指南](/guides/python-library)
-4. [架构](/developer-guide/architecture)
-5. [工具](/user-guide/features/tools)
-6. [会话](/user-guide/sessions)
+1. [安装](./installation.md)
+2. [快速入门](./quickstart.md)
+3. [Python 库指南](../guides/python-library.md)
+4. [架构](../developer-guide/architecture.md)
+5. [工具](../user-guide/features/tools.md)
+6. [会话](../user-guide/sessions.md)
 
 ## 主要功能一览
 
@@ -124,30 +124,30 @@ Cron 任务让 Hermes Agent 按计划执行任务——每日摘要、定期检
 
 | 功能 | 说明 | 链接 |
 |---|---|---|
-| **工具** | Agent 可调用的内置工具（文件 I/O、搜索、Shell 等） | [工具](/user-guide/features/tools) |
-| **技能** | 可安装的插件包，用于添加新能力 | [技能](/user-guide/features/skills) |
-| **记忆** | 跨会话的持久化记忆 | [记忆](/user-guide/features/memory) |
-| **上下文文件** | 将文件和目录传入对话 | [上下文文件](/user-guide/features/context-files) |
-| **MCP** | 通过模型上下文协议连接外部工具服务器 | [MCP](/user-guide/features/mcp) |
-| **Cron** | 调度周期性 agent 任务 | [Cron](/user-guide/features/cron) |
-| **委派** | 生成子 agent 以并行处理工作 | [委派](/user-guide/features/delegation) |
-| **代码执行** | 运行以编程方式调用 Hermes 工具的 Python 脚本 | [代码执行](/user-guide/features/code-execution) |
-| **浏览器** | 网页浏览与抓取 | [浏览器](/user-guide/features/browser) |
-| **Hooks** | 事件驱动的回调与中间件 | [Hooks](/user-guide/features/hooks) |
-| **批处理** | 批量处理多个输入 | [批处理](/user-guide/features/batch-processing) |
-| **强化学习训练** | 使用强化学习微调模型 | [强化学习训练](/user-guide/features/rl-training) |
-| **Provider 路由** | 在多个 LLM provider 之间路由请求 | [Provider 路由](/user-guide/features/provider-routing) |
+| **工具** | Agent 可调用的内置工具（文件 I/O、搜索、Shell 等） | [工具](../user-guide/features/tools.md) |
+| **技能** | 可安装的插件包，用于添加新能力 | [技能](../user-guide/features/skills.md) |
+| **记忆** | 跨会话的持久化记忆 | [记忆](../user-guide/features/memory.md) |
+| **上下文文件** | 将文件和目录传入对话 | [上下文文件](../user-guide/features/context-files.md) |
+| **MCP** | 通过模型上下文协议连接外部工具服务器 | [MCP](../user-guide/features/mcp.md) |
+| **Cron** | 调度周期性 agent 任务 | [Cron](../user-guide/features/cron.md) |
+| **委派** | 生成子 agent 以并行处理工作 | [委派](../user-guide/features/delegation.md) |
+| **代码执行** | 运行以编程方式调用 Hermes 工具的 Python 脚本 | [代码执行](../user-guide/features/code-execution.md) |
+| **浏览器** | 网页浏览与抓取 | [浏览器](../user-guide/features/browser.md) |
+| **Hooks** | 事件驱动的回调与中间件 | [Hooks](../user-guide/features/hooks.md) |
+| **批处理** | 批量处理多个输入 | [批处理](../user-guide/features/batch-processing.md) |
+| **强化学习训练** | 使用强化学习微调模型 | [Atropos](https://github.com/NousResearch/atropos)（外部） |
+| **Provider 路由** | 在多个 LLM provider 之间路由请求 | [Provider 路由](../user-guide/features/provider-routing.md) |
 
 ## 下一步阅读
 
 根据您当前所处阶段：
 
-- **刚完成安装？** → 前往[快速入门](/getting-started/quickstart)，运行您的第一次对话。
-- **完成了快速入门？** → 阅读 [CLI 用法](/user-guide/cli)和[配置](/user-guide/configuration)，自定义您的设置。
-- **已熟悉基础？** → 探索[工具](/user-guide/features/tools)、[技能](/user-guide/features/skills)和[记忆](/user-guide/features/memory)，释放 agent 的全部能力。
-- **为团队部署？** → 阅读[安全](/user-guide/security)和[会话](/user-guide/sessions)，了解访问控制与对话管理。
-- **准备好开发了？** → 进入[开发者指南](/developer-guide/architecture)，了解内部机制并开始贡献。
-- **想要实际示例？** → 查看[指南](/guides/tips)部分，获取真实项目案例和技巧。
+- **刚完成安装？** → 前往[快速入门](./quickstart.md)，运行您的第一次对话。
+- **完成了快速入门？** → 阅读 [CLI 用法](../user-guide/cli.md)和[配置](../user-guide/configuration.md)，自定义您的设置。
+- **已熟悉基础？** → 探索[工具](../user-guide/features/tools.md)、[技能](../user-guide/features/skills.md)和[记忆](../user-guide/features/memory.md)，释放 agent 的全部能力。
+- **为团队部署？** → 阅读[安全](../user-guide/security.md)和[会话](../user-guide/sessions.md)，了解访问控制与对话管理。
+- **准备好开发了？** → 进入[开发者指南](../developer-guide/architecture.md)，了解内部机制并开始贡献。
+- **想要实际示例？** → 查看[指南](../guides/tips.md)部分，获取真实项目案例和技巧。
 
 :::tip
 您无需阅读所有内容。选择与您目标匹配的路径，按顺序跟随链接，即可快速上手。随时可以回到本页寻找下一步。
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/quickstart.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/quickstart.md
index 135e5ee579..f2dd34fbb5 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/quickstart.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/quickstart.md
@@ -236,7 +236,7 @@ Agent 会代你执行终端命令并显示结果。
 hermes gateway setup    # 交互式平台配置
 ```
 
-接入 [Telegram](/user-guide/messaging/telegram)、[Discord](/user-guide/messaging/discord)、[Slack](/user-guide/messaging/slack)、[WhatsApp](/user-guide/messaging/whatsapp)、[Signal](/user-guide/messaging/signal)、[Email](/user-guide/messaging/email)、[Home Assistant](/user-guide/messaging/homeassistant) 或 [Microsoft Teams](/user-guide/messaging/teams)。
+接入 [Telegram](../user-guide/messaging/telegram.md)、[Discord](../user-guide/messaging/discord.md)、[Slack](../user-guide/messaging/slack.md)、[WhatsApp](../user-guide/messaging/whatsapp.md)、[Signal](../user-guide/messaging/signal.md)、[Email](../user-guide/messaging/email.md)、[Home Assistant](../user-guide/messaging/homeassistant.md) 或 [Microsoft Teams](../user-guide/messaging/teams.md)。
 
 ### 自动化与工具
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/automate-with-cron.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/automate-with-cron.md
index 3b32d09b77..9d33c6f91c 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/automate-with-cron.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/automate-with-cron.md
@@ -6,17 +6,17 @@ description: "使用 Hermes cron 的真实自动化模式——监控、报告
 
 # 用 Cron 自动化一切
 
-[每日简报机器人教程](/guides/daily-briefing-bot)涵盖了基础内容。本指南更进一步——五种真实的自动化模式，可直接改造用于你自己的工作流。
+[每日简报机器人教程](./daily-briefing-bot.md)涵盖了基础内容。本指南更进一步——五种真实的自动化模式，可直接改造用于你自己的工作流。
 
-完整功能参考请见 [定时任务（Cron）](/user-guide/features/cron)。
+完整功能参考请见 [定时任务（Cron）](../user-guide/features/cron.md)。
 
 :::info 核心概念
 Cron 任务在全新的 agent 会话中运行，不保留当前对话的任何记忆。Prompt（提示词）必须**完全自包含**——把 agent 需要知道的一切都写进去。
 :::
 
 :::tip 不需要 LLM？你有两种零 token 方案。
-- **循环看门狗**：脚本本身已能生成精确消息（内存告警、磁盘告警、心跳）时，使用 [纯脚本 cron 任务](/guides/cron-script-only)。相同的调度器，无需 LLM。你可以在对话中让 Hermes 帮你设置——`cronjob` 工具知道何时选择 `no_agent=True` 并为你编写脚本。
-- **已在运行的脚本发起的一次性通知**（CI 步骤、post-commit hook、部署脚本、外部调度的监控）：使用 [`hermes send`](/guides/pipe-script-output) 将 stdout 或文件直接推送到 Telegram / Discord / Slack 等，无需设置 cron 条目。
+- **循环看门狗**：脚本本身已能生成精确消息（内存告警、磁盘告警、心跳）时，使用 [纯脚本 cron 任务](./cron-script-only.md)。相同的调度器，无需 LLM。你可以在对话中让 Hermes 帮你设置——`cronjob` 工具知道何时选择 `no_agent=True` 并为你编写脚本。
+- **已在运行的脚本发起的一次性通知**（CI 步骤、post-commit hook、部署脚本、外部调度的监控）：使用 [`hermes send`](./pipe-script-output.md) 将 stdout 或文件直接推送到 Telegram / Discord / Slack 等，无需设置 cron 条目。
 :::
 
 ---
@@ -263,4 +263,4 @@ Skill 按顺序加载——先加载 `arxiv`（教 agent 如何搜索论文）
 
 ---
 
-*完整的 cron 参考——所有参数、边界情况和内部机制——请见 [定时任务（Cron）](/user-guide/features/cron)。*
\ No newline at end of file
+*完整的 cron 参考——所有参数、边界情况和内部机制——请见 [定时任务（Cron）](../user-guide/features/cron.md)。*
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/automation-blueprints.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/automation-blueprints.md
index 0c0afba47d..eeae5e362c 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/automation-blueprints.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/automation-blueprints.md
@@ -6,11 +6,11 @@ description: "开箱即用的自动化蓝图——定时任务、GitHub 事件
 
 # 自动化蓝图
 
-常见自动化模式的复制粘贴蓝图。每个蓝图使用 Hermes 内置的 [cron 调度器](/user-guide/features/cron) 实现基于时间的触发，使用 [webhook 平台](/user-guide/messaging/webhooks) 实现事件驱动触发。
+常见自动化模式的复制粘贴蓝图。每个蓝图使用 Hermes 内置的 [cron 调度器](../user-guide/features/cron.md) 实现基于时间的触发，使用 [webhook 平台](../user-guide/messaging/webhooks.md) 实现事件驱动触发。
 
 所有蓝图适用于**任意模型**——不绑定单一提供商。
 
-如需带表单的参数化蓝图（无需手写 cron 语法），请参阅[自动化蓝图目录](/reference/automation-blueprints-catalog)。
+如需带表单的参数化蓝图（无需手写 cron 语法），请参阅[自动化蓝图目录](../reference/automation-blueprints-catalog.mdx)。
 
 :::tip 三种触发类型
 | 触发方式 | 方式 | 工具 |
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/azure-foundry.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/azure-foundry.md
index 03e5fc3d59..5a25e7e17f 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/azure-foundry.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/azure-foundry.md
@@ -328,7 +328,7 @@ model:
 
 ## 相关链接
 
-- [环境变量](/reference/environment-variables)
-- [配置](/user-guide/configuration)
-- [AWS Bedrock](/guides/aws-bedrock) — 另一个主要的云 provider 集成
+- [环境变量](../reference/environment-variables.md)
+- [配置](../user-guide/configuration.md)
+- [AWS Bedrock](./aws-bedrock.md) — 另一个主要的云 provider 集成
 - [Microsoft：为 Foundry 配置 Entra ID](https://learn.microsoft.com/azure/ai-foundry/foundry-models/how-to/configure-entra-id) — 无密钥路径的上游文档
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/cron-script-only.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/cron-script-only.md
index 93df4ac086..1b1202ad3a 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/cron-script-only.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/cron-script-only.md
@@ -173,7 +173,7 @@ hermes cron create "0 9 * * *"       # 标准 cron：每天上午 9 点
 hermes cron create "30m"             # 单次：30 分钟后运行一次
 ```
 
-完整语法请参阅 [cron 功能参考](/user-guide/features/cron)。
+完整语法请参阅 [cron 功能参考](../user-guide/features/cron.md)。
 
 ## 投递目标
 
@@ -235,13 +235,13 @@ hermes cron create "*/15 * * * *" \
 |----------|-----------|-------------|
 | `cronjob --no-agent`（本页） | 你的脚本，由 Hermes 调度 | 不需要推理的周期性看门狗 / 告警 / 指标 |
 | `cronjob`（默认，LLM） | 带可选预检脚本的 agent | 消息内容需要对数据进行推理时 |
-| OS cron + `curl` 到 [webhook 订阅](/user-guide/messaging/webhooks) | 你的脚本，由 OS 调度 | 当 Hermes 本身可能不健康时（即被监控对象） |
+| OS cron + `curl` 到 [webhook 订阅](../user-guide/messaging/webhooks.md) | 你的脚本，由 OS 调度 | 当 Hermes 本身可能不健康时（即被监控对象） |
 
 对于必须在 **gateway 宕机时也能触发**的关键系统健康看门狗，请使用 OS 级 cron 配合 `curl` 调用 Hermes webhook 订阅（或任何外部告警端点）——这些作为独立 OS 进程运行，不依赖 Hermes 是否在线。当被监控对象是外部系统时，in-gateway 调度器才是正确选择。
 
 ## 相关文档
 
-- [用 Cron 自动化一切](/guides/automate-with-cron) — LLM 驱动的 cron 模式。
-- [定时任务（Cron）参考](/user-guide/features/cron) — 完整计划语法、生命周期、投递路由。
-- [Webhook 订阅](/user-guide/messaging/webhooks) — 供外部调度器使用的即发即忘 HTTP 入口。
-- [Gateway 内部机制](/developer-guide/gateway-internals) — 投递路由器内部实现。
\ No newline at end of file
+- [用 Cron 自动化一切](./automate-with-cron.md) — LLM 驱动的 cron 模式。
+- [定时任务（Cron）参考](../user-guide/features/cron.md) — 完整计划语法、生命周期、投递路由。
+- [Webhook 订阅](../user-guide/messaging/webhooks.md) — 供外部调度器使用的即发即忘 HTTP 入口。
+- [Gateway 内部机制](../developer-guide/gateway-internals.md) — 投递路由器内部实现。
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/cron-troubleshooting.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/cron-troubleshooting.md
index a1405cc5e0..2362161e5e 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/cron-troubleshooting.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/cron-troubleshooting.md
@@ -224,4 +224,4 @@ hermes skills list                  # 确认已安装的 skill
 
 ---
 
-*完整的 cron 参考文档，请参阅 [用 Cron 自动化一切](/guides/automate-with-cron) 和 [定时任务（Cron）](/user-guide/features/cron)。*
\ No newline at end of file
+*完整的 cron 参考文档，请参阅 [用 Cron 自动化一切](./automate-with-cron.md) 和 [定时任务（Cron）](../user-guide/features/cron.md)。*
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/daily-briefing-bot.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/daily-briefing-bot.md
index 0b3da3e510..ede2557657 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/daily-briefing-bot.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/daily-briefing-bot.md
@@ -26,7 +26,7 @@ description: "构建一个自动化每日简报机器人，研究主题、汇总
 
 开始之前，请确保：
 
-- **已安装 Hermes Agent** — 参见[安装指南](/getting-started/installation)
+- **已安装 Hermes Agent** — 参见[安装指南](../getting-started/installation.md)
 - **Gateway 正在运行** — gateway 守护进程负责处理 cron 执行：
   ```bash
   hermes gateway install   # Install as a user service
@@ -35,7 +35,7 @@ description: "构建一个自动化每日简报机器人，研究主题、汇总
   hermes gateway           # Run in foreground
   ```
 - **Firecrawl API 密钥** — 在环境变量中设置 `FIRECRAWL_API_KEY` 以启用网页搜索
-- **已配置消息推送**（可选但推荐）— 已设置 [Telegram](/user-guide/messaging/telegram) 或 Discord 并配置了 home channel
+- **已配置消息推送**（可选但推荐）— 已设置 [Telegram](../user-guide/messaging/telegram.md) 或 Discord 并配置了 home channel
 
 :::tip 没有消息推送？没关系
 你仍然可以使用 `deliver: "local"` 跟随本教程。简报将保存至 `~/.hermes/cron/output/`，你可以随时查阅。
@@ -167,7 +167,7 @@ Format as a clean briefing with section headers and emoji. End with today's date
 Collect all results and combine them into a single clean briefing with section headers, emoji formatting, and source links. Add today's date as a header."
 ```
 
-每个子 agent 独立并行搜索，然后主 agent 将所有内容合并为一份精美的简报。详见[委托文档](/user-guide/features/delegation)了解其工作原理。
+每个子 agent 独立并行搜索，然后主 agent 将所有内容合并为一份精美的简报。详见[委托文档](../user-guide/features/delegation.md)了解其工作原理。
 
 ### 仅工作日调度
 
@@ -188,7 +188,7 @@ Collect all results and combine them into a single clean briefing with section h
 
 ### 通过 Memory 添加个人上下文
 
-如果你启用了 [memory（记忆）](/user-guide/features/memory)，可以存储跨会话持久保留的偏好设置。但请记住 — cron 任务在全新会话中运行，不保留对话记忆。若要添加个人上下文，请直接将其写入 prompt：
+如果你启用了 [memory（记忆）](../user-guide/features/memory.md)，可以存储跨会话持久保留的偏好设置。但请记住 — cron 任务在全新会话中运行，不保留对话记忆。若要添加个人上下文，请直接将其写入 prompt：
 
 ```
 /cron add "0 8 * * *" "You are creating a briefing for a senior ML engineer who cares about: PyTorch ecosystem, transformer architectures, open-weight models, and AI regulation in the EU. Skip stories about product launches or funding rounds unless they involve open source.
@@ -257,11 +257,11 @@ sudo hermes gateway install --system
 
 你已经构建了一个可运行的每日简报机器人。以下是一些可以继续探索的方向：
 
-- **[定时任务（Cron）](/user-guide/features/cron)** — 调度格式、重复限制和推送选项的完整参考
-- **[委托](/user-guide/features/delegation)** — 深入了解并行子 agent 工作流
-- **[消息推送平台](/user-guide/messaging)** — 设置 Telegram、Discord 或其他推送目标
-- **[Memory](/user-guide/features/memory)** — 跨会话的持久上下文
-- **[技巧与最佳实践](/guides/tips)** — 更多 prompt 工程建议
+- **[定时任务（Cron）](../user-guide/features/cron.md)** — 调度格式、重复限制和推送选项的完整参考
+- **[委托](../user-guide/features/delegation.md)** — 深入了解并行子 agent 工作流
+- **[消息推送平台](../user-guide/messaging/index.md)** — 设置 Telegram、Discord 或其他推送目标
+- **[Memory](../user-guide/features/memory.md)** — 跨会话的持久上下文
+- **[技巧与最佳实践](./tips.md)** — 更多 prompt 工程建议
 
 :::tip 还能调度什么？
 简报机器人的模式适用于任何场景：竞争对手监控、GitHub 仓库摘要、天气预报、投资组合追踪、服务器健康检查，甚至每日笑话。只要你能用 prompt 描述它，就能调度它。
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/delegation-patterns.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/delegation-patterns.md
index dc0ae06578..dd350332af 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/delegation-patterns.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/delegation-patterns.md
@@ -8,7 +8,7 @@ description: "何时以及如何使用子代理委托——并行研究、代码
 
 Hermes 可以生成隔离的子代理来并行处理任务。每个子代理拥有独立的对话、终端会话和工具集。只有最终摘要会返回——中间工具调用不会进入你的上下文窗口。
 
-完整功能参考，请参阅[子代理委托](/user-guide/features/delegation)。
+完整功能参考，请参阅[子代理委托](../user-guide/features/delegation.md)。
 
 ---
 
@@ -236,4 +236,4 @@ delegation:
 
 ---
 
-*完整的委托参考——所有参数、ACP 集成和高级配置——请参阅[子代理委托](/user-guide/features/delegation)。*
+*完整的委托参考——所有参数、ACP 集成和高级配置——请参阅[子代理委托](../user-guide/features/delegation.md)。*
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/github-pr-review-agent.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/github-pr-review-agent.md
index d2e6e8cf7c..dbbe9bfdd9 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/github-pr-review-agent.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/github-pr-review-agent.md
@@ -34,7 +34,7 @@ description: "构建一个自动化 AI 代码审查器，监控你的仓库、
 
 ## 前提条件
 
-- **已安装 Hermes Agent** — 参见[安装指南](/getting-started/installation)
+- **已安装 Hermes Agent** — 参见[安装指南](../getting-started/installation.md)
 - **Gateway 已运行**（用于 cron 任务）：
   ```bash
   hermes gateway install   # Install as a service
@@ -50,7 +50,7 @@ description: "构建一个自动化 AI 代码审查器，监控你的仓库、
   # Authenticate
   gh auth login
   ```
-- **已配置消息通知**（可选）— [Telegram](/user-guide/messaging/telegram) 或 [Discord](/user-guide/messaging/discord)
+- **已配置消息通知**（可选）— [Telegram](../user-guide/messaging/telegram.md) 或 [Discord](../user-guide/messaging/discord.md)
 
 :::tip 没有消息通知？没关系
 使用 `deliver: "local"` 将审查结果保存到 `~/.hermes/cron/output/`。在接入通知之前用于测试非常方便。
@@ -297,7 +297,7 @@ GitHub 对已认证用户每小时允许 5,000 次 API 请求。每次 PR 审查
 ## 下一步
 
 - **[基于 Webhook 的 PR 审查](./webhook-github-pr-review.md)** — 在 PR 被打开时立即获得审查（需要公开端点）
-- **[每日简报 Bot](/guides/daily-briefing-bot)** — 将 PR 审查与你的晨间资讯摘要结合
-- **[构建 Plugin](/developer-guide/plugins)** — 将审查逻辑封装为可共享的 plugin
-- **[Profiles](/user-guide/profiles)** — 运行一个专属审查器 profile，拥有独立的 memory 和配置
-- **[Fallback Providers](/user-guide/features/fallback-providers)** — 确保在某个 provider 不可用时审查任务仍能正常运行
\ No newline at end of file
+- **[每日简报 Bot](./daily-briefing-bot.md)** — 将 PR 审查与你的晨间资讯摘要结合
+- **[构建 Plugin](../developer-guide/plugins/index.md)** — 将审查逻辑封装为可共享的 plugin
+- **[Profiles](../user-guide/profiles.md)** — 运行一个专属审查器 profile，拥有独立的 memory 和配置
+- **[Fallback Providers](../user-guide/features/fallback-providers.md)** — 确保在某个 provider 不可用时审查任务仍能正常运行
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/google-gemini.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/google-gemini.md
index f1fa70f4dd..dad8773014 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/google-gemini.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/google-gemini.md
@@ -248,7 +248,7 @@ GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
 
 ## 相关链接
 
-- [AI Providers](/integrations/providers)
-- [Configuration](/user-guide/configuration)
-- [Fallback Providers](/user-guide/features/fallback-providers)
-- [AWS Bedrock](/guides/aws-bedrock) — 使用 AWS 凭据的原生云 provider 集成
\ No newline at end of file
+- [AI Providers](../integrations/providers.md)
+- [Configuration](../user-guide/configuration.md)
+- [Fallback Providers](../user-guide/features/fallback-providers.md)
+- [AWS Bedrock](./aws-bedrock.md) — 使用 AWS 凭据的原生云 provider 集成
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/migrate-from-openclaw.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/migrate-from-openclaw.md
index 65fcdbec89..2ebbbb5d82 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/migrate-from-openclaw.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/migrate-from-openclaw.md
@@ -163,7 +163,7 @@ TTS 设置从 OpenClaw 配置的**两个**位置读取，优先级如下：
 | `HEARTBEAT.md` | `archive/workspace/HEARTBEAT.md` | 使用 cron 作业执行周期性任务 |
 | `BOOTSTRAP.md` | `archive/workspace/BOOTSTRAP.md` | 使用上下文文件或 skills |
 | Cron 作业 | `archive/cron-config.json` | 通过 `hermes cron create` 重建 |
-| 插件 | `archive/plugins-config.json` | 参见 [插件指南](/user-guide/features/hooks) |
+| 插件 | `archive/plugins-config.json` | 参见 [插件指南](../user-guide/features/hooks.md) |
 | Hooks/webhooks | `archive/hooks-config.json` | 使用 `hermes webhook` 或 gateway hooks |
 | 记忆后端 | `archive/memory-backend-config.json` | 通过 `hermes honcho` 配置 |
 | Skills 注册表 | `archive/skills-registry-config.json` | 使用 `hermes skills config` |
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/operate-teams-meeting-pipeline.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/operate-teams-meeting-pipeline.md
index 482622fe50..d46acdaf1d 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/operate-teams-meeting-pipeline.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/operate-teams-meeting-pipeline.md
@@ -5,7 +5,7 @@ description: "Microsoft Teams 会议流水线的运行手册、上线检查清
 
 # 操作 Teams 会议流水线
 
-本指南适用于已通过 [Teams Meetings](/user-guide/messaging/teams-meetings) 启用该功能之后的操作阶段。
+本指南适用于已通过 [Teams Meetings](../user-guide/messaging/teams-meetings.md) 启用该功能之后的操作阶段。
 
 本页内容：
 - 操作员 CLI 流程
@@ -284,5 +284,5 @@ hermes teams-pipeline show <job-id>
 
 ## 相关文档
 
-- [Teams Meetings 设置](/user-guide/messaging/teams-meetings)
-- [Microsoft Teams bot 设置](/user-guide/messaging/teams)
\ No newline at end of file
+- [Teams Meetings 设置](../user-guide/messaging/teams-meetings.md)
+- [Microsoft Teams bot 设置](../user-guide/messaging/teams.md)
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/pipe-script-output.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/pipe-script-output.md
index 72c961c74f..788ca4c56b 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/pipe-script-output.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/pipe-script-output.md
@@ -209,9 +209,9 @@ hermes send --list --json
 
 ## 相关文档
 
-- [用 Cron 自动化一切](/guides/automate-with-cron) —
+- [用 Cron 自动化一切](./automate-with-cron.md) —
   输出自动投递到任意平台的定时任务。
-- [Gateway 内部机制](/developer-guide/gateway-internals) —
+- [Gateway 内部机制](../developer-guide/gateway-internals.md) —
   `hermes send` 与 cron 投递共享的投递路由器。
-- [消息平台配置](/user-guide/messaging/) —
+- [消息平台配置](../user-guide/messaging/index.md) —
   各平台的一次性配置说明。
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/team-telegram-assistant.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/team-telegram-assistant.md
index e8b5c4c0ea..5d43fec105 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/team-telegram-assistant.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/team-telegram-assistant.md
@@ -24,7 +24,7 @@ description: "逐步指南：为整个团队搭建一个 Telegram 机器人，
 
 开始前，请确保你已具备：
 
-- **已在服务器或 VPS 上安装 Hermes Agent**（不是你的笔记本——机器人需要持续运行）。如尚未安装，请参阅[安装指南](/getting-started/installation)。
+- **已在服务器或 VPS 上安装 Hermes Agent**（不是你的笔记本——机器人需要持续运行）。如尚未安装，请参阅[安装指南](../getting-started/installation.md)。
 - **一个 Telegram 账号**（机器人所有者）
 - **已配置 LLM 提供商**——至少在 `~/.hermes/.env` 中配置了 OpenAI、Anthropic 或其他受支持提供商的 API 密钥
 
@@ -291,7 +291,7 @@ display:
 
 通过编辑 `~/.hermes/SOUL.md` 自定义机器人的沟通方式：
 
-完整指南请参阅[在 Hermes 中使用 SOUL.md](/guides/use-soul-with-hermes)。
+完整指南请参阅[在 Hermes 中使用 SOUL.md](./use-soul-with-hermes.md)。
 
 ```markdown
 # Soul
@@ -428,13 +428,13 @@ hermes gateway stop && hermes gateway start
 
 你已经拥有一个可用的团队 Telegram 助手。以下是一些后续步骤：
 
-- **[安全指南](/user-guide/security)**——深入了解授权、容器隔离和命令审批
-- **[消息 Gateway](/user-guide/messaging)**——gateway 架构、会话管理和聊天命令的完整参考
-- **[Telegram 设置](/user-guide/messaging/telegram)**——平台专属详情，包括语音消息和 TTS
-- **[定时任务](/user-guide/features/cron)**——高级 cron 调度，含投递选项和 cron 表达式
-- **[上下文文件](/user-guide/features/context-files)**——用于项目知识的 AGENTS.md、SOUL.md 和 .cursorrules
-- **[个性设置](/user-guide/features/personality)**——内置个性预设和自定义角色定义
-- **添加更多平台**——同一 gateway 可同时运行 [Discord](/user-guide/messaging/discord)、[Slack](/user-guide/messaging/slack) 和 [WhatsApp](/user-guide/messaging/whatsapp)
+- **[安全指南](../user-guide/security.md)**——深入了解授权、容器隔离和命令审批
+- **[消息 Gateway](../user-guide/messaging/index.md)**——gateway 架构、会话管理和聊天命令的完整参考
+- **[Telegram 设置](../user-guide/messaging/telegram.md)**——平台专属详情，包括语音消息和 TTS
+- **[定时任务](../user-guide/features/cron.md)**——高级 cron 调度，含投递选项和 cron 表达式
+- **[上下文文件](../user-guide/features/context-files.md)**——用于项目知识的 AGENTS.md、SOUL.md 和 .cursorrules
+- **[个性设置](../user-guide/features/personality.md)**——内置个性预设和自定义角色定义
+- **添加更多平台**——同一 gateway 可同时运行 [Discord](../user-guide/messaging/discord.md)、[Slack](../user-guide/messaging/slack.md) 和 [WhatsApp](../user-guide/messaging/whatsapp.md)
 
 ---
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/tips.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/tips.md
index c258aa2e34..dd8def3b7b 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/tips.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/tips.md
@@ -80,7 +80,7 @@ CLI 会自动检测多行粘贴。直接粘贴代码块或错误堆栈——不
 
 想让 Hermes 拥有稳定的默认风格？编辑 `~/.hermes/SOUL.md`（如果使用自定义 Hermes home，则为 `$HERMES_HOME/SOUL.md`）。Hermes 现在会自动生成一个初始 SOUL 文件，并将该全局文件作为实例级个性来源。
 
-完整说明请参阅 [在 Hermes 中使用 SOUL.md](/guides/use-soul-with-hermes)。
+完整说明请参阅 [在 Hermes 中使用 SOUL.md](./use-soul-with-hermes.md)。
 
 ```markdown
 # Soul
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-mcp-with-hermes.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-mcp-with-hermes.md
index ee5ac3f1d7..02f268455b 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-mcp-with-hermes.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-mcp-with-hermes.md
@@ -485,6 +485,6 @@ enabled: false
 
 ## 相关文档
 
-- [MCP（模型上下文协议）](/user-guide/features/mcp)
-- [FAQ](/reference/faq)
-- [斜杠命令](/reference/slash-commands)
\ No newline at end of file
+- [MCP（模型上下文协议）](../user-guide/features/mcp.md)
+- [FAQ](../reference/faq.md)
+- [斜杠命令](../reference/slash-commands.md)
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-soul-with-hermes.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-soul-with-hermes.md
index ef43ae4c6e..22059ecd7f 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-soul-with-hermes.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-soul-with-hermes.md
@@ -258,7 +258,7 @@ vim ~/.hermes/SOUL.md
 
 ## 相关文档
 
-- [个性与 SOUL.md](/user-guide/features/personality)
-- [上下文文件](/user-guide/features/context-files)
-- [配置](/user-guide/configuration)
-- [技巧与最佳实践](/guides/tips)
\ No newline at end of file
+- [个性与 SOUL.md](../user-guide/features/personality.md)
+- [上下文文件](../user-guide/features/context-files.md)
+- [配置](../user-guide/configuration.md)
+- [技巧与最佳实践](./tips.md)
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-voice-mode-with-hermes.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-voice-mode-with-hermes.md
index 99bbe53fa7..e41ab8edcd 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-voice-mode-with-hermes.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-voice-mode-with-hermes.md
@@ -6,7 +6,7 @@ description: "在 CLI、Telegram、Discord 及 Discord 语音频道中设置和
 
 # 在 Hermes 中使用语音模式
 
-本指南是[语音模式功能参考](/user-guide/features/voice-mode)的实用配套文档。
+本指南是[语音模式功能参考](../user-guide/features/voice-mode.md)的实用配套文档。
 
 功能页面介绍语音模式能做什么，本指南则说明如何真正用好它。
 
@@ -462,8 +462,8 @@ Hermes 加入 Discord 语音频道（VC），监听用户语音，转录后运
 
 ## 下一步阅读
 
-- [语音模式功能参考](/user-guide/features/voice-mode)
-- [消息 Gateway](/user-guide/messaging)
-- [Discord 设置](/user-guide/messaging/discord)
-- [Telegram 设置](/user-guide/messaging/telegram)
-- [配置](/user-guide/configuration)
\ No newline at end of file
+- [语音模式功能参考](../user-guide/features/voice-mode.md)
+- [消息 Gateway](../user-guide/messaging/index.md)
+- [Discord 设置](../user-guide/messaging/discord.md)
+- [Telegram 设置](../user-guide/messaging/telegram.md)
+- [配置](../user-guide/configuration.md)
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/webhook-github-pr-review.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/webhook-github-pr-review.md
index 788deb3b85..47e5396f0c 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/webhook-github-pr-review.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/webhook-github-pr-review.md
@@ -16,7 +16,7 @@ description: "将 Hermes 连接到 GitHub，使其自动获取 PR diff、审查
 :::
 
 :::info 参考文档
-完整的 webhook 平台参考（所有配置选项、投递类型、动态订阅、安全模型），请参阅 [Webhooks](/user-guide/messaging/webhooks)。
+完整的 webhook 平台参考（所有配置选项、投递类型、动态订阅、安全模型），请参阅 [Webhooks](../user-guide/messaging/webhooks.md)。
 :::
 
 :::warning Prompt 注入风险
@@ -196,7 +196,7 @@ GitHub 会针对多种 action 发送 `pull_request` 事件：`opened`、`synchro
 
 ## 使用 skill 保持一致的审查风格
 
-加载一个 [Hermes skill](/user-guide/features/skills) 以赋予 agent 一致的审查风格。在 `config.yaml` 的 `platforms.webhook.extra.routes` 中，向你的路由添加 `skills`：
+加载一个 [Hermes skill](../user-guide/features/skills.md) 以赋予 agent 一致的审查风格。在 `config.yaml` 的 `platforms.webhook.extra.routes` 中，向你的路由添加 `skills`：
 
 ```yaml
 platforms:
@@ -324,6 +324,6 @@ platforms:
 ## 下一步
 
 - **[基于 Cron 的 PR 审查](./github-pr-review-agent.md)** —— 按计划轮询 PR，无需公网端点
-- **[Webhook 参考](/user-guide/messaging/webhooks)** —— webhook 平台的完整配置参考
-- **[构建 Plugin](/developer-guide/plugins)** —— 将审查逻辑打包为可共享的 plugin
-- **[Profiles](/user-guide/profiles)** —— 运行一个拥有独立内存和配置的专属审查者 profile
\ No newline at end of file
+- **[Webhook 参考](../user-guide/messaging/webhooks.md)** —— webhook 平台的完整配置参考
+- **[构建 Plugin](../developer-guide/plugins/index.md)** —— 将审查逻辑打包为可共享的 plugin
+- **[Profiles](../user-guide/profiles.md)** —— 运行一个拥有独立内存和配置的专属审查者 profile
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/work-with-skills.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/work-with-skills.md
index d834538b25..d613fd17ce 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/work-with-skills.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/work-with-skills.md
@@ -8,7 +8,7 @@ description: "查找、安装、使用和创建 skills——按需加载的知
 
 Skills（技能）是按需加载的知识文档，用于教会 Hermes 如何处理特定任务——从生成 ASCII 艺术到管理 GitHub PR。本指南介绍日常使用方法。
 
-完整技术参考请见 [Skills 系统](/user-guide/features/skills)。
+完整技术参考请见 [Skills 系统](../user-guide/features/skills.md)。
 
 ---
 
@@ -135,7 +135,7 @@ skill_view("writing-plans")
 
 插件 skills **不会**列在系统 prompt 中，也不出现在 `skills_list` 中。它们是按需加载的——当你知道某个插件提供了某个 skill 时，显式加载它。加载后，agent 会看到一个横幅，列出同一插件的其他 skills。
 
-关于如何在自己的插件中捆绑 skills，请参见 [构建 Hermes 插件 → 捆绑 skills](/developer-guide/plugins#bundle-skills)。
+关于如何在自己的插件中捆绑 skills，请参见 [构建 Hermes 插件 → 捆绑 skills](../developer-guide/plugins/index.md#bundle-skills)。
 
 ---
 
@@ -287,4 +287,4 @@ hermes skills
 
 ---
 
-*完整的 skills 参考——frontmatter 字段、条件激活、外部目录等——请见 [Skills 系统](/user-guide/features/skills)。*
\ No newline at end of file
+*完整的 skills 参考——frontmatter 字段、条件激活、外部目录等——请见 [Skills 系统](../user-guide/features/skills.md)。*
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/index.mdx b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/index.mdx
index b4f7515680..d4c0b43a4b 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/index.mdx
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/index.mdx
@@ -57,7 +57,7 @@ import Link from "@docusaurus/Link";
 curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
 ```
 
-**Windows（原生，PowerShell）** — _早期测试版，[详情 →](/user-guide/windows-native)_
+**Windows（原生，PowerShell）** — _早期测试版，[详情 →](./user-guide/windows-native.md)_
 
 ```powershell
 iex (irm https://hermes-agent.nousresearch.com/install.ps1)
@@ -65,7 +65,7 @@ iex (irm https://hermes-agent.nousresearch.com/install.ps1)
 
 **Android（Termux）** — 与 Linux 相同的 curl 一行命令；安装程序会自动检测 Termux。
 
-请参阅完整的 **[安装指南](/getting-started/installation)**，了解安装程序的具体操作、按用户与 root 的目录布局以及 Windows 相关说明。
+请参阅完整的 **[安装指南](./getting-started/installation.md)**，了解安装程序的具体操作、按用户与 root 的目录布局以及 Windows 相关说明。
 
 ## Hermes Agent 是什么？
 
@@ -75,24 +75,24 @@ iex (irm https://hermes-agent.nousresearch.com/install.ps1)
 
 |                                                                       |                                                                    |
 | --------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| 🚀 **[安装](/getting-started/installation)**                          | 在 Linux、macOS、WSL2 或原生 Windows（早期测试版）上 60 秒完成安装 |
-| 📖 **[快速入门教程](/getting-started/quickstart)**                    | 第一次对话及值得尝试的核心功能                                     |
-| 🗺️ **[学习路径](/getting-started/learning-path)**                     | 根据你的经验水平找到合适的文档                                     |
-| ⚙️ **[配置](/user-guide/configuration)**                              | 配置文件、提供商、模型及选项                                       |
-| 💬 **[消息网关](/user-guide/messaging)**                              | 配置 Telegram、Discord、Slack、WhatsApp、Teams 等平台              |
-| 🔧 **[工具与工具集](/user-guide/features/tools)**                     | 70+ 内置工具及其配置方式                                           |
-| 🧠 **[记忆系统](/user-guide/features/memory)**                        | 跨会话持续增长的持久记忆                                           |
-| 📚 **[技能系统](/user-guide/features/skills)**                        | 智能体创建并复用的程序性记忆                                       |
-| 🔌 **[MCP 集成](/user-guide/features/mcp)**                           | 连接 MCP 服务器、过滤其工具，并安全扩展 Hermes                     |
-| 🧭 **[在 Hermes 中使用 MCP](/guides/use-mcp-with-hermes)**            | 实用的 MCP 配置模式、示例与教程                                    |
-| 🎙️ **[语音模式](/user-guide/features/voice-mode)**                    | 在 CLI、Telegram、Discord 及 Discord 语音频道中进行实时语音交互    |
-| 🗣️ **[在 Hermes 中使用语音模式](/guides/use-voice-mode-with-hermes)** | Hermes 语音工作流的实操配置与使用模式                              |
-| 🎭 **[个性与 SOUL.md](/user-guide/features/personality)**             | 通过全局 SOUL.md 定义 Hermes 的默认风格                            |
-| 📄 **[上下文文件](/user-guide/features/context-files)**               | 影响每次对话的项目上下文文件                                       |
-| 🔒 **[安全](/user-guide/security)**                                   | 命令审批、授权与容器隔离                                           |
-| 💡 **[技巧与最佳实践](/guides/tips)**                                 | 快速上手，充分发挥 Hermes 的潜力                                   |
-| 🏗️ **[架构](/developer-guide/architecture)**                          | 底层工作原理                                                       |
-| ❓ **[常见问题与故障排查](/reference/faq)**                           | 常见问题及解决方案                                                 |
+| 🚀 **[安装](./getting-started/installation.md)**                          | 在 Linux、macOS、WSL2 或原生 Windows（早期测试版）上 60 秒完成安装 |
+| 📖 **[快速入门教程](./getting-started/quickstart.md)**                    | 第一次对话及值得尝试的核心功能                                     |
+| 🗺️ **[学习路径](./getting-started/learning-path.md)**                     | 根据你的经验水平找到合适的文档                                     |
+| ⚙️ **[配置](./user-guide/configuration.md)**                              | 配置文件、提供商、模型及选项                                       |
+| 💬 **[消息网关](./user-guide/messaging/index.md)**                              | 配置 Telegram、Discord、Slack、WhatsApp、Teams 等平台              |
+| 🔧 **[工具与工具集](./user-guide/features/tools.md)**                     | 70+ 内置工具及其配置方式                                           |
+| 🧠 **[记忆系统](./user-guide/features/memory.md)**                        | 跨会话持续增长的持久记忆                                           |
+| 📚 **[技能系统](./user-guide/features/skills.md)**                        | 智能体创建并复用的程序性记忆                                       |
+| 🔌 **[MCP 集成](./user-guide/features/mcp.md)**                           | 连接 MCP 服务器、过滤其工具，并安全扩展 Hermes                     |
+| 🧭 **[在 Hermes 中使用 MCP](./guides/use-mcp-with-hermes.md)**            | 实用的 MCP 配置模式、示例与教程                                    |
+| 🎙️ **[语音模式](./user-guide/features/voice-mode.md)**                    | 在 CLI、Telegram、Discord 及 Discord 语音频道中进行实时语音交互    |
+| 🗣️ **[在 Hermes 中使用语音模式](./guides/use-voice-mode-with-hermes.md)** | Hermes 语音工作流的实操配置与使用模式                              |
+| 🎭 **[个性与 SOUL.md](./user-guide/features/personality.md)**             | 通过全局 SOUL.md 定义 Hermes 的默认风格                            |
+| 📄 **[上下文文件](./user-guide/features/context-files.md)**               | 影响每次对话的项目上下文文件                                       |
+| 🔒 **[安全](./user-guide/security.md)**                                   | 命令审批、授权与容器隔离                                           |
+| 💡 **[技巧与最佳实践](./guides/tips.md)**                                 | 快速上手，充分发挥 Hermes 的潜力                                   |
+| 🏗️ **[架构](./developer-guide/architecture.md)**                          | 底层工作原理                                                       |
+| ❓ **[常见问题与故障排查](./reference/faq.md)**                           | 常见问题及解决方案                                                 |
 
 ## 核心功能
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/buzz.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/buzz.md
index 85ca200f9e..56d8bf211c 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/buzz.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/buzz.md
@@ -22,7 +22,7 @@ Hermes 有三种方式与 Buzz 集成。根据 Hermes 运行的位置和你的
 
 Buzz Desktop 将 Hermes 作为预设运行时提供。按常规方式安装 Hermes 后，打开 **Settings → Runtimes**，Hermes 会自动出现——发现机制在登录 shell 的 PATH 上解析 `hermes-acp` 启动器，安装器会将其写入 `~/.local/bin`（较旧安装由 `hermes update` 自动补齐）。
 
-完整设置、故障排查和安全注意事项（Buzz 会自动批准工具权限——请保持 agent 为 owner-only）：**[ACP 宿主集成 → Buzz Desktop](/user-guide/features/acp#buzz-desktop)**
+完整设置、故障排查和安全注意事项（Buzz 会自动批准工具权限——请保持 agent 为 owner-only）：**[ACP 宿主集成 → Buzz Desktop](../user-guide/features/acp.md#buzz-desktop)**
 
 ## ② 中继桥接（buzz-acp + ACP）
 
@@ -32,7 +32,7 @@ Buzz Desktop 将 Hermes 作为预设运行时提供。按常规方式安装 Herm
 Buzz relay <-- WebSocket --> buzz-acp <-- ACP over stdio --> Hermes Agent
 ```
 
-被启动的 Hermes 使用该主机上相同的配置、凭据、记忆和技能。密钥铸造、频道发现、所有者遥测（`BUZZ_ACP_RELAY_OBSERVER`）和无头权限指南：**[ACP 宿主集成 → Buzz 频道（中继桥接）](/user-guide/features/acp)**
+被启动的 Hermes 使用该主机上相同的配置、凭据、记忆和技能。密钥铸造、频道发现、所有者遥测（`BUZZ_ACP_RELAY_OBSERVER`）和无头权限指南：**[ACP 宿主集成 → Buzz 频道（中继桥接）](../user-guide/features/acp.md)**
 
 ## ③ 原生网关平台（完整 Hermes 推荐）
 
@@ -42,7 +42,7 @@ Buzz relay <-- WebSocket --> buzz-acp <-- ACP over stdio --> Hermes Agent
 hermes gateway setup   # 选择 Buzz
 ```
 
-完整配置参考（环境变量、config.yaml、传输模式、访问控制）：**[消息平台 → Buzz](/user-guide/messaging/buzz)**
+完整配置参考（环境变量、config.yaml、传输模式、访问控制）：**[消息平台 → Buzz](../user-guide/messaging/buzz.md)**
 
 ## 该选哪一个？
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/index.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/index.md
index 3906102e00..d9414ff2a6 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/index.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/index.md
@@ -12,13 +12,13 @@ Hermes Agent 可连接外部系统，用于 AI 推理、工具服务器、IDE 
 
 Hermes 开箱即支持多个 AI 推理提供商。使用 `hermes model` 进行交互式配置，或在 `config.yaml` 中直接设置。
 
-- **[AI 提供商](/user-guide/features/provider-routing)** — OpenRouter、Anthropic、OpenAI、Google 以及任何兼容 OpenAI 的端点。Hermes 会自动检测每个提供商的能力，包括视觉、流式传输和工具调用。
-- **[提供商路由](/user-guide/features/provider-routing)** — 精细控制哪些底层提供商处理你的 OpenRouter 请求。通过排序、白名单、黑名单和显式优先级排序，在成本、速度或质量之间优化。
-- **[备用提供商](/user-guide/features/fallback-providers)** — 当主模型遇到错误时，自动故障转移到备用 LLM 提供商。包括主模型回退，以及用于视觉、压缩和网页提取的独立辅助任务回退。
+- **[AI 提供商](../user-guide/features/provider-routing.md)** — OpenRouter、Anthropic、OpenAI、Google 以及任何兼容 OpenAI 的端点。Hermes 会自动检测每个提供商的能力，包括视觉、流式传输和工具调用。
+- **[提供商路由](../user-guide/features/provider-routing.md)** — 精细控制哪些底层提供商处理你的 OpenRouter 请求。通过排序、白名单、黑名单和显式优先级排序，在成本、速度或质量之间优化。
+- **[备用提供商](../user-guide/features/fallback-providers.md)** — 当主模型遇到错误时，自动故障转移到备用 LLM 提供商。包括主模型回退，以及用于视觉、压缩和网页提取的独立辅助任务回退。
 
 ## 工具服务器（MCP）
 
-- **[MCP 服务器](/user-guide/features/mcp)** — 通过 Model Context Protocol 将 Hermes 连接到外部工具服务器。无需编写原生 Hermes 工具，即可访问来自 GitHub、数据库、文件系统、浏览器栈、内部 API 等的工具。支持 stdio 和 SSE 两种传输方式、按服务器过滤工具，以及具备能力感知的资源/prompt 注册。
+- **[MCP 服务器](../user-guide/features/mcp.md)** — 通过 Model Context Protocol 将 Hermes 连接到外部工具服务器。无需编写原生 Hermes 工具，即可访问来自 GitHub、数据库、文件系统、浏览器栈、内部 API 等的工具。支持 stdio 和 SSE 两种传输方式、按服务器过滤工具，以及具备能力感知的资源/prompt 注册。
 
 ## 网页搜索后端
 
@@ -49,7 +49,7 @@ Hermes 内置完整的浏览器自动化功能，提供多种后端选项，用
 - **本地 Chromium 系 CDP** — 使用 `/browser connect` 连接正在运行的 Chrome、Brave、Chromium 或 Edge 浏览器
 - **本地 Chromium** — 通过 `agent-browser` CLI 使用无头本地浏览器
 
-详见[浏览器自动化](/user-guide/features/browser)的配置与使用说明。
+详见[浏览器自动化](../user-guide/features/browser.md)的配置与使用说明。
 
 ## 语音与 TTS 提供商
 
@@ -63,38 +63,38 @@ Hermes 内置完整的浏览器自动化功能，提供多种后端选项，用
 | **MiniMax** | 良好 | 付费 | `MINIMAX_API_KEY` |
 | **NeuTTS** | 良好 | 免费 | 无需 |
 
-语音转文字支持六个提供商：本地 faster-whisper（免费，设备端运行）、本地命令封装器、Groq、OpenAI Whisper API、Mistral 和 xAI。语音消息转录支持 Telegram、Discord、WhatsApp 及其他消息平台。详见[语音与 TTS](/user-guide/features/tts) 和[语音模式](/user-guide/features/voice-mode)。
+语音转文字支持六个提供商：本地 faster-whisper（免费，设备端运行）、本地命令封装器、Groq、OpenAI Whisper API、Mistral 和 xAI。语音消息转录支持 Telegram、Discord、WhatsApp 及其他消息平台。详见[语音与 TTS](../user-guide/features/tts.md) 和[语音模式](../user-guide/features/voice-mode.md)。
 
 ## IDE 与编辑器集成
 
-- **[IDE 集成（ACP）](/user-guide/features/acp)** — 在兼容 ACP 的编辑器（如 VS Code、Zed 和 JetBrains）中使用 Hermes Agent。Hermes 作为 ACP 服务器运行，在编辑器内渲染聊天消息、工具活动、文件差异和终端命令。
+- **[IDE 集成（ACP）](../user-guide/features/acp.md)** — 在兼容 ACP 的编辑器（如 VS Code、Zed 和 JetBrains）中使用 Hermes Agent。Hermes 作为 ACP 服务器运行，在编辑器内渲染聊天消息、工具活动、文件差异和终端命令。
 
 ## 程序化访问
 
-- **[API 服务器](/user-guide/features/api-server)** — 将 Hermes 暴露为兼容 OpenAI 的 HTTP 端点。任何支持 OpenAI 格式的前端——Open WebUI、LobeChat、LibreChat、NextChat、ChatBox——均可连接并将 Hermes 作为后端使用，享有其完整工具集。
+- **[API 服务器](../user-guide/features/api-server.md)** — 将 Hermes 暴露为兼容 OpenAI 的 HTTP 端点。任何支持 OpenAI 格式的前端——Open WebUI、LobeChat、LibreChat、NextChat、ChatBox——均可连接并将 Hermes 作为后端使用，享有其完整工具集。
 
 ## 记忆与个性化
 
-- **[内置记忆](/user-guide/features/memory)** — 通过 `MEMORY.md` 和 `USER.md` 文件实现持久化、精选记忆。Agent 维护有界的个人笔记和用户画像数据存储，跨会话保留。
-- **[记忆提供商](/user-guide/features/memory-providers)** — 接入外部记忆后端以实现更深度的个性化。支持八个提供商：Honcho（辩证推理）、OpenViking（分层检索）、Mem0（云端提取）、Hindsight（知识图谱）、Holographic（本地 SQLite）、RetainDB（混合搜索）、ByteRover（基于 CLI）和 Supermemory。
+- **[内置记忆](../user-guide/features/memory.md)** — 通过 `MEMORY.md` 和 `USER.md` 文件实现持久化、精选记忆。Agent 维护有界的个人笔记和用户画像数据存储，跨会话保留。
+- **[记忆提供商](../user-guide/features/memory-providers.md)** — 接入外部记忆后端以实现更深度的个性化。支持八个提供商：Honcho（辩证推理）、OpenViking（分层检索）、Mem0（云端提取）、Hindsight（知识图谱）、Holographic（本地 SQLite）、RetainDB（混合搜索）、ByteRover（基于 CLI）和 Supermemory。
 
 ## 消息平台
 
 Hermes 可作为 gateway（网关）机器人运行于 19+ 个消息平台，均通过同一 `gateway` 子系统配置：
 
-- **[Telegram](/user-guide/messaging/telegram)**、**[Discord](/user-guide/messaging/discord)**、**[Slack](/user-guide/messaging/slack)**、**[WhatsApp](/user-guide/messaging/whatsapp)**、**[Signal](/user-guide/messaging/signal)**、**[Matrix](/user-guide/messaging/matrix)**、**[Mattermost](/user-guide/messaging/mattermost)**、**[Email](/user-guide/messaging/email)**、**[SMS](/user-guide/messaging/sms)**、**[DingTalk](/user-guide/messaging/dingtalk)**、**[Feishu/Lark](/user-guide/messaging/feishu)**、**[WeCom](/user-guide/messaging/wecom)**、**[WeCom Callback](/user-guide/messaging/wecom-callback)**、**[Weixin](/user-guide/messaging/weixin)**、**[BlueBubbles](/user-guide/messaging/bluebubbles)**、**[QQ Bot](/user-guide/messaging/qqbot)**、**[Yuanbao](/user-guide/messaging/yuanbao)**、**[Home Assistant](/user-guide/messaging/homeassistant)**、**[Microsoft Teams](/user-guide/messaging/teams)**、**[Webhooks](/user-guide/messaging/webhooks)**
+- **[Telegram](../user-guide/messaging/telegram.md)**、**[Discord](../user-guide/messaging/discord.md)**、**[Slack](../user-guide/messaging/slack.md)**、**[WhatsApp](../user-guide/messaging/whatsapp.md)**、**[Signal](../user-guide/messaging/signal.md)**、**[Matrix](../user-guide/messaging/matrix.md)**、**[Mattermost](../user-guide/messaging/mattermost.md)**、**[Email](../user-guide/messaging/email.md)**、**[SMS](../user-guide/messaging/sms.md)**、**[DingTalk](../user-guide/messaging/dingtalk.md)**、**[Feishu/Lark](../user-guide/messaging/feishu.md)**、**[WeCom](../user-guide/messaging/wecom.md)**、**[WeCom Callback](../user-guide/messaging/wecom-callback.md)**、**[Weixin](../user-guide/messaging/weixin.md)**、**[BlueBubbles](../user-guide/messaging/bluebubbles.md)**、**[QQ Bot](../user-guide/messaging/qqbot.md)**、**[Yuanbao](../user-guide/messaging/yuanbao.md)**、**[Home Assistant](../user-guide/messaging/homeassistant.md)**、**[Microsoft Teams](../user-guide/messaging/teams.md)**、**[Webhooks](../user-guide/messaging/webhooks.md)**
 
-平台对比表和配置指南详见[消息 Gateway 概览](/user-guide/messaging)。
+平台对比表和配置指南详见[消息 Gateway 概览](../user-guide/messaging/index.md)。
 
 ## 家庭自动化
 
-- **[Home Assistant](/user-guide/messaging/homeassistant)** — 通过四个专用工具（`ha_list_entities`、`ha_get_state`、`ha_list_services`、`ha_call_service`）控制智能家居设备。配置 `HASS_TOKEN` 后，Home Assistant 工具集将自动激活。
+- **[Home Assistant](../user-guide/messaging/homeassistant.md)** — 通过四个专用工具（`ha_list_entities`、`ha_get_state`、`ha_list_services`、`ha_call_service`）控制智能家居设备。配置 `HASS_TOKEN` 后，Home Assistant 工具集将自动激活。
 
 ## 插件
 
-- **[插件系统](/user-guide/features/plugins)** — 无需修改核心代码，通过自定义工具、生命周期 hook（钩子）和 CLI 命令扩展 Hermes。插件从 `~/.hermes/plugins/`、项目本地 `.hermes/plugins/` 以及通过 pip 安装的入口点自动发现。
-- **[构建插件](/developer-guide/plugins)** — 创建包含工具、hook 和 CLI 命令的 Hermes 插件的分步指南。
+- **[插件系统](../user-guide/features/plugins.md)** — 无需修改核心代码，通过自定义工具、生命周期 hook（钩子）和 CLI 命令扩展 Hermes。插件从 `~/.hermes/plugins/`、项目本地 `.hermes/plugins/` 以及通过 pip 安装的入口点自动发现。
+- **[构建插件](../developer-guide/plugins/index.md)** — 创建包含工具、hook 和 CLI 命令的 Hermes 插件的分步指南。
 
 ## 训练与评估
 
-- **[批处理](/user-guide/features/batch-processing)** — 并行跨数百个 prompt（提示词）运行 Agent，生成结构化的 ShareGPT 格式轨迹数据，用于训练数据生成或评估。
\ No newline at end of file
+- **[批处理](../user-guide/features/batch-processing.md)** — 并行跨数百个 prompt（提示词）运行 Agent，生成结构化的 ShareGPT 格式轨迹数据，用于训练数据生成或评估。
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/providers.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/providers.md
index 4a0513f519..c405c43b94 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/providers.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/providers.md
@@ -44,7 +44,7 @@ sidebar_position: 1
 | **LM Studio** | `hermes model` → "LM Studio"（provider: `lmstudio`，可选 `LM_API_KEY`） |
 | **自定义端点** | `hermes model` → 选择"Custom endpoint"（保存在 `config.yaml`） |
 
-官方 API key 路径请参见专属的 [Google Gemini 指南](/guides/google-gemini)。
+官方 API key 路径请参见专属的 [Google Gemini 指南](../guides/google-gemini.md)。
 
 :::tip 模型 key 别名
 在 `model:` 配置节中，可以使用 `default:` 或 `model:` 作为模型 ID 的键名。`model: { default: my-model }` 和 `model: { model: my-model }` 效果完全相同。
@@ -53,7 +53,7 @@ sidebar_position: 1
 
 ### Nous Portal
 
-[Nous Portal](https://portal.nousresearch.com) 是 Nous Research 的统一订阅网关，也是**运行 Hermes Agent 的推荐方式**。一次 OAuth 登录即可访问 300+ 前沿智能体模型（Claude、GPT、Gemini、DeepSeek、Qwen、Kimi、GLM、MiniMax、Grok 等）以及 [Tool Gateway](/user-guide/features/tool-gateway)（网页搜索、图像生成、TTS、浏览器自动化）——费用从你的 Nous 订阅中扣除，无需单独管理各提供商账户。
+[Nous Portal](https://portal.nousresearch.com) 是 Nous Research 的统一订阅网关，也是**运行 Hermes Agent 的推荐方式**。一次 OAuth 登录即可访问 300+ 前沿智能体模型（Claude、GPT、Gemini、DeepSeek、Qwen、Kimi、GLM、MiniMax、Grok 等）以及 [Tool Gateway](../user-guide/features/tool-gateway.md)（网页搜索、图像生成、TTS、浏览器自动化）——费用从你的 Nous 订阅中扣除，无需单独管理各提供商账户。
 
 ```bash
 hermes setup --portal     # 全新安装——一条命令完成 OAuth + 提供商 + 网关配置
@@ -63,7 +63,7 @@ hermes portal info        # 随时查看登录状态和路由信息
 
 还没有订阅？前往 [portal.nousresearch.com/manage-subscription](https://portal.nousresearch.com/manage-subscription) 购买。
 
-**完整详情：** 参见专属的 [Nous Portal 集成页面](/integrations/nous-portal)（订阅内容、模型目录、故障排查）以及分步指南[使用 Nous Portal 运行 Hermes Agent](/guides/run-hermes-with-nous-portal)。
+**完整详情：** 参见专属的 [Nous Portal 集成页面](./nous-portal.md)（订阅内容、模型目录、故障排查）以及分步指南[使用 Nous Portal 运行 Hermes Agent](../guides/run-hermes-with-nous-portal.md)。
 
 
 :::info Codex 说明
@@ -88,11 +88,11 @@ Groups = x25519:secp256r1:secp384r1:x448
 :::
 
 :::warning
-即使使用 Nous Portal、Codex 或自定义端点，某些工具（视觉、网页摘要、MoA）仍会使用单独的"辅助"模型。默认情况下（`auxiliary.*.provider: "auto"`），Hermes 将这些任务路由到你的**主聊天模型**——即你在 `hermes model` 中选择的同一模型。你可以单独覆盖每个任务，将其路由到更便宜/更快的模型（例如 OpenRouter 上的 Gemini Flash）——参见[辅助模型](/user-guide/configuration#auxiliary-models)。
+即使使用 Nous Portal、Codex 或自定义端点，某些工具（视觉、网页摘要、MoA）仍会使用单独的"辅助"模型。默认情况下（`auxiliary.*.provider: "auto"`），Hermes 将这些任务路由到你的**主聊天模型**——即你在 `hermes model` 中选择的同一模型。你可以单独覆盖每个任务，将其路由到更便宜/更快的模型（例如 OpenRouter 上的 Gemini Flash）——参见[辅助模型](../user-guide/configuration.md#auxiliary-models)。
 :::
 
 :::tip Nous Tool Gateway
-付费 Nous Portal 订阅者还可访问 **[Tool Gateway](/user-guide/features/tool-gateway)**——网页搜索、图像生成、TTS 和浏览器自动化，均通过你的订阅路由。无需额外 API key。全新安装时，`hermes setup --portal` 一条命令即可完成登录、设置 Nous 为提供商并开启网关。现有用户可通过 `hermes model` 或 `hermes tools` 按工具启用。随时使用 `hermes portal info` 查看路由状态。
+付费 Nous Portal 订阅者还可访问 **[Tool Gateway](../user-guide/features/tool-gateway.md)**——网页搜索、图像生成、TTS 和浏览器自动化，均通过你的订阅路由。无需额外 API key。全新安装时，`hermes setup --portal` 一条命令即可完成登录、设置 Nous 为提供商并开启网关。现有用户可通过 `hermes model` 或 `hermes tools` 按工具启用。随时使用 `hermes portal info` 查看路由状态。
 :::
 
 ### 模型管理的两个命令
@@ -365,7 +365,7 @@ bedrock:
 
 Bedrock 底层使用 **Converse API**——请求被转换为 Bedrock 的模型无关格式，因此同一配置适用于 Claude、Nova、DeepSeek 和 Llama 模型。仅在调用非默认区域端点时才需设置 `BEDROCK_BASE_URL`。
 
-参见 [AWS Bedrock 指南](/guides/aws-bedrock)，了解 IAM 配置、区域选择和跨区域推理的详细步骤。
+参见 [AWS Bedrock 指南](../guides/aws-bedrock.md)，了解 IAM 配置、区域选择和跨区域推理的详细步骤。
 
 ### Qwen Portal（OAuth）
 
@@ -434,7 +434,7 @@ model:
 支持的模型：`MiniMax-M2.7`（主模型）和 `MiniMax-M2.7-highspeed`（默认辅助模型）。OAuth 路径忽略 `MINIMAX_API_KEY` / `MINIMAX_BASE_URL`。
 
 :::tip MiniMax OAuth 与 API key
-`minimax-oauth` 使用 MiniMax 面向消费者的 portal，通过 OAuth 登录——无需设置计费。`minimax` 和 `minimax-cn` 提供商使用 `MINIMAX_API_KEY` / `MINIMAX_CN_API_KEY`——用于程序化访问。完整流程参见 [MiniMax OAuth 指南](/guides/minimax-oauth)。
+`minimax-oauth` 使用 MiniMax 面向消费者的 portal，通过 OAuth 登录——无需设置计费。`minimax` 和 `minimax-cn` 提供商使用 `MINIMAX_API_KEY` / `MINIMAX_CN_API_KEY`——用于程序化访问。完整流程参见 [MiniMax OAuth 指南](../guides/minimax-oauth.md)。
 :::
 
 ### NVIDIA NIM
@@ -993,7 +993,7 @@ model:
 
 **可能原因：**
 1. **服务器上的输出上限（`max_tokens`）过低** — SGLang 默认每次响应 128 tokens。在服务器上设置 `--default-max-tokens`；Hermes 不再提供用户输出上限设置。注意：`max_tokens` 只控制响应长度——与对话历史可以有多长无关（那是 `context_length`）。
-2. **上下文耗尽** — 模型填满了上下文窗口。增加 `model.context_length` 或在 Hermes 中启用[上下文压缩](/user-guide/configuration#context-compression)。
+2. **上下文耗尽** — 模型填满了上下文窗口。增加 `model.context_length` 或在 Hermes 中启用[上下文压缩](../user-guide/configuration.md#context-compression)。
 
 ---
 
@@ -1393,7 +1393,7 @@ openrouter:
 - 设置为空字符串（或删除该行）让 OpenRouter 选择最强的可用编程模型——这是省略 plugins 块时的文档行为。
 - 在给定日期内，按分数选择是确定性的，但随着 Pareto 前沿移动（新模型、基准更新），实际选择的模型可能变化。
 - 参见 OpenRouter 的 [Pareto Router 文档](https://openrouter.ai/docs/guides/routing/routers/pareto-router) 了解完整路由器行为。
-- 要将 Pareto Code 路由器用于特定**辅助任务**（压缩、视觉等）而非主智能体，在该任务下设置 `extra_body.plugins`——参见[辅助模型 → OpenRouter 路由与辅助任务的 Pareto Code](/user-guide/configuration#openrouter-routing--pareto-code-for-auxiliary-tasks)。
+- 要将 Pareto Code 路由器用于特定**辅助任务**（压缩、视觉等）而非主智能体，在该任务下设置 `extra_body.plugins`——参见[辅助模型 → OpenRouter 路由与辅助任务的 Pareto Code](../user-guide/configuration.md#openrouter-routing--pareto-code-for-auxiliary-tasks)。
 
 ## 故障转移提供商
 
@@ -1422,12 +1422,12 @@ fallback_model:
 支持的提供商：`openrouter`、`nous`、`openai-codex`、`copilot`、`copilot-acp`、`anthropic`、`gemini`、`qwen-oauth`、`huggingface`、`zai`、`kimi-coding`、`kimi-coding-cn`、`minimax`、`minimax-cn`、`minimax-oauth`、`deepseek`、`nvidia`、`xai`、`xai-oauth`、`ollama-cloud`、`bedrock`、`azure-foundry`、`opencode-zen`、`opencode-go`、`kilocode`、`xiaomi`、`arcee`、`gmi`、`stepfun`、`lmstudio`、`alibaba`、`alibaba-coding-plan`、`tencent-tokenhub`、`custom`。
 
 :::tip
-故障转移仅通过 `config.yaml` 配置——或通过 `hermes fallback` 交互式配置。有关触发时机、链推进方式以及与辅助任务和委托的交互，参见[故障转移提供商](/user-guide/features/fallback-providers)。
+故障转移仅通过 `config.yaml` 配置——或通过 `hermes fallback` 交互式配置。有关触发时机、链推进方式以及与辅助任务和委托的交互，参见[故障转移提供商](../user-guide/features/fallback-providers.md)。
 :::
 
 ---
 
 ## 另请参阅
 
-- [配置](/user-guide/configuration) — 通用配置（目录结构、配置优先级、终端后端、记忆、压缩等）
-- [环境变量](/reference/environment-variables) — 所有环境变量的完整参考
+- [配置](../user-guide/configuration.md) — 通用配置（目录结构、配置优先级、终端后端、记忆、压缩等）
+- [环境变量](../reference/environment-variables.md) — 所有环境变量的完整参考
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/cli-commands.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/cli-commands.md
index 4271ae3d2a..bb8cd5319a 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/cli-commands.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/cli-commands.md
@@ -227,7 +227,7 @@ hermes gateway <subcommand>
 | `--no-supervise` | 在 `run` 时：在 s6-overlay Docker 镜像内部，跳过 s6 自动监管，退回到 pre-s6 前台语义——gateway 作为容器主进程运行，无自动重启。在 s6 镜像之外为空操作。等同于设置 `HERMES_GATEWAY_NO_SUPERVISE=1`。 |
 
 :::tip WSL 用户
-使用 `hermes gateway run` 而非 `hermes gateway start`——WSL 的 systemd 支持不稳定。用 tmux 包裹以保持持久运行：`tmux new -s hermes 'hermes gateway run'`。详见 [WSL FAQ](/reference/faq#wsl-gateway-keeps-disconnecting-or-hermes-gateway-start-fails)。
+使用 `hermes gateway run` 而非 `hermes gateway start`——WSL 的 systemd 支持不稳定。用 tmux 包裹以保持持久运行：`tmux new -s hermes 'hermes gateway run'`。详见 [WSL FAQ](./faq.md#wsl-gateway-keeps-disconnecting-or-hermes-gateway-start-fails)。
 :::
 
 ## `hermes lsp`
@@ -249,7 +249,7 @@ hermes lsp <subcommand>
 | `restart` | 关闭正在运行的客户端，以便下次编辑时重新启动。 |
 | `which <id>` | 打印某个服务器的已解析二进制路径。 |
 
-完整指南、支持的语言和配置项，请参阅 [LSP — 语义诊断](/user-guide/features/lsp)。
+完整指南、支持的语言和配置项，请参阅 [LSP — 语义诊断](../user-guide/features/lsp.md)。
 
 ## `hermes setup`
 
@@ -333,7 +333,7 @@ hermes slack manifest --slashes-only  # 仅输出 features.slash_commands 数组
 
 ## `hermes auth`
 
-管理同一 provider 的密钥轮换凭据池。完整文档请参阅 [凭据池](/user-guide/features/credential-pools)。
+管理同一 provider 的密钥轮换凭据池。完整文档请参阅 [凭据池](../user-guide/features/credential-pools.md)。
 
 ```bash
 hermes auth                                              # 交互式向导
@@ -393,7 +393,7 @@ hermes kanban [--board <slug>] <action> [options]
 |------|---------|
 | `--board <slug>` | 操作特定看板。默认为当前看板（通过 `hermes kanban boards switch`、`HERMES_KANBAN_BOARD` 环境变量或 `default` 设置）。 |
 
-**这是人工/脚本操作界面。** 调度器生成的 agent worker 通过专用的 `kanban_*` [toolset](/user-guide/features/kanban#how-workers-interact-with-the-board)（`kanban_show`、`kanban_complete`、`kanban_block`、`kanban_create`、`kanban_link`、`kanban_comment`、`kanban_heartbeat`；编排器 profile 还可使用 `kanban_list` 和 `kanban_unblock`）驱动看板，而非调用 `hermes kanban`。Worker 的环境中固定了 `HERMES_KANBAN_BOARD`，因此物理上无法看到其他看板。
+**这是人工/脚本操作界面。** 调度器生成的 agent worker 通过专用的 `kanban_*` [toolset](../user-guide/features/kanban.md#how-workers-interact-with-the-board)（`kanban_show`、`kanban_complete`、`kanban_block`、`kanban_create`、`kanban_link`、`kanban_comment`、`kanban_heartbeat`；编排器 profile 还可使用 `kanban_list` 和 `kanban_unblock`）驱动看板，而非调用 `hermes kanban`。Worker 的环境中固定了 `HERMES_KANBAN_BOARD`，因此物理上无法看到其他看板。
 
 | 操作 | 用途 |
 |--------|---------|
@@ -421,7 +421,7 @@ hermes kanban [--board <slug>] <action> [options]
 | `dispatch` | 对活跃看板执行一次调度器扫描。标志：`--dry-run`、`--max N`、`--failure-limit N`、`--json`。 |
 | `context <id>` | 打印 worker 将看到的完整上下文（标题 + 正文 + 父任务结果 + 评论）。 |
 | `specify <id>` / `specify --all` | 通过辅助 LLM 将 triage 列中的任务细化为具体规格（标题 + 包含目标、方案、验收标准的正文），然后将其提升到 `todo`。标志：`--tenant`（将 `--all` 限定到一个 tenant）、`--author`、`--json`。在 `config.yaml` 的 `auxiliary.triage_specifier` 下配置模型。 |
-| `decompose <id>` / `decompose --all` | 将 triage 列中的任务按描述拆分为子任务图，路由到专业 profile（编排器驱动路径）。当 LLM 判断任务不适合拆分时，回退到 specify 风格的单任务提升。与 `specify` 相同的标志。在 `config.yaml` 的 `auxiliary.kanban_decomposer` 下配置模型。当 `kanban.auto_decompose: true`（默认）时，每次调度器 tick 也会自动运行。参见 [自动与手动编排](/user-guide/features/kanban#auto-vs-manual-orchestration)。 |
+| `decompose <id>` / `decompose --all` | 将 triage 列中的任务按描述拆分为子任务图，路由到专业 profile（编排器驱动路径）。当 LLM 判断任务不适合拆分时，回退到 specify 风格的单任务提升。与 `specify` 相同的标志。在 `config.yaml` 的 `auxiliary.kanban_decomposer` 下配置模型。当 `kanban.auto_decompose: true`（默认）时，每次调度器 tick 也会自动运行。参见 [自动与手动编排](../user-guide/features/kanban.md#auto-vs-manual-orchestration)。 |
 | `gc` | 删除已归档任务的 scratch 工作区。 |
 
 示例：
@@ -444,7 +444,7 @@ hermes kanban boards rm atm10-server --delete
 
 所有操作也可作为 gateway 中的斜杠命令使用（`/kanban …`），参数界面相同——包括 `boards` 子命令和 `--board` 标志。
 
-完整设计——与 Cline Kanban / Paperclip / NanoClaw / Gemini Enterprise 的对比、八种协作模式、四个用户故事、并发正确性证明——请参阅 [Kanban 用户指南](/user-guide/features/kanban)。
+完整设计——与 Cline Kanban / Paperclip / NanoClaw / Gemini Enterprise 的对比、八种协作模式、四个用户故事、并发正确性证明——请参阅 [Kanban 用户指南](../user-guide/features/kanban.md)。
 
 ## `hermes webhook`
 
@@ -1145,7 +1145,7 @@ hermes claw migrate --source /home/user/old-openclaw
 hermes dashboard [options]
 ```
 
-启动 Web 控制台——基于浏览器的界面，用于管理配置、API 密钥和监控会话。需要 `cd ~/.hermes/hermes-agent && uv pip install -e ".[web]"`（FastAPI + Uvicorn）。内嵌浏览器 Chat 标签页始终可用，但额外需要 `pty` extra（`cd ~/.hermes/hermes-agent && uv pip install -e ".[web,pty]"`）以及 POSIX PTY 环境（如 Linux、macOS 或 WSL2）。完整文档请参阅 [Web 控制台](/user-guide/features/web-dashboard)。
+启动 Web 控制台——基于浏览器的界面，用于管理配置、API 密钥和监控会话。需要 `cd ~/.hermes/hermes-agent && uv pip install -e ".[web]"`（FastAPI + Uvicorn）。内嵌浏览器 Chat 标签页始终可用，但额外需要 `pty` extra（`cd ~/.hermes/hermes-agent && uv pip install -e ".[web,pty]"`）以及 POSIX PTY 环境（如 Linux、macOS 或 WSL2）。完整文档请参阅 [Web 控制台](../user-guide/features/web-dashboard.md)。
 
 | 选项 | 默认值 | 说明 |
 |--------|---------|-------------|
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/environment-variables.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/environment-variables.md
index 265c39fc4a..ead51dbf03 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/environment-variables.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/environment-variables.md
@@ -58,7 +58,7 @@ description: "Hermes Agent 使用的所有环境变量完整参考"
 | `AZURE_CLIENT_SECRET` | `EnvironmentCredential` 使用的服务主体密钥 |
 | `AZURE_CLIENT_CERTIFICATE_PATH` | 服务主体证书（`AZURE_CLIENT_SECRET` 的替代方案） |
 | `AZURE_FEDERATED_TOKEN_FILE` | AKS Workload Identity / OIDC 流程的联合 token 文件路径 |
-| `AZURE_AUTHORITY_HOST` | 主权云 authority 覆盖（例如 Azure Government 使用 `https://login.microsoftonline.us`）。参见 [Azure Foundry 指南](/guides/azure-foundry#sovereign-clouds-government-china) |
+| `AZURE_AUTHORITY_HOST` | 主权云 authority 覆盖（例如 Azure Government 使用 `https://login.microsoftonline.us`）。参见 [Azure Foundry 指南](../guides/azure-foundry.md#sovereign-clouds-government-china) |
 | `IDENTITY_ENDPOINT` / `MSI_ENDPOINT` | App Service、Functions 和 Container Apps 的托管标识端点；VM 通常使用 IMDS 而不设置这些变量 |
 | `HF_TOKEN` | Hugging Face Inference Providers token（[huggingface.co/settings/tokens](https://huggingface.co/settings/tokens)） |
 | `HF_BASE_URL` | 覆盖 Hugging Face base URL（默认：`https://router.huggingface.co/v1`） |
@@ -160,7 +160,7 @@ description: "Hermes Agent 使用的所有环境变量完整参考"
 
 ### Langfuse 可观测性
 
-内置 [`observability/langfuse`](/user-guide/features/built-in-plugins#observabilitylangfuse) 插件的环境变量。在 `~/.hermes/.env` 中设置。在这些变量生效之前，还必须启用该插件（`hermes plugins enable observability/langfuse`，或在 `hermes plugins` 中勾选）。
+内置 [`observability/langfuse`](../user-guide/features/built-in-plugins.md#observabilitylangfuse) 插件的环境变量。在 `~/.hermes/.env` 中设置。在这些变量生效之前，还必须启用该插件（`hermes plugins enable observability/langfuse`，或在 `hermes plugins` 中勾选）。
 
 | 变量 | 描述 |
 |----------|-------------|
@@ -176,7 +176,7 @@ description: "Hermes Agent 使用的所有环境变量完整参考"
 
 ### Nous Tool Gateway
 
-这些变量为付费 Nous 订阅者或自托管 gateway 部署配置 [Tool Gateway](/user-guide/features/tool-gateway)。大多数用户无需设置——gateway 通过 `hermes model` 或 `hermes tools` 自动配置。
+这些变量为付费 Nous 订阅者或自托管 gateway 部署配置 [Tool Gateway](../user-guide/features/tool-gateway.md)。大多数用户无需设置——gateway 通过 `hermes model` 或 `hermes tools` 自动配置。
 
 | 变量 | 描述 |
 |----------|-------------|
@@ -415,7 +415,7 @@ description: "Hermes Agent 使用的所有环境变量完整参考"
 | `API_SERVER_PORT` | API 服务器端口（默认：`8642`） |
 | `API_SERVER_HOST` | API 服务器主机/绑定地址（默认：`127.0.0.1`）。使用 `0.0.0.0` 开放网络访问——需要 `API_SERVER_KEY` 和严格的 `API_SERVER_CORS_ORIGINS` 白名单。 |
 | `API_SERVER_MODEL_NAME` | `/v1/models` 上公告的模型名称。默认为 profile 名称（默认 profile 为 `hermes-agent`）。适用于 Open WebUI 等前端需要每个连接使用不同模型名称的多用户场景。 |
-| `GATEWAY_PROXY_URL` | 将消息转发到的远程 Hermes API 服务器 URL（[代理模式](/user-guide/messaging/matrix#proxy-mode-e2ee-on-macos)）。设置后，gateway 仅处理平台 I/O——所有 agent 工作委托给远程服务器。也可通过 `config.yaml` 中的 `gateway.proxy_url` 配置。 |
+| `GATEWAY_PROXY_URL` | 将消息转发到的远程 Hermes API 服务器 URL（[代理模式](../user-guide/messaging/matrix.md#proxy-mode-e2ee-on-macos)）。设置后，gateway 仅处理平台 I/O——所有 agent 工作委托给远程服务器。也可通过 `config.yaml` 中的 `gateway.proxy_url` 配置。 |
 | `GATEWAY_PROXY_KEY` | 代理模式下与远程 API 服务器认证的 Bearer token。必须与远程主机上的 `API_SERVER_KEY` 一致。 |
 | `MESSAGING_CWD` | 消息模式下终端命令的工作目录（默认：`~`） |
 | `GATEWAY_ALLOWED_USERS` | 跨所有平台允许的逗号分隔用户 ID |
@@ -423,7 +423,7 @@ description: "Hermes Agent 使用的所有环境变量完整参考"
 
 ### Microsoft Graph（Teams 会议）
 
-用于即将推出的 Teams 会议摘要流水线的 Microsoft Graph REST 客户端的仅应用凭证。Azure 门户操作步骤和所需 API 权限详见[注册 Microsoft Graph 应用程序](/guides/microsoft-graph-app-registration)。
+用于即将推出的 Teams 会议摘要流水线的 Microsoft Graph REST 客户端的仅应用凭证。Azure 门户操作步骤和所需 API 权限详见[注册 Microsoft Graph 应用程序](../guides/microsoft-graph-app-registration.md)。
 
 | 变量 | 描述 |
 |----------|-------------|
@@ -435,7 +435,7 @@ description: "Hermes Agent 使用的所有环境变量完整参考"
 
 ### Microsoft Graph Webhook 监听器
 
-Graph 事件（Teams 会议、日历、聊天等）的入站变更通知监听器。设置和安全加固详见 [Microsoft Graph Webhook 监听器](/user-guide/messaging/msgraph-webhook)。
+Graph 事件（Teams 会议、日历、聊天等）的入站变更通知监听器。设置和安全加固详见 [Microsoft Graph Webhook 监听器](../user-guide/messaging/msgraph-webhook.md)。
 
 | 变量 | 描述 |
 |----------|-------------|
@@ -447,7 +447,7 @@ Graph 事件（Teams 会议、日历、聊天等）的入站变更通知监听
 
 ### Teams 会议摘要投递
 
-仅在启用 [`teams_pipeline` 插件](/user-guide/messaging/msgraph-webhook)时使用。设置也可在 `config.yaml` 的 `platforms.teams.extra` 下配置——两者都设置时环境变量优先。参见 [Microsoft Teams → 会议摘要投递](/user-guide/messaging/teams#meeting-summary-delivery-teams-meeting-pipeline)。
+仅在启用 [`teams_pipeline` 插件](../user-guide/messaging/msgraph-webhook.md)时使用。设置也可在 `config.yaml` 的 `platforms.teams.extra` 下配置——两者都设置时环境变量优先。参见 [Microsoft Teams → 会议摘要投递](../user-guide/messaging/teams.md#meeting-summary-delivery-teams-meeting-pipeline)。
 
 | 变量 | 描述 |
 |----------|-------------|
@@ -460,7 +460,7 @@ Graph 事件（Teams 会议、日历、聊天等）的入站变更通知监听
 
 ### LINE Messaging API
 
-由内置 LINE 平台插件（`plugins/platforms/line/`）使用。完整设置详见 [消息 Gateway → LINE](/user-guide/messaging/line)。
+由内置 LINE 平台插件（`plugins/platforms/line/`）使用。完整设置详见 [消息 Gateway → LINE](../user-guide/messaging/line.md)。
 
 | 变量 | 描述 |
 |----------|-------------|
@@ -497,7 +497,7 @@ Graph 事件（Teams 会议、日历、聊天等）的入站变更通知监听
 | `NTFY_HOME_CHANNEL` | `deliver: ntfy` 的 cron 任务的默认投递目标。 |
 | `NTFY_HOME_CHANNEL_NAME` | 主频道的人类可读标签（默认为话题名称）。 |
 
-在使用不受信任的话题部署前，请参阅 [ntfy 消息指南](/user-guide/messaging/ntfy)——特别是**身份模型**部分。
+在使用不受信任的话题部署前，请参阅 [ntfy 消息指南](../user-guide/messaging/ntfy.md)——特别是**身份模型**部分。
 
 ### 高级消息调优
 
@@ -658,7 +658,7 @@ fallback_providers:
 
 旧版顶层 `fallback_model` 单提供商格式仍可向后兼容读取，但新配置应使用 `fallback_providers`。
 
-详见 [回退提供商](/user-guide/features/fallback-providers)。
+详见 [回退提供商](../user-guide/features/fallback-providers.md)。
 
 ## 提供商路由（仅 config.yaml）
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/faq.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/faq.md
index e1c39b9b1f..f77d4ad9a2 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/faq.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/faq.md
@@ -595,9 +595,9 @@ hermes chat
 ```
 
 另请参阅：
-- [MCP（模型上下文协议）](/user-guide/features/mcp)
-- [在 Hermes 中使用 MCP](/guides/use-mcp-with-hermes)
-- [MCP 配置参考](/reference/mcp-config-reference)
+- [MCP（模型上下文协议）](../user-guide/features/mcp.md)
+- [在 Hermes 中使用 MCP](../guides/use-mcp-with-hermes.md)
+- [MCP 配置参考](./mcp-config-reference.md)
 
 #### MCP 超时错误
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/mcp-config-reference.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/mcp-config-reference.md
index 899b94999a..bb135b1159 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/mcp-config-reference.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/mcp-config-reference.md
@@ -9,8 +9,8 @@ description: "Hermes Agent MCP 配置键、过滤语义及工具策略参考"
 本页是主 MCP 文档的简明参考手册。
 
 概念说明请参阅：
-- [MCP（Model Context Protocol）](/user-guide/features/mcp)
-- [在 Hermes 中使用 MCP](/guides/use-mcp-with-hermes)
+- [MCP（Model Context Protocol）](../user-guide/features/mcp.md)
+- [在 Hermes 中使用 MCP](../guides/use-mcp-with-hermes.md)
 
 ## 根配置结构
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/slash-commands.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/slash-commands.md
index 00fd4b74a2..00657198d8 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/slash-commands.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/slash-commands.md
@@ -49,17 +49,17 @@ Hermes 有两个斜杠命令入口，均由 `hermes_cli/commands.py` 中的中
 | `/stop` | 终止所有正在运行的后台进程 |
 | `/queue <prompt>`（别名：`/q`） | 将 prompt（提示词）加入队列等待下一轮处理（不会中断当前 agent 响应）。 |
 | `/steer <prompt>` | 在**下一次工具调用之后**向 agent 注入一条中途说明——不中断、不产生新的用户轮次。当前工具完成后，该文本会追加到最后一条工具结果的内容中，在不打断当前工具调用循环的情况下为 agent 提供新上下文。可用于在任务进行中调整方向（例如在 agent 运行测试时说"专注于 auth 模块"）。 |
-| `/goal <text>` | 设置一个持续目标，Hermes 将跨轮次持续推进——这是我们对 Ralph loop 的实现。每轮结束后，辅助裁判模型会判断目标是否完成；若未完成，Hermes 自动继续。子命令：`/goal status`、`/goal pause`、`/goal resume`、`/goal clear`。预算默认为 20 轮（`goals.max_turns`）；任何真实用户消息都会抢占继续循环，状态在 `/resume` 后保留。完整说明见 [持续目标](/user-guide/features/goals)。 |
+| `/goal <text>` | 设置一个持续目标，Hermes 将跨轮次持续推进——这是我们对 Ralph loop 的实现。每轮结束后，辅助裁判模型会判断目标是否完成；若未完成，Hermes 自动继续。子命令：`/goal status`、`/goal pause`、`/goal resume`、`/goal clear`。预算默认为 20 轮（`goals.max_turns`）；任何真实用户消息都会抢占继续循环，状态在 `/resume` 后保留。完整说明见 [持续目标](../user-guide/features/goals.md)。 |
 | `/subgoal <text>` | 在循环进行中向活动目标追加一个用户自定义条件。继续 prompt 会将所有子目标原文呈现给 agent，裁判也会将其纳入 DONE/CONTINUE 判断——因此只有原始目标**和**所有子目标都满足时，目标才会被标记为完成。子命令：`/subgoal`（列出）、`/subgoal remove <N>`、`/subgoal clear`。需要有活动的 `/goal`。 |
 | `/resume [name]` | 恢复之前命名的会话 |
 | `/sessions` | 在交互式选择器中浏览并恢复历史会话 |
 | `/redraw` | 强制完整重绘 UI（在 tmux 调整大小、鼠标选择产生残影等导致终端错位后恢复）。 |
 | `/status` | 显示会话信息——模型、提供商、profile、会话 ID、工作目录、标题、创建/更新时间戳、token 总量、agent 运行状态——随后显示本地**会话摘要**块（近期用户/助手轮次数、工具结果数、最常用工具、最近访问的文件、最新用户 prompt 和最新助手回复）。摘要从内存中的对话本地计算，不调用 LLM，不影响 prompt 缓存。 |
 | `/agents`（别名：`/tasks`） | 显示当前会话中的活动 agent 和运行中的任务。 |
-| `/bg <prompt>` | 在独立的后台会话中运行 prompt。agent 独立处理你的 prompt——当前会话保持空闲可继续其他工作。任务完成后结果以面板形式显示。见 [CLI 后台会话](/user-guide/cli#background-sessions)。 |
+| `/bg <prompt>` | 在独立的后台会话中运行 prompt。agent 独立处理你的 prompt——当前会话保持空闲可继续其他工作。任务完成后结果以面板形式显示。见 [CLI 后台会话](../user-guide/cli.md#background-sessions)。 |
 | `/btw <question>` | 在不打断当前工作的情况下，就**当前对话**提出一个快速的顺带问题。由一次一次性辅助 LLM 调用根据对话快照作答——实时会话的历史和提示缓存不受影响，当前回合继续运行。需要全新上下文的独立任务请使用 `/bg`。 |
 | `/branch [name]`（别名：`/fork`） | 分支当前会话（探索不同路径） |
-| `/handoff <platform>` | **仅限 CLI。** 将当前会话移交给消息平台（Telegram、Discord、Slack、WhatsApp、Signal、Matrix）。gateway 立即接管，在支持线程的平台上创建新线程（Telegram 话题、Discord 文字频道线程、Slack 和 Matrix 消息锚定线程），将目标重新绑定到你的 CLI session_id 以重放完整的角色感知转录，并伪造一条合成用户轮次让 agent 确认已在新位置工作。成功后 CLI 干净退出并提示 `/resume`；随时可用 `/resume <title>` 在本地恢复。轮次进行中拒绝执行。需要 gateway 正在运行且目标平台已配置 home 频道（从目标聊天中执行 `/sethome`）。见 [跨平台移交](/user-guide/sessions#cross-platform-handoff)。 |
+| `/handoff <platform>` | **仅限 CLI。** 将当前会话移交给消息平台（Telegram、Discord、Slack、WhatsApp、Signal、Matrix）。gateway 立即接管，在支持线程的平台上创建新线程（Telegram 话题、Discord 文字频道线程、Slack 和 Matrix 消息锚定线程），将目标重新绑定到你的 CLI session_id 以重放完整的角色感知转录，并伪造一条合成用户轮次让 agent 确认已在新位置工作。成功后 CLI 干净退出并提示 `/resume`；随时可用 `/resume <title>` 在本地恢复。轮次进行中拒绝执行。需要 gateway 正在运行且目标平台已配置 home 频道（从目标聊天中执行 `/sethome`）。见 [跨平台移交](../user-guide/sessions.md#cross-platform-handoff)。 |
 
 ### 配置
 
@@ -88,13 +88,13 @@ Hermes 有两个斜杠命令入口，均由 `hermes_cli/commands.py` 中的中
 | `/toolsets` | 列出可用工具集 |
 | `/browser [connect\|disconnect\|status]` | 管理本地 Chromium 系浏览器的 CDP 连接。`connect` 将浏览器工具附加到正在运行的 Chrome、Brave、Chromium 或 Edge 实例（默认：`http://127.0.0.1:9222`）。`disconnect` 断开连接。`status` 显示当前连接状态。若未检测到调试器，则自动启动支持的 Chromium 系浏览器。 |
 | `/skills` | 从在线注册表搜索、安装、检查或管理 skill |
-| `/memory [pending\|approve\|reject\|approval]` | 审核由写入审批门控（`memory.write_approval`）暂存的待处理 memory 写入，并切换该门控。见 [Memory 功能](/user-guide/features/memory)。 |
-| `/bundles` | 列出已配置的 skill bundle——即一次预加载多个 skill 的 `/<name>` 斜杠别名。在 `~/.hermes/config.yaml` 的 `bundles:` 下配置。见 [Skills 功能](/user-guide/features/skills)。 |
+| `/memory [pending\|approve\|reject\|approval]` | 审核由写入审批门控（`memory.write_approval`）暂存的待处理 memory 写入，并切换该门控。见 [Memory 功能](../user-guide/features/memory.md)。 |
+| `/bundles` | 列出已配置的 skill bundle——即一次预加载多个 skill 的 `/<name>` 斜杠别名。在 `~/.hermes/config.yaml` 的 `bundles:` 下配置。见 [Skills 功能](../user-guide/features/skills.md)。 |
 | `/cron` | 管理定时任务（列出、添加/创建、编辑、暂停、恢复、运行、删除） |
 | `/suggestions [accept\|dismiss N\|catalog\|clear]`（别名：`/suggest`） | 审核建议的自动化。使用 `/suggestions` 列出待处理建议，`/suggestions accept <id>` 接受并创建建议任务，`/suggestions dismiss <id>` 拒绝单条建议，`/suggestions catalog` 添加精选起步自动化，`/suggestions clear` 清理已解决的建议记录。被接受的任务会保留当前表面作为投递来源。 |
 | `/blueprint [name] [slot=value ...]`（别名：`/bp`） | 通过 blueprint 模板设置自动化。裸 `/blueprint` 列出目录；`/blueprint <name>` 会在下一次 agent 轮次启动引导式填槽流程；`/blueprint <name> slot=value ...` 直接创建任务。 |
-| `/curator` | 后台 skill 维护——`status`、`run`、`pin`、`archive`。见 [Curator](/user-guide/features/curator)。 |
-| `/kanban <action>` | 无需离开聊天即可操作多 profile、多项目协作看板。完整的 `hermes kanban` 命令面均可用：`/kanban list`、`/kanban show t_abc`、`/kanban create "title" --assignee X`、`/kanban comment t_abc "text"`、`/kanban unblock t_abc`、`/kanban dispatch` 等。支持多看板：`/kanban boards list`、`/kanban boards create <slug>`、`/kanban boards switch <slug>`、`/kanban --board <slug> <action>`。见 [Kanban 斜杠命令](/user-guide/features/kanban#kanban-slash-command)。 |
+| `/curator` | 后台 skill 维护——`status`、`run`、`pin`、`archive`。见 [Curator](../user-guide/features/curator.md)。 |
+| `/kanban <action>` | 无需离开聊天即可操作多 profile、多项目协作看板。完整的 `hermes kanban` 命令面均可用：`/kanban list`、`/kanban show t_abc`、`/kanban create "title" --assignee X`、`/kanban comment t_abc "text"`、`/kanban unblock t_abc`、`/kanban dispatch` 等。支持多看板：`/kanban boards list`、`/kanban boards create <slug>`、`/kanban boards switch <slug>`、`/kanban --board <slug> <action>`。见 [Kanban 斜杠命令](../user-guide/features/kanban.md#kanban-slash-command)。 |
 | `/reload-mcp`（别名：`/reload_mcp`） | 从 config.yaml 重新加载 MCP 服务器 |
 | `/reload-skills`（别名：`/reload_skills`） | 重新扫描 `~/.hermes/skills/` 以发现新安装或已删除的 skill |
 | `/reload` | 将 `.env` 变量重新加载到运行中的会话（无需重启即可获取新 API 密钥） |
@@ -212,7 +212,7 @@ hermes config set model.aliases.grok x-ai/grok-4
 | `/undo` | 移除最后一轮对话。 |
 | `/sethome`（别名：`/set-home`） | 将当前聊天标记为该平台的 home 频道，用于消息投递。 |
 | `/compress [focus topic]` | 手动压缩对话上下文。可选的焦点主题可缩小摘要保留的范围。 |
-| `/topic [off\|help\|session-id]` | **仅限 Telegram DM。** 管理用户自主的多会话话题模式。`/topic` 启用或显示状态；`/topic off` 禁用并清除绑定；`/topic help` 显示用法；在话题中执行 `/topic <session-id>` 可恢复之前的会话。见 [多会话 DM 模式](/user-guide/messaging/telegram#multi-session-dm-mode-topic)。 |
+| `/topic [off\|help\|session-id]` | **仅限 Telegram DM。** 管理用户自主的多会话话题模式。`/topic` 启用或显示状态；`/topic off` 禁用并清除绑定；`/topic help` 显示用法；在话题中执行 `/topic <session-id>` 可恢复之前的会话。见 [多会话 DM 模式](../user-guide/messaging/telegram.md#multi-session-dm-mode-topic)。 |
 | `/title [name]` | 设置或显示会话标题。 |
 | `/resume [name]` | 恢复之前命名的会话。 |
 | `/usage` | 显示 token 用量、估算费用明细（输入/输出）、上下文窗口状态、会话时长，以及——当活动提供商支持时——从提供商 API 实时拉取的**账户限额**部分，包含剩余配额/积分。 |
@@ -221,18 +221,18 @@ hermes config set model.aliases.grok x-ai/grok-4
 | `/reasoning [level\|show\|hide]` | 更改推理力度或切换推理显示。 |
 | `/voice [on\|off\|tts\|join\|channel\|leave\|status]` | 控制聊天中的语音回复。`join`/`channel`/`leave` 管理 Discord 语音频道模式。 |
 | `/rollback [number]` | 列出或恢复文件系统检查点。 |
-| `/bg <prompt>` | 在独立的后台会话中运行 prompt。任务完成后结果投递回同一聊天。见 [消息平台后台会话](/user-guide/messaging/#background-sessions)。 |
+| `/bg <prompt>` | 在独立的后台会话中运行 prompt。任务完成后结果投递回同一聊天。见 [消息平台后台会话](../user-guide/messaging/index.md#background-sessions)。 |
 | `/btw <question>` | 在不打断当前对话的情况下，就当前对话提出顺带问题。根据对话快照作答；答案就绪后发送到聊天中。 |
 | `/queue <prompt>`（别名：`/q`） | 将 prompt 加入队列等待下一轮处理，不中断当前轮次。 |
 | `/steer <prompt>` | 在下一次工具调用后注入一条消息，不中断——模型在下一次迭代时获取，而非作为新轮次。 |
-| `/goal <text>` | 设置一个持续目标，Hermes 将跨轮次持续推进——这是我们对 Ralph loop 的实现。裁判模型在每轮后检查；若未完成，Hermes 自动继续，直到完成、你暂停/清除，或达到轮次预算（默认 20）。子命令：`/goal status`、`/goal pause`、`/goal resume`、`/goal clear`。agent 运行中可安全执行 status/pause/clear；设置新目标需先执行 `/stop`。见 [持续目标](/user-guide/features/goals)。 |
+| `/goal <text>` | 设置一个持续目标，Hermes 将跨轮次持续推进——这是我们对 Ralph loop 的实现。裁判模型在每轮后检查；若未完成，Hermes 自动继续，直到完成、你暂停/清除，或达到轮次预算（默认 20）。子命令：`/goal status`、`/goal pause`、`/goal resume`、`/goal clear`。agent 运行中可安全执行 status/pause/clear；设置新目标需先执行 `/stop`。见 [持续目标](../user-guide/features/goals.md)。 |
 | `/footer [on\|off\|status]` | 切换最终回复中的运行时元数据页脚（显示模型、工具调用次数、耗时）。 |
 | `/curator [status\|run\|pin\|archive]` | 后台 skill 维护控制。 |
 | `/suggestions [accept\|dismiss N\|catalog\|clear]` | 直接在聊天中审核建议的自动化。`/suggestions` 列出待处理建议，`catalog` 添加精选起步自动化，`clear` 清理已解决的建议记录。被接受的建议会保留当前聊天/线程作为任务投递来源。 |
 | `/blueprint [name] [slot=value ...]` | 浏览 cron blueprint、启动引导式填槽对话，或直接创建 blueprint 任务。直接创建的任务会回投到当前聊天/线程。 |
-| `/memory [pending\|approve\|reject\|approval]` | 审核由写入审批门控（`memory.write_approval`）暂存的待处理 memory 写入——可直接在聊天中批准或拒绝——并通过 `/memory approval on\|off` 切换门控。见 [Memory 功能](/user-guide/features/memory)。 |
+| `/memory [pending\|approve\|reject\|approval]` | 审核由写入审批门控（`memory.write_approval`）暂存的待处理 memory 写入——可直接在聊天中批准或拒绝——并通过 `/memory approval on\|off` 切换门控。见 [Memory 功能](../user-guide/features/memory.md)。 |
 | `/skills [pending\|approve\|reject\|diff\|approval]` | 审核由写入审批门控（`skills.write_approval`）暂存的待处理 **skill** 写入。每条待写入会显示一行摘要；`/skills diff <id>` 在聊天中会截断——完整 diff 请在 CLI 或 `~/.hermes/pending/skills/<id>.json` 中查看。仅当门控开启（或仍有待处理写入）时出现；搜索/安装仍然是 CLI-only。 |
-| `/kanban <action>` | 从聊天中操作多 profile、多项目协作看板——参数与 CLI 完全一致。绕过运行中 agent 的保护，因此 `/kanban unblock t_abc`、`/kanban comment t_abc "…"`、`/kanban list --mine`、`/kanban boards switch <slug>` 等均可在轮次进行中使用。`/kanban create …` 会自动将发起聊天订阅到新任务的终态事件。见 [Kanban 斜杠命令](/user-guide/features/kanban#kanban-slash-command)。 |
+| `/kanban <action>` | 从聊天中操作多 profile、多项目协作看板——参数与 CLI 完全一致。绕过运行中 agent 的保护，因此 `/kanban unblock t_abc`、`/kanban comment t_abc "…"`、`/kanban list --mine`、`/kanban boards switch <slug>` 等均可在轮次进行中使用。`/kanban create …` 会自动将发起聊天订阅到新任务的终态事件。见 [Kanban 斜杠命令](../user-guide/features/kanban.md#kanban-slash-command)。 |
 | `/platform <list\|pause\|resume> [name]` | 直接在聊天中操作正在运行的 gateway 平台。`/platform list` 列出所有适配器及其状态（运行中、熔断器暂停、手动暂停）；`/platform pause <name>` 停止向该适配器分发新消息但不卸载它；`/platform resume <name>` 重新启用它，并在上游恢复健康后清除已触发的熔断器。 |
 | `/reload-mcp`（别名：`/reload_mcp`） | 从配置重新加载 MCP 服务器。 |
 | `/yolo` | 切换 YOLO 模式——跳过所有危险命令审批提示。 |
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/tools-reference.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/tools-reference.md
index 12c36c6f63..ba05df5496 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/tools-reference.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/tools-reference.md
@@ -11,7 +11,7 @@ description: "Hermes 内置工具权威参考，按工具集分组"
 **当前注册表快速统计：** 约 71 个工具 —— 10 个浏览器工具（核心）+ 2 个 CDP 门控浏览器工具、4 个文件工具、4 个 Home Assistant 工具、2 个终端工具、2 个 Web 工具、5 个 Feishu 工具、7 个 Spotify 工具（由内置 `spotify` 插件注册）、5 个 Yuanbao 工具、9 个 kanban 工具（在 kanban 调度器生成 agent 时注册）、2 个 Discord 工具，以及若干独立工具（`memory`、`clarify`、`delegate_task`、`execute_code`、`cronjob`、`session_search`、`skill_view`/`skill_manage`/`skills_list`、`text_to_speech`、`image_generate`、`video_generate`、`vision_analyze`、`video_analyze`、`send_message`、`todo`、`computer_use`、`process`）。
 
 :::tip MCP 工具
-除内置工具外，Hermes 还可从 MCP 服务器动态加载工具。MCP 工具以 `mcp_<server>_` 为前缀（例如，`github` MCP 服务器的 `mcp_github_create_issue`）。配置方法见 [MCP 集成](/user-guide/features/mcp)。
+除内置工具外，Hermes 还可从 MCP 服务器动态加载工具。MCP 工具以 `mcp_<server>_` 为前缀（例如，`github` MCP 服务器的 `mcp_github_create_issue`）。配置方法见 [MCP 集成](../user-guide/features/mcp.md)。
 :::
 
 ## `browser` 工具集
@@ -117,7 +117,7 @@ description: "Hermes 内置工具权威参考，按工具集分组"
 
 ## `kanban` 工具集
 
-在以下情况下注册：(a) agent 由 kanban 调度器生成（设置了 `HERMES_KANBAN_TASK` 环境变量），或 (b) 在显式启用 `kanban` 工具集的 profile 中运行。任务范围的 worker 使用生命周期工具处理其分配的任务；编排器 profile 还额外获得 `kanban_list` 和 `kanban_unblock` 等看板路由工具。完整工作流见 [Kanban 多 Agent](/user-guide/features/kanban)。
+在以下情况下注册：(a) agent 由 kanban 调度器生成（设置了 `HERMES_KANBAN_TASK` 环境变量），或 (b) 在显式启用 `kanban` 工具集的 profile 中运行。任务范围的 worker 使用生命周期工具处理其分配的任务；编排器 profile 还额外获得 `kanban_list` 和 `kanban_unblock` 等看板路由工具。完整工作流见 [Kanban 多 Agent](../user-guide/features/kanban.md)。
 
 | 工具 | 描述 | 所需环境 |
 |------|------|----------|
@@ -193,7 +193,7 @@ description: "Hermes 内置工具权威参考，按工具集分组"
 - **xAI Grok-Imagine** —— 文本生成视频和图片生成视频（SuperGrok OAuth 或 `XAI_API_KEY`）。
 - **FAL.ai** —— Veo 3.1、Pixverse v6、Kling O3（需要 `FAL_KEY`）。
 
-单个 `video_generate` 工具涵盖两种模态——传入 `image_url` 可为静态图片制作动画，省略则从文本生成。活跃后端自动路由到正确的端点。工具描述在会话启动时重建，以反映活跃后端的实际能力（模态、宽高比、分辨率、时长范围、最大参考图片数、音频支持）。后端开发见 [视频生成提供者插件](/developer-guide/video-gen-provider-plugin)。
+单个 `video_generate` 工具涵盖两种模态——传入 `image_url` 可为静态图片制作动画，省略则从文本生成。活跃后端自动路由到正确的端点。工具描述在会话启动时重建，以反映活跃后端的实际能力（模态、宽高比、分辨率、时长范围、最大参考图片数、音频支持）。后端开发见 [视频生成提供者插件](../developer-guide/video-gen-provider-plugin.md)。
 
 | 工具 | 描述 | 所需环境 |
 |------|------|----------|
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/bot-mode.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/bot-mode.md
index 98034ad28c..40c4547871 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/bot-mode.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/bot-mode.md
@@ -114,7 +114,7 @@ Routines 本质上就是命名空间为 `[bot:<name>] <routine>` 的普通 [Herm
 - **不是每个 Bot 都会回复每一条消息。** 是否发言由每个成员自己决定——一个 Bot 只有在有新内容可补充时才会回复，否则就跳过；@提及特定成员会把这一轮范围限定到他们身上。你可以预期被 @提及 的成员（或任何有话要说的成员）会发言，其余的保持安静。
 - **关闭 Desktop 后房间仍会继续运行。** 当一个房间的所有成员都位于同一个 gateway 上时，该 gateway 会通过一个持久的驱动器来负责轮次调度：关闭 Hermes Desktop（或失去它的连接）不会让讨论中途停止，Desktop 重新连接时只需从房间日志中补上进度即可。适用这种情况时，gateway 上的 `groups.capabilities` 会报告 `driver: true`。成员跨多台机器的房间则不同：每个成员的轮次运行在它自己的 gateway 上，*Bot 之间的消息*一节中描述的跨连接信使机制仍然适用于它们。
 - **房间可以跨越多台机器。** New Group Chat 选择器可以从任意已注册的连接中挑选 Bot；每个成员的发言都运行在它自己的机器上，在它自己那台机器的房间会话里。跨机器的成员在房间和其他成员的对话记录中都带有设备徽标（`dixie · Mac Mini`），消除歧义的 `@name-device` handle 在房间提及中同样有效——因此两台机器上同名的 agent 永远不会混淆。
-- **插件可以观察成员的工作。** 持久的房间日志会记录 `turn.started` 和 `turn.settled`；成员在这两者之间做的事情（工具、审批、流式文本）会通过 [`on_room_member_activity`](/user-guide/features/hooks#on_room_member_activity) 钩子投射给插件，并附带房间、成员和轮次坐标，因此社区客户端无需读取 Hermes 内部实现，就能在 Group Chat 之上构建工具卡片和实时成员状态。
+- **插件可以观察成员的工作。** 持久的房间日志会记录 `turn.started` 和 `turn.settled`；成员在这两者之间做的事情（工具、审批、流式文本）会通过 [`on_room_member_activity`](./features/hooks.md#on_room_member_activity) 钩子投射给插件，并附带房间、成员和轮次坐标，因此社区客户端无需读取 Hermes 内部实现，就能在 Group Chat 之上构建工具卡片和实时成员状态。
 
 ## Bot 之间的消息
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/cli.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/cli.md
index f08c16ce4e..ea43669f6b 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/cli.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/cli.md
@@ -160,7 +160,7 @@ quick_commands:
     target: /gateway restart
 ```
 
-然后在任意聊天中输入 `/status`、`/gpu` 或 `/restart`。更多示例参见[配置指南](/user-guide/configuration#quick-commands)。
+然后在任意聊天中输入 `/status`、`/gpu` 或 `/restart`。更多示例参见[配置指南](./configuration.md#quick-commands)。
 
 ## 启动时预加载 Skill
 
@@ -310,7 +310,7 @@ CLI 在 agent 工作时显示动态反馈：
   ┊ 📄 web_extract (2.1s)
 ```
 
-使用 `/verbose` 循环切换显示模式：`off → new → all → verbose`。该命令也可为消息平台启用——参见[配置](/user-guide/configuration#display-settings)。
+使用 `/verbose` 循环切换显示模式：`off → new → all → verbose`。该命令也可为消息平台启用——参见[配置](./configuration.md#display-settings)。
 
 ### 工具预览长度
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/configuration.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/configuration.md
index 2cdd9fbb77..9e86946da6 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/configuration.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/configuration.md
@@ -71,7 +71,7 @@ delegation:
 
 单个值中可以有多个引用：`url: "${HOST}:${PORT}"`。如果引用的变量未设置，占位符将保持原样（`${UNDEFINED_VAR}` 保持不变）。仅支持 `${VAR}` 语法 —— 裸 `$VAR` 不会被展开。
 
-关于 AI provider 设置（OpenRouter、Anthropic、Copilot、自定义端点、自托管 LLM、回退模型等），请参阅 [AI Providers](/integrations/providers)。
+关于 AI provider 设置（OpenRouter、Anthropic、Copilot、自定义端点、自托管 LLM、回退模型等），请参阅 [AI Providers](../integrations/providers.md)。
 
 ### Provider 超时
 
@@ -478,7 +478,7 @@ skills:
 hermes config set skills.config.myplugin.path ~/myplugin-data
 ```
 
-有关在您自己的技能中声明配置设置的详细信息，请参阅[创建技能 — 配置设置](/developer-guide/creating-skills#config-settings-configyaml)。
+有关在您自己的技能中声明配置设置的详细信息，请参阅[创建技能 — 配置设置](../developer-guide/creating-skills.md#config-settings-configyaml)。
 
 ### Agent 创建技能写入的守卫
 
@@ -687,7 +687,7 @@ agent:
 
 ## 上下文引擎
 
-上下文引擎控制在接近模型 token 限制时如何管理对话。内置的 `compressor` 引擎使用有损摘要（参见[上下文压缩](/developer-guide/context-compression-and-caching)）。插件引擎可以用替代策略替换它。
+上下文引擎控制在接近模型 token 限制时如何管理对话。内置的 `compressor` 引擎使用有损摘要（参见[上下文压缩](../developer-guide/context-compression-and-caching.md)）。插件引擎可以用替代策略替换它。
 
 ```yaml
 context:
@@ -703,7 +703,7 @@ context:
 
 插件引擎**永远不会自动激活** —— 您必须将 `context.engine` 显式设置为插件名称。可用引擎可以通过 `hermes plugins` → Provider Plugins → Context Engine 浏览和选择。
 
-有关内存插件的类似单选系统，请参阅[内存 Providers](/user-guide/features/memory-providers)。
+有关内存插件的类似单选系统，请参阅[内存 Providers](./features/memory-providers.md)。
 
 ## 迭代预算
 
@@ -719,7 +719,7 @@ agent:
 
 当迭代预算完全耗尽时，CLI 向用户显示通知：`⚠ Iteration budget reached (500/500) — response may be incomplete`。
 
-`agent.api_max_retries` 控制 Hermes 在回退 provider 切换启动**之前**对瞬时错误（速率限制、连接断开、5xx）重试 provider API 调用的次数。默认为 `3` —— 总共四次尝试。如果您配置了[回退 providers](/user-guide/features/fallback-providers) 并希望更快地故障转移，请将其降至 `0`，这样主 provider 上的第一个瞬时错误会立即切换到回退，而不是对不稳定的端点进行重试。
+`agent.api_max_retries` 控制 Hermes 在回退 provider 切换启动**之前**对瞬时错误（速率限制、连接断开、5xx）重试 provider API 调用的次数。默认为 `3` —— 总共四次尝试。如果您配置了[回退 providers](./features/fallback-providers.md) 并希望更快地故障转移，请将其降至 `0`，这样主 provider 上的第一个瞬时错误会立即切换到回退，而不是对不稳定的端点进行重试。
 
 ### API 超时
 
@@ -775,7 +775,7 @@ credential_pool_strategies:
   anthropic: least_used      # 始终选择使用最少的密钥
 ```
 
-选项：`fill_first`（默认）、`round_robin`、`least_used`、`random`。完整文档请参阅[凭据池](/user-guide/features/credential-pools)。
+选项：`fill_first`（默认）、`round_robin`、`least_used`、`random`。完整文档请参阅[凭据池](./features/credential-pools.md)。
 
 ## Prompt 缓存
 
@@ -783,7 +783,7 @@ credential_pool_strategies:
 
 对于**原生 Anthropic**、**OpenRouter** 和 **Nous Portal** 上的 Claude，Hermes 在系统提示词和技能块上附加带有 1 小时 TTL（`ttl: "1h"`）的 `cache_control` 断点。在新鲜的一小时内首次发送时按完整输入费率计费；同一小时内任何会话的后续发送以折扣缓存读取费率从缓存中提取。这意味着系统提示词、加载的技能内容以及任何长上下文包含的早期部分在第一个小时内跨 `hermes` 会话和分叉子 agent 被重用。
 
-Qwen Cloud（阿里巴巴 DashScope）上游将缓存 TTL 限制为 5 分钟，因此 Hermes 在那里使用 5 分钟断点 TTL。其他通过第三方的 Claude 路径（AWS Bedrock、Azure Foundry）回退到 provider 自己的缓存默认值。xAI Grok 使用单独的会话固定对话 ID 机制 —— 参阅 [xAI prompt 缓存](/integrations/providers#xai-grok--responses-api--prompt-caching)。
+Qwen Cloud（阿里巴巴 DashScope）上游将缓存 TTL 限制为 5 分钟，因此 Hermes 在那里使用 5 分钟断点 TTL。其他通过第三方的 Claude 路径（AWS Bedrock、Azure Foundry）回退到 provider 自己的缓存默认值。xAI Grok 使用单独的会话固定对话 ID 机制 —— 参阅 [xAI prompt 缓存](../integrations/providers.md#xai-grok--responses-api--prompt-caching)。
 
 不存在禁用此功能的旋钮 —— 缓存始终开启，即使在单轮对话中也能节省费用，因为仅系统提示词就占输入 token 数的相当大比例。
 
@@ -838,7 +838,7 @@ Hermes 中的每个模型槽位 —— 辅助任务、压缩、回退 —— 使
 
 当设置 `base_url` 时，Hermes 忽略 provider 并直接调用该端点（使用 `api_key` 或 `OPENAI_API_KEY` 进行认证）。当仅设置 `provider` 时，Hermes 使用该 provider 的内置认证和基础 URL。
 
-辅助任务的可用 providers：`auto`、`main`，以及[provider 注册表](/reference/environment-variables)中的任何 provider —— `openrouter`、`nous`、`openai-codex`、`copilot`、`copilot-acp`、`anthropic`、`gemini`、`qwen-oauth`、`zai`、`kimi-coding`、`kimi-coding-cn`、`minimax`、`minimax-cn`、`minimax-oauth`、`deepseek`、`nvidia`、`xai`、`xai-oauth`、`ollama-cloud`、`alibaba`、`bedrock`、`huggingface`、`arcee`、`xiaomi`、`kilocode`、`opencode-zen`、`opencode-go`、`ai-gateway`、`azure-foundry` —— 或您 `custom_providers` 列表中任何命名的自定义 provider（例如 `provider: "beans"`）。
+辅助任务的可用 providers：`auto`、`main`，以及[provider 注册表](../reference/environment-variables.md)中的任何 provider —— `openrouter`、`nous`、`openai-codex`、`copilot`、`copilot-acp`、`anthropic`、`gemini`、`qwen-oauth`、`zai`、`kimi-coding`、`kimi-coding-cn`、`minimax`、`minimax-cn`、`minimax-oauth`、`deepseek`、`nvidia`、`xai`、`xai-oauth`、`ollama-cloud`、`alibaba`、`bedrock`、`huggingface`、`arcee`、`xiaomi`、`kilocode`、`opencode-zen`、`opencode-go`、`ai-gateway`、`azure-foundry` —— 或您 `custom_providers` 列表中任何命名的自定义 provider（例如 `provider: "beans"`）。
 
 :::tip MiniMax OAuth
 `minimax-oauth` 通过浏览器 OAuth 登录（无需 API 密钥）。运行 `hermes model` 并选择 **MiniMax (OAuth)** 进行认证。辅助任务自动使用 `MiniMax-M2.7-highspeed`。参阅 [MiniMax OAuth 指南](../guides/minimax-oauth.md)。
@@ -849,12 +849,12 @@ Hermes 中的每个模型槽位 —— 辅助任务、压缩、回退 —— 使
 :::
 
 :::warning `"main"` 仅用于辅助任务
-`"main"` provider 选项表示"使用我的主 agent 使用的任何 provider" —— 它仅在 `auxiliary:`、`compression:` 和 `fallback_model:` 配置中有效。它**不是**顶级 `model.provider` 设置的有效值。如果您使用自定义 OpenAI 兼容端点，请在 `model:` 部分设置 `provider: custom`。所有主模型 provider 选项请参阅 [AI Providers](/integrations/providers)。
+`"main"` provider 选项表示"使用我的主 agent 使用的任何 provider" —— 它仅在 `auxiliary:`、`compression:` 和 `fallback_model:` 配置中有效。它**不是**顶级 `model.provider` 设置的有效值。如果您使用自定义 OpenAI 兼容端点，请在 `model:` 部分设置 `provider: custom`。所有主模型 provider 选项请参阅 [AI Providers](../integrations/providers.md)。
 :::
 
 如果端点直接拒绝推理字段（例如 OpenAI 兼容中继后面的纯聊天模型返回 `400 Unrecognized request argument supplied: reasoning_effort`），辅助调用会去掉所有推理字段重试一次，因此该任务（例如会话标题）仍会以端点的默认行为完成。
 
-**后台审查有所不同：** 与主会话使用同一模型的审查分支始终继承主会话的推理强度；`auxiliary.background_review.reasoning_effort` 在这条路径上不会生效，即使显式指定了主会话的 provider/model 也一样。推理设置、系统 prompt、完整会话快照和工具定义保持逐字节一致，以复用 prompt 缓存前缀。没有用于同模型审查的独立推理强度开关。详见[同模型审查的推理强度](/user-guide/features/memory#same-model-review-reasoning)。路由到其他模型时的独立问题见 [#94825](https://github.com/NousResearch/hermes-agent/issues/94825)。
+**后台审查有所不同：** 与主会话使用同一模型的审查分支始终继承主会话的推理强度；`auxiliary.background_review.reasoning_effort` 在这条路径上不会生效，即使显式指定了主会话的 provider/model 也一样。推理设置、系统 prompt、完整会话快照和工具定义保持逐字节一致，以复用 prompt 缓存前缀。没有用于同模型审查的独立推理强度开关。详见[同模型审查的推理强度](./features/memory.md#same-model-review-reasoning)。路由到其他模型时的独立问题见 [#94825](https://github.com/NousResearch/hermes-agent/issues/94825)。
 
 ### 完整辅助配置参考
 
@@ -922,7 +922,7 @@ auxiliary:
 :::
 
 :::info
-上下文压缩有自己的 `compression:` 块用于阈值，以及 `auxiliary.compression:` 块用于模型/provider 设置 —— 参阅上方的[上下文压缩](#context-compression)。主备用链使用顶层的 `fallback_providers:` 列表 —— 参阅[备用提供商](/integrations/providers#fallback-providers)。三者都遵循相同的 provider/model/base_url 模式。
+上下文压缩有自己的 `compression:` 块用于阈值，以及 `auxiliary.compression:` 块用于模型/provider 设置 —— 参阅上方的[上下文压缩](#context-compression)。主备用链使用顶层的 `fallback_providers:` 列表 —— 参阅[备用提供商](../integrations/providers.md#fallback-providers)。三者都遵循相同的 provider/model/base_url 模式。
 :::
 
 ### 辅助任务的每任务回退链
@@ -955,7 +955,7 @@ auxiliary:
 
 ### OpenRouter 路由和辅助任务的 Pareto Code
 
-当辅助任务解析到 OpenRouter（显式或通过 `provider: "main"` 而您的主 agent 在 OpenRouter 上）时，主 agent 的 `provider_routing` 和 `openrouter.min_coding_score` 设置**不会传播** —— 按设计，每个辅助任务是独立的。要为特定辅助任务设置 OpenRouter provider 偏好或使用 [Pareto Code 路由器](/integrations/providers#openrouter-pareto-code-router)，请通过 `extra_body` 按任务设置：
+当辅助任务解析到 OpenRouter（显式或通过 `provider: "main"` 而您的主 agent 在 OpenRouter 上）时，主 agent 的 `provider_routing` 和 `openrouter.min_coding_score` 设置**不会传播** —— 按设计，每个辅助任务是独立的。要为特定辅助任务设置 OpenRouter provider 偏好或使用 [Pareto Code 路由器](../integrations/providers.md#openrouter-pareto-code-router)，请通过 `extra_body` 按任务设置：
 
 ```yaml
 auxiliary:
@@ -1103,7 +1103,7 @@ auxiliary:
 
 ### 原生视觉嵌入预算（顶层 `vision:`）
 
-与 `auxiliary.vision`（选择描述器模型）不同：当*主*模型支持视觉时，`vision_analyze` 和浏览器截图会把真实像素嵌入工具结果，并在之后的每一轮请求中重复发送。`vision.embed_target_bytes`（默认 `262144`，限制在 64 KiB..4 MiB 之间）控制单次嵌入的大小；`vision.max_calls_per_image` 限制同一张图片在一个会话中可被嵌入的次数（未设置 = 委派子代理内为 3，主代理不限；`0` = 不限）。参见 [视觉 → 原生嵌入伴随整个会话](/user-guide/features/vision#原生嵌入伴随整个会话visionembed_target_bytes-与-visionmax_calls_per_image)。
+与 `auxiliary.vision`（选择描述器模型）不同：当*主*模型支持视觉时，`vision_analyze` 和浏览器截图会把真实像素嵌入工具结果，并在之后的每一轮请求中重复发送。`vision.embed_target_bytes`（默认 `262144`，限制在 64 KiB..4 MiB 之间）控制单次嵌入的大小；`vision.max_calls_per_image` 限制同一张图片在一个会话中可被嵌入的次数（未设置 = 委派子代理内为 3，主代理不限；`0` = 不限）。参见 [视觉 → 原生嵌入伴随整个会话](./features/vision.md#原生嵌入伴随整个会话visionembed_target_bytes-与-visionmax_calls_per_image)。
 
 ## 推理努力程度
 
@@ -1371,7 +1371,7 @@ voice:
   silence_duration: 3.0         # 自动停止前的静默秒数
 ```
 
-在 CLI 中使用 `/voice on` 启用麦克风模式，使用 `record_key` 开始/停止录音，使用 `/voice tts` 切换口语回复。端到端设置和平台特定行为请参阅[语音模式](/user-guide/features/voice-mode)。
+在 CLI 中使用 `/voice on` 启用麦克风模式，使用 `record_key` 开始/停止录音，使用 `/voice tts` 切换口语回复。端到端设置和平台特定行为请参阅[语音模式](./features/voice-mode.md)。
 
 ## 流式传输
 
@@ -1424,7 +1424,7 @@ group_sessions_per_user: true  # true = 群组/频道中每用户隔离，false
 - 私信不受影响。Hermes 仍然像往常一样通过聊天/DM ID 键入 DM。
 - 线程与其父频道保持隔离；使用 `true` 时，每个参与者在线程内也获得自己的会话。
 
-有关行为详情和示例，请参阅[会话](/user-guide/sessions)和 [Discord 指南](/user-guide/messaging/discord)。
+有关行为详情和示例，请参阅[会话](./sessions.md)和 [Discord 指南](./messaging/discord.md)。
 
 ## 未授权 DM 行为
 
@@ -1526,7 +1526,7 @@ web:
 
 **后端选择：** 如果未设置 `web.backend`，后端从可用的 API 密钥自动检测。如果仅设置了 `SEARXNG_URL`，使用 SearXNG。如果仅设置了 `EXA_API_KEY`，使用 Exa。如果仅设置了 `TAVILY_API_KEY`，使用 Tavily。如果仅设置了 `PARALLEL_API_KEY`，使用 Parallel。否则 Firecrawl 是默认值。
 
-**SearXNG** 是一个免费、自托管、尊重隐私的元搜索引擎，查询 70+ 个搜索引擎。无需 API 密钥 —— 只需将 `SEARXNG_URL` 设置为您的实例（例如 `http://localhost:8080`）。SearXNG 仅限搜索；`web_extract` 需要单独的提取 provider（设置 `web.extract_backend`）。Docker 设置说明请参阅 [Web 搜索设置指南](/user-guide/features/web-search)。
+**SearXNG** 是一个免费、自托管、尊重隐私的元搜索引擎，查询 70+ 个搜索引擎。无需 API 密钥 —— 只需将 `SEARXNG_URL` 设置为您的实例（例如 `http://localhost:8080`）。SearXNG 仅限搜索；`web_extract` 需要单独的提取 provider（设置 `web.extract_backend`）。Docker 设置说明请参阅 [Web 搜索设置指南](./features/web-search.md)。
 
 **自托管 Firecrawl：** 设置 `FIRECRAWL_API_URL` 指向您自己的实例。设置自定义 URL 后，API 密钥变为可选（在服务器上设置 `USE_DB_AUTHENTICATION=***` 以禁用认证）。
 
@@ -1566,7 +1566,7 @@ browser:
 
 完整对话框工作流请参阅[浏览器功能页面](./features/browser.md#browser_dialog)。
 
-浏览器工具集支持多个 provider。有关 Browserbase、Browser Use 和本地 Chromium 系 CDP 设置的详细信息，请参阅[浏览器功能页面](/user-guide/features/browser)。
+浏览器工具集支持多个 provider。有关 Browserbase、Browser Use 和本地 Chromium 系 CDP 设置的详细信息，请参阅[浏览器功能页面](./features/browser.md)。
 
 ## 时区
 
@@ -1668,7 +1668,7 @@ approvals:
 
 ## 检查点
 
-破坏性文件操作之前的自动文件系统快照。详情请参阅[检查点与回滚](/user-guide/checkpoints-and-rollback)。
+破坏性文件操作之前的自动文件系统快照。详情请参阅[检查点与回滚](./checkpoints-and-rollback.md)。
 
 ```yaml
 checkpoints:
@@ -1735,8 +1735,8 @@ Hermes 使用两种不同的上下文范围：
 - 所有加载的上下文文件上限为 20,000 字符，并进行智能截断。
 
 另请参阅：
-- [个性与 SOUL.md](/user-guide/features/personality)
-- [上下文文件](/user-guide/features/context-files)
+- [个性与 SOUL.md](./features/personality.md)
+- [上下文文件](./features/context-files.md)
 
 ## 工作目录
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/configuring-models.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/configuring-models.md
index 58d31c7d56..b5a430c481 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/configuring-models.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/configuring-models.md
@@ -12,7 +12,7 @@ Hermes 使用两类模型槽位：
 本页介绍如何通过仪表板配置上述两类模型。如需使用配置文件或 CLI，请跳至底部的[其他方法](#alternative-methods)。
 
 :::tip 最快路径：Nous Portal
-[Nous Portal](/user-guide/features/tool-gateway) 在单一订阅下提供 300+ 个模型。全新安装后，运行 `hermes setup --portal` 即可登录并一键将 Nous 设为提供商。使用 `hermes portal info` 查看当前配置。
+[Nous Portal](./features/tool-gateway.md) 在单一订阅下提供 300+ 个模型。全新安装后，运行 `hermes setup --portal` 即可登录并一键将 Nous 设为提供商。使用 `hermes portal info` 查看当前配置。
 :::
 
 ## Models 页面
@@ -186,7 +186,7 @@ hermes config set model.aliases.fav anthropic/claude-opus-4.6
 hermes config set model.aliases.grok x-ai/grok-4
 ```
 
-然后在聊天中使用 `/model fav` 或 `/model grok`。用户别名会覆盖内置短名称（`sonnet`、`kimi`、`opus` 等）。完整参考请见[自定义模型别名](/reference/slash-commands#custom-model-aliases)。
+然后在聊天中使用 `/model fav` 或 `/model grok`。用户别名会覆盖内置短名称（`sonnet`、`kimi`、`opus` 等）。完整参考请见[自定义模型别名](../reference/slash-commands.md#custom-model-aliases)。
 
 ### `hermes model` 子命令
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/docker.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/docker.md
index 8b1609ef12..3e8fc8c011 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/docker.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/docker.md
@@ -267,7 +267,7 @@ docker run -d \
 - Playwright 与 Chromium（`npx playwright install --with-deps chromium --only-shell`）
 - ripgrep、ffmpeg、git 和 `xz-utils` 作为系统工具
 - **`docker-cli`** — 使容器内运行的 agent 可以驱动宿主机的 Docker 守护进程（绑定挂载 `/var/run/docker.sock` 以启用），用于 `docker build`、`docker run`、容器检查等操作
-- **`openssh-client`** — 从容器内启用 [SSH 终端后端](/user-guide/configuration#ssh-backend)。SSH 后端调用系统 `ssh` 二进制文件；若缺少此组件，在容器化安装中会静默失败
+- **`openssh-client`** — 从容器内启用 [SSH 终端后端](./configuration.md#ssh-backend)。SSH 后端调用系统 `ssh` 二进制文件；若缺少此组件，在容器化安装中会静默失败
 - WhatsApp 桥接（`scripts/whatsapp-bridge/`）
 - **[`s6-overlay`](https://github.com/just-containers/s6-overlay) v3** 作为 PID 1（替代旧版 `tini`）——监管 dashboard 和各 profile gateway，崩溃后自动重启，回收僵尸子进程，并转发信号
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/api-server.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/api-server.md
index 490e957bf8..1896910b61 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/api-server.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/api-server.md
@@ -11,7 +11,7 @@ API 服务器将 hermes-agent 作为 OpenAI 兼容的 HTTP 端点暴露出来。
 你的 agent 使用完整工具集（终端、文件操作、网络搜索、记忆、技能）处理请求，并返回最终响应。在流式传输时，工具进度指示器会内联显示，让前端能够展示 agent 正在执行的操作。
 
 :::tip 一个后端同时覆盖模型与工具
-Hermes 本身需要配置好 provider（提供商）和工具后端，API 服务器才能发挥作用。[Nous Portal](/user-guide/features/tool-gateway) 订阅同时处理两者——300+ 个模型，以及通过 Tool Gateway 提供的网络/图像/TTS/浏览器功能。在启动 API 服务器之前运行一次 `hermes setup --portal`，Open WebUI 或 LobeChat 等前端即可获得一个完整配备工具的后端。
+Hermes 本身需要配置好 provider（提供商）和工具后端，API 服务器才能发挥作用。[Nous Portal](./tool-gateway.md) 订阅同时处理两者——300+ 个模型，以及通过 Tool Gateway 提供的网络/图像/TTS/浏览器功能。在启动 API 服务器之前运行一次 `hermes setup --portal`，Open WebUI 或 LobeChat 等前端即可获得一个完整配备工具的后端。
 :::
 
 ## 快速开始
@@ -51,7 +51,7 @@ curl http://localhost:8642/v1/chat/completions \
   -d '{"model": "hermes-agent", "messages": [{"role": "user", "content": "Hello!"}]}'
 ```
 
-或连接 Open WebUI、LobeChat 或其他任意前端——参见 [Open WebUI 集成指南](/user-guide/messaging/open-webui)获取分步说明。
+或连接 Open WebUI、LobeChat 或其他任意前端——参见 [Open WebUI 集成指南](../messaging/open-webui.md)获取分步说明。
 
 ## 端点
 
@@ -196,7 +196,7 @@ OpenAI Responses API 格式。通过 `previous_response_id` 支持服务端对
 
 ### GET /v1/models
 
-将 agent 列为可用模型。广播的模型名称默认为 [profile](/user-guide/profiles) 名称（默认 profile 则为 `hermes-agent`）。大多数前端进行模型发现时需要此端点。
+将 agent 列为可用模型。广播的模型名称默认为 [profile](../profiles.md) 名称（默认 profile 则为 `hermes-agent`）。大多数前端进行模型发现时需要此端点。
 
 ### GET /v1/capabilities
 
@@ -396,7 +396,7 @@ API_SERVER_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
 
 | 前端 | Stars | 连接方式 |
 |----------|-------|------------|
-| [Open WebUI](/user-guide/messaging/open-webui) | 126k | 提供完整指南 |
+| [Open WebUI](../messaging/open-webui.md) | 126k | 提供完整指南 |
 | LobeChat | 73k | 自定义 provider 端点 |
 | LibreChat | 34k | librechat.yaml 中的自定义端点 |
 | AnythingLLM | 56k | 通用 OpenAI provider |
@@ -410,7 +410,7 @@ API_SERVER_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
 
 ## 使用 Profiles 的多用户设置
 
-要为多个用户提供各自隔离的 Hermes 实例（独立的配置、记忆、技能），请使用 [profiles](/user-guide/profiles)：
+要为多个用户提供各自隔离的 Hermes 实例（独立的配置、记忆、技能），请使用 [profiles](../profiles.md)：
 
 ```bash
 # 为每个用户创建 profile
@@ -441,7 +441,7 @@ hermes -p bob gateway &
 - `http://localhost:8643/v1/models` → 模型 `alice`
 - `http://localhost:8644/v1/models` → 模型 `bob`
 
-在 Open WebUI 中，将每个添加为单独的连接。模型下拉列表显示 `alice` 和 `bob` 作为不同模型，每个均由完全隔离的 Hermes 实例支持。详见 [Open WebUI 指南](/user-guide/messaging/open-webui#multi-user-setup-with-profiles)。
+在 Open WebUI 中，将每个添加为单独的连接。模型下拉列表显示 `alice` 和 `bob` 作为不同模型，每个均由完全隔离的 Hermes 实例支持。详见 [Open WebUI 指南](../messaging/open-webui.md#multi-user-setup-with-profiles)。
 
 ## 限制
 
@@ -453,4 +453,4 @@ hermes -p bob gateway &
 
 API 服务器还作为 **gateway 代理模式**的后端。当另一个 Hermes gateway 实例配置了指向此 API 服务器的 `GATEWAY_PROXY_URL` 时，它会将所有消息转发到这里，而不是运行自己的 agent。这支持分离部署——例如，一个处理 Matrix E2EE 的 Docker 容器将请求中继到宿主机侧的 agent。
 
-完整设置指南参见 [Matrix 代理模式](/user-guide/messaging/matrix#proxy-mode-e2ee-on-macos)。
\ No newline at end of file
+完整设置指南参见 [Matrix 代理模式](../messaging/matrix.md#proxy-mode-e2ee-on-macos)。
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/batch-processing.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/batch-processing.md
index 6068a52c4a..a2d9c9a20b 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/batch-processing.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/batch-processing.md
@@ -35,7 +35,7 @@ python batch_runner.py --list_distributions
 ```
 
 :::tip 大规模运行下的可预测成本
-批量运行会启动大量并发 agent 会话，每个会话都会调用模型和工具。[Nous Portal](/user-guide/features/tool-gateway) 订阅将模型访问、网页搜索、图像生成、TTS 以及云端浏览器统一计费——当你希望在不同供应商账户间稳定控制每条轨迹成本、避免触碰速率限制时非常实用。使用 `hermes setup --portal` 完成配置，然后将 `--model` 指向 Nous 模型。
+批量运行会启动大量并发 agent 会话，每个会话都会调用模型和工具。[Nous Portal](./tool-gateway.md) 订阅将模型访问、网页搜索、图像生成、TTS 以及云端浏览器统一计费——当你希望在不同供应商账户间稳定控制每条轨迹成本、避免触碰速率限制时非常实用。使用 `hermes setup --portal` 完成配置，然后将 `--model` 指向 Nous 模型。
 :::
 
 ## 数据集格式
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/built-in-plugins.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/built-in-plugins.md
index 5ac19fae8f..7e7b9a2044 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/built-in-plugins.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/built-in-plugins.md
@@ -9,7 +9,7 @@ description: "随 Hermes Agent 附带并通过生命周期 hook 自动运行的
 
 Hermes 随仓库附带了一小组插件。它们位于 `<repo>/plugins/<name>/`，与用户安装在 `~/.hermes/plugins/` 中的插件一同自动加载。它们使用与第三方插件相同的插件接口——hook、工具、斜杠命令——只是在仓库内维护。
 
-请参阅 [插件](/user-guide/features/plugins) 页面了解通用插件系统，以及 [构建 Hermes 插件](/developer-guide/plugins) 了解如何编写自己的插件。
+请参阅 [插件](./plugins.md) 页面了解通用插件系统，以及 [构建 Hermes 插件](../../developer-guide/plugins/index.md) 了解如何编写自己的插件。
 
 ## 发现机制
 
@@ -253,7 +253,7 @@ agent 会启动会议加入流程，在通话进行时将转录内容流式传
 
 ## 添加内置插件
 
-内置插件的编写方式与其他 Hermes 插件完全相同——参见 [构建 Hermes 插件](/developer-guide/plugins)。唯一的区别是：
+内置插件的编写方式与其他 Hermes 插件完全相同——参见 [构建 Hermes 插件](../../developer-guide/plugins/index.md)。唯一的区别是：
 
 - 目录位于 `<repo>/plugins/<name>/`，而非 `~/.hermes/plugins/<name>/`
 - 在 `hermes plugins list` 中，manifest 来源显示为 `bundled`
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/code-execution.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/code-execution.md
index affe00131e..84c51914ae 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/code-execution.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/code-execution.md
@@ -217,7 +217,7 @@ terminal:
     - ANOTHER_TOKEN
 ```
 
-详情参见[安全指南](/user-guide/security#environment-variable-passthrough)。
+详情参见[安全指南](../security.md#environment-variable-passthrough)。
 
 Hermes 始终将脚本和自动生成的 `hermes_tools.py` RPC 存根写入临时暂存目录，执行完成后清理。在 `strict` 模式下，脚本也在该目录中*运行*；在 `project` 模式下，脚本在会话的工作目录中运行（暂存目录保留在 `PYTHONPATH` 中以确保导入正常解析）。子进程在独立的进程组中运行，以便在超时或中断时干净地终止。
 
@@ -231,7 +231,7 @@ Hermes 始终将脚本和自动生成的 `hermes_tools.py` RPC 存根写入临
 | 运行构建或测试套件 | ❌ | ✅ |
 | 对搜索结果进行循环处理 | ✅ | ❌ |
 | 交互式/后台进程 | ❌ | ✅ |
-| 需要环境变量中的 API key | ⚠️ 仅通过[透传](/user-guide/security#environment-variable-passthrough) | ✅（大多数可透传） |
+| 需要环境变量中的 API key | ⚠️ 仅通过[透传](../security.md#environment-variable-passthrough) | ✅（大多数可透传） |
 
 **经验法则：** 需要在调用之间含逻辑地程序化调用 Hermes 工具时，使用 `execute_code`。运行 shell 命令、构建和进程时，使用 `terminal`。
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/context-files.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/context-files.md
index a9116b46ea..e2a0a0b75a 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/context-files.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/context-files.md
@@ -79,7 +79,7 @@ This is a Next.js 14 web application with a Python FastAPI backend.
 
 ## SOUL.md
 
-`SOUL.md` 控制 agent 的个性、语气和沟通风格。完整详情请参阅[个性](/user-guide/features/personality)页面。
+`SOUL.md` 控制 agent 的个性、语气和沟通风格。完整详情请参阅[个性](./personality.md)页面。
 
 **位置：**
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/cron.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/cron.md
index 31c2452c86..42061f325e 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/cron.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/cron.md
@@ -18,7 +18,7 @@ Cron 任务可以：
 - 将结果回传到来源会话、本地文件或已配置的平台目标
 - 在全新的 agent 会话中运行，使用正常的静态工具列表
 - 以**无 agent 模式**运行——按计划执行脚本，其 stdout 原样投递，零 LLM 参与（参见下方[无 agent 模式](#no-agent-mode-script-only-jobs)章节）
-- 由**外部事件触发**——设置了 `cron_job` 的 webhook 路由会在事情发生的那一刻（PR 收到反馈、服务发出告警）立即触发任务，而不是等待下一次定时 tick。参见[事件触发的 Cron 任务](/user-guide/messaging/webhooks#event-triggered-cron-jobs)。
+- 由**外部事件触发**——设置了 `cron_job` 的 webhook 路由会在事情发生的那一刻（PR 收到反馈、服务发出告警）立即触发任务，而不是等待下一次定时 tick。参见[事件触发的 Cron 任务](../messaging/webhooks.md#event-triggered-cron-jobs)。
 
 所有这些功能均可通过 `cronjob` 工具由 Hermes 自身使用，因此你可以用自然语言创建、暂停、编辑和删除任务——无需 CLI。
 
@@ -463,7 +463,7 @@ cronjob(action="create", schedule="every 5m",
 
 当消息内容完全由脚本决定时（看门狗、阈值告警、心跳），它会自动选择 `no_agent=True`。同一工具也让 agent 可以暂停、恢复、编辑和删除任务——整个生命周期都通过聊天驱动，无需任何人接触 CLI。
 
-参见[纯脚本 Cron 任务指南](/guides/cron-script-only)获取实际示例。
+参见[纯脚本 Cron 任务指南](../../guides/cron-script-only.md)获取实际示例。
 
 ## 通过 `context_from` 串联任务
 
@@ -525,7 +525,7 @@ cronjob(
 Cron 任务继承你配置的回退 provider 和凭证池轮换。如果主 API key 被限速或 provider 返回错误，cron agent 可以：
 
 - **回退到备用 provider**，前提是你在 `config.yaml` 中配置了 `fallback_providers`（或旧版 `fallback_model`）
-- **轮换到下一个凭证**，即同一 provider 的[凭证池](/user-guide/configuration#credential-pool-strategies)中的下一个
+- **轮换到下一个凭证**，即同一 provider 的[凭证池](../configuration.md#credential-pool-strategies)中的下一个
 
 这意味着高频运行或在高峰时段运行的 cron 任务更具弹性——单个被限速的 key 不会导致整次运行失败。
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/curator.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/curator.md
index 2a5d51008e..1a69a22695 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/curator.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/curator.md
@@ -8,7 +8,7 @@ description: "Agent 创建的技能的后台维护——使用跟踪、过期检
 
 Curator 是针对 **agent 创建的技能**的后台维护流程。它跟踪每个技能被查看、使用和修补的频率，将长期未使用的技能经历 `active → stale → archived` 状态流转，并定期启动一个短暂的辅助模型审查，提出合并或修补漂移的建议。
 
-它的存在是为了防止通过[自我改进循环](/user-guide/features/skills#agent-managed-skills-skill_manage-tool)创建的技能无限堆积。每次 agent 解决新问题并保存技能时，该技能都会落入 `~/.hermes/skills/`。若没有维护，最终会出现数十个范围狭窄的近似重复项，污染技能目录并浪费 token（令牌）。
+它的存在是为了防止通过[自我改进循环](./skills.md#agent-managed-skills-skill_manage-tool)创建的技能无限堆积。每次 agent 解决新问题并保存技能时，该技能都会落入 `~/.hermes/skills/`。若没有维护，最终会出现数十个范围狭窄的近似重复项，污染技能目录并浪费 token（令牌）。
 
 默认情况下（`prune_builtins: true`），Curator 在 `archive_after_days` 天未使用后，可以归档**未使用的捆绑内置技能**（随仓库附带），与它主要管理的 agent 自创技能一并处理。通过 [agentskills.io](https://agentskills.io) 安装的 hub 技能始终不受影响。设置 `curator.prune_builtins: false` 可恢复旧的“仅 agent 自创”行为，此时捆绑技能绝不会被触碰。Curator 也**绝不自动删除**——最坏的结果是归档到 `~/.hermes/skills/.archive/`，这是可恢复的。
 
@@ -242,7 +242,7 @@ Curator 在 `min_idle_hours` 未经过时也会拒绝运行，因此在活跃的
 
 ## 另请参阅
 
-- [技能系统](/user-guide/features/skills)——技能的总体工作原理及创建技能的自我改进循环
-- [内存](/user-guide/features/memory)——维护长期记忆的并行后台审查
-- [捆绑技能目录](/reference/skills-catalog)
+- [技能系统](./skills.md)——技能的总体工作原理及创建技能的自我改进循环
+- [内存](./memory.md)——维护长期记忆的并行后台审查
+- [捆绑技能目录](../../reference/skills-catalog.md)
 - [Issue #7816](https://github.com/NousResearch/hermes-agent/issues/7816)——原始提案与设计讨论
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/delegation.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/delegation.md
index ee35ae5e81..571053d513 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/delegation.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/delegation.md
@@ -264,7 +264,7 @@ TUI 提供 `/agents` 浮层（别名 `/tasks`），将递归 `delegate_task` 扇
 
 在经典 CLI 和 TUI 中按 **F7**，可将实时栏折叠为单行摘要，再按一次恢复多行预览。单行保留运行数量和展开/恢复提示，空间允许时显示活动。输入和发送不受影响；关闭监视器后保留草稿及光标位置。此选项不写入配置。
 
-经典 CLI 的 `/agents` 和 `/tasks` 仍打印文本摘要；父智能体忙碌时可直接按 **F6** 打开交互式监视器。参见 [TUI — 斜杠命令](/user-guide/tui#slash-commands)。
+经典 CLI 的 `/agents` 和 `/tasks` 仍打印文本摘要；父智能体忙碌时可直接按 **F6** 打开交互式监视器。参见 [TUI — 斜杠命令](../tui.md#slash-commands)。
 
 ## 深度限制与嵌套编排 {#depth-limit-and-nested-orchestration}
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/fallback-providers.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/fallback-providers.md
index 7906b74da8..183d069c23 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/fallback-providers.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/fallback-providers.md
@@ -262,7 +262,7 @@ fallback_model:
 
 ### 辅助任务的提供商选项
 
-以下选项仅适用于 `auxiliary:`、`compression:` 和 `fallback_model:` 配置——`"main"` **不是**顶层 `model.provider` 的有效值。对于自定义端点，请在 `model:` 部分使用 `provider: custom`（参见 [AI 提供商](/integrations/providers)）。
+以下选项仅适用于 `auxiliary:`、`compression:` 和 `fallback_model:` 配置——`"main"` **不是**顶层 `model.provider` 的有效值。对于自定义端点，请在 `model:` 部分使用 `provider: custom`（参见 [AI 提供商](../../integrations/providers.md)）。
 
 | 提供商 | 说明 | 要求 |
 |----------|-------------|-------------|
@@ -369,7 +369,7 @@ delegation:
   # api_key: "local-key"
 ```
 
-完整配置详情参见[子 Agent 委派](/user-guide/features/delegation)。
+完整配置详情参见[子 Agent 委派](./delegation.md)。
 
 ---
 
@@ -387,7 +387,7 @@ cronjob(
 )
 ```
 
-完整配置详情参见[定时任务（Cron）](/user-guide/features/cron)。
+完整配置详情参见[定时任务（Cron）](./cron.md)。
 
 ---
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/goals.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/goals.md
index 5a36234ceb..11c8118ef9 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/goals.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/goals.md
@@ -118,7 +118,7 @@ goals:
 
 ### 选择裁判模型
 
-裁判使用 `goal_judge` 辅助任务。默认情况下，它解析为你的主模型（参见[辅助模型](/user-guide/configuration#auxiliary-models)）。若想将裁判路由到廉价快速的模型以降低成本，可添加覆盖配置：
+裁判使用 `goal_judge` 辅助任务。默认情况下，它解析为你的主模型（参见[辅助模型](../configuration.md#auxiliary-models)）。若想将裁判路由到廉价快速的模型以降低成本，可添加覆盖配置：
 
 ```yaml
 auxiliary:
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/hooks.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/hooks.md
index a169b6aed7..dc590b3938 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/hooks.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/hooks.md
@@ -11,7 +11,7 @@ Hermes 有四套 hook 系统，可在关键生命周期节点运行自定义代
 | 系统 | 注册方式 | 运行环境 | 使用场景 |
 |------|---------|---------|---------|
 | **[Gateway hooks](#gateway-event-hooks)** | `~/.hermes/hooks/` 下的 `HOOK.yaml` + `handler.py` | 仅 Gateway | 日志、告警、webhook |
-| **[Plugin hooks](#plugin-hooks)** | [插件](/user-guide/features/plugins)中的 `ctx.register_hook()` | CLI + Gateway | 工具拦截、指标采集、护栏 |
+| **[Plugin hooks](#plugin-hooks)** | [插件](./plugins.md)中的 `ctx.register_hook()` | CLI + Gateway | 工具拦截、指标采集、护栏 |
 | **[Shell hooks](#shell-hooks)** | `~/.hermes/config.yaml` 中 `hooks:` 块指向的 shell 脚本 | CLI + Gateway | 用于阻断、自动格式化、上下文注入的即插即用脚本 |
 | **[Outbound webhooks](#outbound-webhooks)** | `~/.hermes/config.yaml` 中的 `hooks.outbound:` 列表 | CLI + Gateway | 将签名后的生命周期事件推送到外部 HTTP endpoint |
 
@@ -352,7 +352,7 @@ Gateway hooks 仅在 **gateway**（Telegram、Discord、Slack、WhatsApp、Teams
 
 ## Plugin Hooks
 
-[插件](/user-guide/features/plugins)可以注册在 **CLI 和 gateway** 会话中均会触发的 hook。这些 hook 通过插件 `register()` 函数中的 `ctx.register_hook()` 以编程方式注册。
+[插件](./plugins.md)可以注册在 **CLI 和 gateway** 会话中均会触发的 hook。这些 hook 通过插件 `register()` 函数中的 `ctx.register_hook()` 以编程方式注册。
 
 ```python
 def register(ctx):
@@ -820,7 +820,7 @@ def my_callback(session_id: str, platform: str, **kwargs):
 
 ---
 
-参见 **[构建插件指南](/developer-guide/plugins)**，获取包含工具 schema、处理器和高级 hook 模式的完整演练。
+参见 **[构建插件指南](../../developer-guide/plugins/index.md)**，获取包含工具 schema、处理器和高级 hook 模式的完整演练。
 
 ---
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/kanban.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/kanban.md
index 0c78159f7c..17d331e5ff 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/kanban.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/kanban.md
@@ -745,7 +745,7 @@ hermes kanban notify-unsubscribe t_abcd \
 ### 多 profile 部署：投递按 profile 归属
 
 在每个 profile 一个 gateway 的部署中（单一调度器，`writer`、`admin` 等各自
-运行独立的 gateway 进程 —— 参见[多 gateway 指南](/user-guide/features/kanban-multi-gateway)），
+运行独立的 gateway 进程 —— 参见[多 gateway 指南](./kanban-multi-gateway.md)），
 调度与投递的归属是分开的：
 
 - **调度保持单一所有者。** 只有一个 gateway 保持
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/mcp.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/mcp.md
index 24e745cbf9..5fefb5c190 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/mcp.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/mcp.md
@@ -585,7 +585,7 @@ MCP 服务器直接从 Hermes 的会话存储（`~/.hermes/sessions/sessions.jso
 
 ## 相关文档
 
-- [在 Hermes 中使用 MCP](/guides/use-mcp-with-hermes)
-- [CLI 命令](/reference/cli-commands)
-- [斜杠命令](/reference/slash-commands)
-- [常见问题](/reference/faq)
\ No newline at end of file
+- [在 Hermes 中使用 MCP](../../guides/use-mcp-with-hermes.md)
+- [CLI 命令](../../reference/cli-commands.md)
+- [斜杠命令](../../reference/slash-commands.md)
+- [常见问题](../../reference/faq.md)
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/memory-providers.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/memory-providers.md
index dfe9d5d46f..375024b6c0 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/memory-providers.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/memory-providers.md
@@ -558,7 +558,7 @@ Base URL 优先级为 `supermemory.json` → `SUPERMEMORY_BASE_URL` → `https:/
 
 ## Profile 隔离
 
-每个提供者的数据按 [profile](/user-guide/profiles) 隔离：
+每个提供者的数据按 [profile](../profiles.md) 隔离：
 
 - **本地存储提供者**（Holographic、ByteRover）使用 `$HERMES_HOME/` 路径，各 profile 路径不同
 - **配置文件提供者**（Honcho、Mem0、Hindsight、Supermemory）将配置存储在 `$HERMES_HOME/` 中，每个 profile 拥有独立凭证
@@ -567,4 +567,4 @@ Base URL 优先级为 `supermemory.json` → `SUPERMEMORY_BASE_URL` → `https:/
 
 ## 构建记忆提供者
 
-参见[开发者指南：Memory Provider 插件](/developer-guide/memory-provider-plugin)了解如何创建自己的提供者。
+参见[开发者指南：Memory Provider 插件](../../developer-guide/memory-provider-plugin.md)了解如何创建自己的提供者。
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/memory.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/memory.md
index 0797b619a2..909980f057 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/memory.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/memory.md
@@ -185,7 +185,7 @@ located at ~/code/api. I discovered it uses Go version 1.22 and...
 hermes sessions list    # 浏览过去的会话
 ```
 
-有关三种调用形式（发现 / 滚动 / 浏览）和响应格式，请参阅[会话搜索工具](/user-guide/sessions#session-search-tool)。
+有关三种调用形式（发现 / 滚动 / 浏览）和响应格式，请参阅[会话搜索工具](../sessions.md#session-search-tool)。
 
 ### session_search 与 memory 的对比
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/personality.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/personality.md
index c3b0a9e430..6482c71df8 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/personality.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/personality.md
@@ -256,10 +256,10 @@ agent:
 
 ## 相关文档
 
-- [上下文文件](/user-guide/features/context-files)
-- [配置](/user-guide/configuration)
-- [技巧与最佳实践](/guides/tips)
-- [SOUL.md 指南](/guides/use-soul-with-hermes)
+- [上下文文件](./context-files.md)
+- [配置](../configuration.md)
+- [技巧与最佳实践](../../guides/tips.md)
+- [SOUL.md 指南](../../guides/use-soul-with-hermes.md)
 
 ## CLI 外观与对话个性
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/plugins.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/plugins.md
index 1ae944e222..8f15ef9bdd 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/plugins.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/plugins.md
@@ -10,9 +10,9 @@ description: "通过插件系统为 Hermes 添加自定义工具、hook 和集
 Hermes 提供了一套插件系统，可在不修改核心代码的情况下添加自定义工具、hook（钩子）和集成。
 
 如果你想为自己、团队或某个项目创建自定义工具，这通常是正确的路径。开发者指南中的
-[Adding Tools](/developer-guide/adding-tools) 页面针对的是存放在 `tools/` 和 `toolsets.py` 中的 Hermes 内置核心工具。
+[Adding Tools](../../developer-guide/adding-tools.md) 页面针对的是存放在 `tools/` 和 `toolsets.py` 中的 Hermes 内置核心工具。
 
-**→ [构建 Hermes Plugin](/developer-guide/plugins)** — 包含完整可运行示例的分步指南。
+**→ [构建 Hermes Plugin](../../developer-guide/plugins/index.md)** — 包含完整可运行示例的分步指南。
 
 ## 快速概览
 
@@ -106,23 +106,23 @@ def register(ctx):
 | 打包 skill | `ctx.register_skill(name, path)` — 命名空间为 `plugin:skill`，通过 `skill_view("plugin:skill")` 加载 |
 | 按环境变量控制 | 在 plugin.yaml 中设置 `requires_env: [API_KEY]` — 在 `hermes plugins install` 时提示输入 |
 | 通过 pip 分发 | `[project.entry-points."hermes_agent.plugins"]` |
-| 注册 gateway 平台（Discord、Telegram、IRC 等） | `ctx.register_platform(name, label, adapter_factory, check_fn, ...)` — 参见 [Adding Platform Adapters](/developer-guide/adding-platform-adapters) |
-| 注册图像生成后端 | `ctx.register_image_gen_provider(provider)` — 参见 [Image Generation Provider Plugins](/developer-guide/image-gen-provider-plugin) |
-| 注册视频生成后端 | `ctx.register_video_gen_provider(provider)` — 参见 [Video Generation Provider Plugins](/developer-guide/video-gen-provider-plugin) |
-| 注册上下文压缩引擎 | `ctx.register_context_engine(engine)` — 参见 [Context Engine Plugins](/developer-guide/context-engine-plugin) |
-| 注册 memory 后端 | 在 `plugins/memory/<name>/__init__.py` 中继承 `MemoryProvider` — 参见 [Memory Provider Plugins](/developer-guide/memory-provider-plugin)（使用独立发现系统） |
-| 调用宿主 LLM | `ctx.llm.complete(...)` / `ctx.llm.complete_structured(...)` — 借用用户当前激活的模型和认证，进行一次性补全，支持可选 JSON schema 验证。参见 [Plugin LLM Access](/developer-guide/plugin-llm-access) |
-| 注册推理后端（LLM provider） | 在 `plugins/model-providers/<name>/__init__.py` 中调用 `register_provider(ProviderProfile(...))` — 参见 [Model Provider Plugins](/developer-guide/model-provider-plugin)（使用独立发现系统） |
+| 注册 gateway 平台（Discord、Telegram、IRC 等） | `ctx.register_platform(name, label, adapter_factory, check_fn, ...)` — 参见 [Adding Platform Adapters](../../developer-guide/adding-platform-adapters.md) |
+| 注册图像生成后端 | `ctx.register_image_gen_provider(provider)` — 参见 [Image Generation Provider Plugins](../../developer-guide/image-gen-provider-plugin.md) |
+| 注册视频生成后端 | `ctx.register_video_gen_provider(provider)` — 参见 [Video Generation Provider Plugins](../../developer-guide/video-gen-provider-plugin.md) |
+| 注册上下文压缩引擎 | `ctx.register_context_engine(engine)` — 参见 [Context Engine Plugins](../../developer-guide/context-engine-plugin.md) |
+| 注册 memory 后端 | 在 `plugins/memory/<name>/__init__.py` 中继承 `MemoryProvider` — 参见 [Memory Provider Plugins](../../developer-guide/memory-provider-plugin.md)（使用独立发现系统） |
+| 调用宿主 LLM | `ctx.llm.complete(...)` / `ctx.llm.complete_structured(...)` — 借用用户当前激活的模型和认证，进行一次性补全，支持可选 JSON schema 验证。参见 [Plugin LLM Access](../../developer-guide/plugin-llm-access.md) |
+| 注册推理后端（LLM provider） | 在 `plugins/model-providers/<name>/__init__.py` 中调用 `register_provider(ProviderProfile(...))` — 参见 [Model Provider Plugins](../../developer-guide/model-provider-plugin.md)（使用独立发现系统） |
 
 ## 插件发现
 
 | 来源 | 路径 | 使用场景 |
 |--------|------|----------|
-| 内置 | `<repo>/plugins/` | 随 Hermes 附带 — 参见 [Built-in Plugins](/user-guide/features/built-in-plugins) |
+| 内置 | `<repo>/plugins/` | 随 Hermes 附带 — 参见 [Built-in Plugins](./built-in-plugins.md) |
 | 用户 | `~/.hermes/plugins/` | 个人插件 |
 | 项目 | `.hermes/plugins/` | 项目专属插件（需要 `HERMES_ENABLE_PROJECT_PLUGINS=true`） |
 | pip | `hermes_agent.plugins` entry_points | 分发包 |
-| Nix | `services.hermes-agent.extraPlugins` / `extraPythonPackages` | NixOS 声明式安装 — 参见 [Nix Setup](/getting-started/nix-setup#plugins) |
+| Nix | `services.hermes-agent.extraPlugins` / `extraPythonPackages` | NixOS 声明式安装 — 参见 [Nix Setup](../../getting-started/nix-setup.md#plugins) |
 
 名称冲突时，后面的来源会覆盖前面的，因此与内置插件同名的用户插件会替换它。
 
@@ -188,7 +188,7 @@ hermes plugins disable <name>     # 从允许列表移除并添加到禁用列
 
 ## 可用 hook
 
-插件可注册 `hermes_cli.plugins.VALID_HOOKS` 当前接受的 24 个生命周期事件。**[Event Hooks 目录](/user-guide/features/hooks#已发布的-plugin-hook-目录)**是精确触发时机、返回值处理、payload 字段和隐私说明的 canonical reference。
+插件可注册 `hermes_cli.plugins.VALID_HOOKS` 当前接受的 24 个生命周期事件。**[Event Hooks 目录](./hooks.md#已发布的-plugin-hook-目录)**是精确触发时机、返回值处理、payload 字段和隐私说明的 canonical reference。
 
 | 描述性类别 | 已发布 hook |
 |---|---|
@@ -217,23 +217,23 @@ Memory provider 和 context engine 是 **provider 插件** — 每种类型同
 
 | 想要添加… | 方式 | 编写指南 |
 |---|---|---|
-| LLM 可调用的**工具** | Python 插件 — `ctx.register_tool()` | [Build a Hermes Plugin](/developer-guide/plugins) · [Adding Tools](/developer-guide/adding-tools) |
-| **生命周期 hook**（LLM 前后、会话开始/结束、工具过滤） | Python 插件 — `ctx.register_hook()` | [Hooks reference](/user-guide/features/hooks) · [Build a Hermes Plugin](/developer-guide/plugins) |
-| CLI / gateway 的**斜杠命令** | Python 插件 — `ctx.register_command()` | [Build a Hermes Plugin](/developer-guide/plugins) · [Extending the CLI](/developer-guide/extending-the-cli) |
-| `hermes <thing>` 的**子命令** | Python 插件 — `ctx.register_cli_command()` | [Extending the CLI](/developer-guide/extending-the-cli) |
-| 插件附带的**skill** | Python 插件 — `ctx.register_skill()` | [Creating Skills](/developer-guide/creating-skills) |
-| **推理后端**（LLM provider：OpenAI 兼容、Codex、Anthropic-Messages、Bedrock） | Provider 插件 — 在 `plugins/model-providers/<name>/` 中调用 `register_provider(ProviderProfile(...))` | **[Model Provider Plugins](/developer-guide/model-provider-plugin)** · [Adding Providers](/developer-guide/adding-providers) |
-| **Gateway 频道**（Discord / Telegram / IRC / Teams 等） | 平台插件 — 在 `plugins/platforms/<name>/` 中调用 `ctx.register_platform()` | [Adding Platform Adapters](/developer-guide/adding-platform-adapters) |
-| **Memory 后端**（Honcho、Mem0、Supermemory 等） | Memory 插件 — 在 `plugins/memory/<name>/` 中继承 `MemoryProvider` | [Memory Provider Plugins](/developer-guide/memory-provider-plugin) |
-| **上下文压缩策略** | Context-engine 插件 — `ctx.register_context_engine()` | [Context Engine Plugins](/developer-guide/context-engine-plugin) |
-| **图像生成后端**（DALL·E、SDXL 等） | 后端插件 — `ctx.register_image_gen_provider()` | [Image Generation Provider Plugins](/developer-guide/image-gen-provider-plugin) |
-| **视频生成后端**（Veo、Kling、Pixverse、Grok-Imagine、Runway 等） | 后端插件 — `ctx.register_video_gen_provider()` | [Video Generation Provider Plugins](/developer-guide/video-gen-provider-plugin) |
-| **TTS 后端**（任意 CLI — Piper、VoxCPM、Kokoro、xtts、语音克隆脚本等） | 配置驱动（推荐）— 在 `config.yaml` 的 `tts.providers.<name>` 下以 `type: command` 声明。或 Python 后端插件 — 对需要超出 shell 模板的 Python SDK / 流式引擎使用 `ctx.register_tts_provider()`。 | [TTS Setup](/user-guide/features/tts#custom-command-providers) · [Python plugin guide](/user-guide/features/tts#python-plugin-providers) |
-| **STT 后端**（自定义 whisper 二进制、本地 ASR CLI） | 配置驱动 — 将 `HERMES_LOCAL_STT_COMMAND` 环境变量设置为 shell 模板 | [Voice Message Transcription (STT)](/user-guide/features/tts#voice-message-transcription-stt) |
-| **通过 MCP 使用外部工具**（文件系统、GitHub、Linear、Notion、任意 MCP 服务器） | 配置驱动 — 在 `config.yaml` 中以 `command:` / `url:` 声明 `mcp_servers.<name>`。Hermes 自动发现服务器的工具并与内置工具一同注册。 | [MCP](/user-guide/features/mcp) |
-| **额外 skill 来源**（自定义 GitHub 仓库、私有 skill 索引） | CLI — `hermes skills tap add <repo>` | [Skills Hub](/user-guide/features/skills#skills-hub) · [发布自定义 tap](/user-guide/features/skills#publishing-a-custom-skill-tap) |
-| **Gateway 事件 hook**（在 `gateway:startup`、`session:start`、`agent:end`、`command:*` 时触发） | 将 `HOOK.yaml` + `handler.py` 放入 `~/.hermes/hooks/<name>/` | [Event Hooks](/user-guide/features/hooks#gateway-event-hooks) |
-| **Shell hook**（在事件时运行 shell 命令 — 通知、审计日志、桌面提醒） | 配置驱动 — 在 `config.yaml` 的 `hooks:` 下声明 | [Shell Hooks](/user-guide/features/hooks#shell-hooks) |
+| LLM 可调用的**工具** | Python 插件 — `ctx.register_tool()` | [Build a Hermes Plugin](../../developer-guide/plugins/index.md) · [Adding Tools](../../developer-guide/adding-tools.md) |
+| **生命周期 hook**（LLM 前后、会话开始/结束、工具过滤） | Python 插件 — `ctx.register_hook()` | [Hooks reference](./hooks.md) · [Build a Hermes Plugin](../../developer-guide/plugins/index.md) |
+| CLI / gateway 的**斜杠命令** | Python 插件 — `ctx.register_command()` | [Build a Hermes Plugin](../../developer-guide/plugins/index.md) · [Extending the CLI](../../developer-guide/extending-the-cli.md) |
+| `hermes <thing>` 的**子命令** | Python 插件 — `ctx.register_cli_command()` | [Extending the CLI](../../developer-guide/extending-the-cli.md) |
+| 插件附带的**skill** | Python 插件 — `ctx.register_skill()` | [Creating Skills](../../developer-guide/creating-skills.md) |
+| **推理后端**（LLM provider：OpenAI 兼容、Codex、Anthropic-Messages、Bedrock） | Provider 插件 — 在 `plugins/model-providers/<name>/` 中调用 `register_provider(ProviderProfile(...))` | **[Model Provider Plugins](../../developer-guide/model-provider-plugin.md)** · [Adding Providers](../../developer-guide/adding-providers.md) |
+| **Gateway 频道**（Discord / Telegram / IRC / Teams 等） | 平台插件 — 在 `plugins/platforms/<name>/` 中调用 `ctx.register_platform()` | [Adding Platform Adapters](../../developer-guide/adding-platform-adapters.md) |
+| **Memory 后端**（Honcho、Mem0、Supermemory 等） | Memory 插件 — 在 `plugins/memory/<name>/` 中继承 `MemoryProvider` | [Memory Provider Plugins](../../developer-guide/memory-provider-plugin.md) |
+| **上下文压缩策略** | Context-engine 插件 — `ctx.register_context_engine()` | [Context Engine Plugins](../../developer-guide/context-engine-plugin.md) |
+| **图像生成后端**（DALL·E、SDXL 等） | 后端插件 — `ctx.register_image_gen_provider()` | [Image Generation Provider Plugins](../../developer-guide/image-gen-provider-plugin.md) |
+| **视频生成后端**（Veo、Kling、Pixverse、Grok-Imagine、Runway 等） | 后端插件 — `ctx.register_video_gen_provider()` | [Video Generation Provider Plugins](../../developer-guide/video-gen-provider-plugin.md) |
+| **TTS 后端**（任意 CLI — Piper、VoxCPM、Kokoro、xtts、语音克隆脚本等） | 配置驱动（推荐）— 在 `config.yaml` 的 `tts.providers.<name>` 下以 `type: command` 声明。或 Python 后端插件 — 对需要超出 shell 模板的 Python SDK / 流式引擎使用 `ctx.register_tts_provider()`。 | [TTS Setup](./tts.md#custom-command-providers) · [Python plugin guide](./tts.md#python-plugin-providers) |
+| **STT 后端**（自定义 whisper 二进制、本地 ASR CLI） | 配置驱动 — 将 `HERMES_LOCAL_STT_COMMAND` 环境变量设置为 shell 模板 | [Voice Message Transcription (STT)](./tts.md#voice-message-transcription-stt) |
+| **通过 MCP 使用外部工具**（文件系统、GitHub、Linear、Notion、任意 MCP 服务器） | 配置驱动 — 在 `config.yaml` 中以 `command:` / `url:` 声明 `mcp_servers.<name>`。Hermes 自动发现服务器的工具并与内置工具一同注册。 | [MCP](./mcp.md) |
+| **额外 skill 来源**（自定义 GitHub 仓库、私有 skill 索引） | CLI — `hermes skills tap add <repo>` | [Skills Hub](./skills.md#skills-hub) · [发布自定义 tap](./skills.md#publishing-a-custom-skill-tap) |
+| **Gateway 事件 hook**（在 `gateway:startup`、`session:start`、`agent:end`、`command:*` 时触发） | 将 `HOOK.yaml` + `handler.py` 放入 `~/.hermes/hooks/<name>/` | [Event Hooks](./hooks.md#gateway-event-hooks) |
+| **Shell hook**（在事件时运行 shell 命令 — 通知、审计日志、桌面提醒） | 配置驱动 — 在 `config.yaml` 的 `hooks:` 下声明 | [Shell Hooks](./hooks.md#shell-hooks) |
 
 :::note
 并非所有扩展都是 Python 插件。某些扩展接口有意使用**配置驱动的 shell 命令**（TTS、STT、shell hook），这样你已有的任意 CLI 无需编写 Python 即可成为插件。其他的是 agent 连接并自动注册工具的**外部服务器**（MCP）。还有一些是拥有自己 manifest 格式的**即插即用目录**（gateway hook）。根据你的集成风格选择合适的接口；上表中的编写指南各自涵盖了占位符、发现机制和示例。
@@ -241,7 +241,7 @@ Memory provider 和 context engine 是 **provider 插件** — 每种类型同
 
 ## NixOS 声明式插件
 
-在 NixOS 上，插件可通过模块选项声明式安装 — 无需 `hermes plugins install`。完整详情请参见 **[Nix Setup 指南](/getting-started/nix-setup#plugins)**。
+在 NixOS 上，插件可通过模块选项声明式安装 — 无需 `hermes plugins install`。完整详情请参见 **[Nix Setup 指南](../../getting-started/nix-setup.md#plugins)**。
 
 ```nix
 services.hermes-agent = {
@@ -343,4 +343,4 @@ ctx.inject_message("New data arrived from the webhook", role="user")
 `inject_message` 仅在 CLI 模式下可用。在 gateway 模式下，没有 CLI 引用，该方法返回 `False`。
 :::
 
-完整的处理器约定、schema 格式、hook 行为、错误处理和常见错误请参见 **[完整指南](/developer-guide/plugins)**。
\ No newline at end of file
+完整的处理器约定、schema 格式、hook 行为、错误处理和常见错误请参见 **[完整指南](../../developer-guide/plugins/index.md)**。
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/provider-routing.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/provider-routing.md
index 0189cdd9f0..6a0e5b45c3 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/provider-routing.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/provider-routing.md
@@ -196,5 +196,5 @@ provider_routing:
 未配置 `provider_routing` 部分时（默认情况），OpenRouter 使用其自身的默认路由逻辑，通常会自动在成本和可用性之间取得平衡。
 
 :::tip Provider Routing 与 Fallback Models
-Provider routing 控制 OpenRouter **内部的子 provider** 如何处理你的请求。若需要在主模型失败时自动故障转移到完全不同的 provider，请参阅 [Fallback Providers](/user-guide/features/fallback-providers)。
+Provider routing 控制 OpenRouter **内部的子 provider** 如何处理你的请求。若需要在主模型失败时自动故障转移到完全不同的 provider，请参阅 [Fallback Providers](./fallback-providers.md)。
 :::
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/skills.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/skills.md
index f2b2650084..b52aae4a83 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/skills.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/skills.md
@@ -14,8 +14,8 @@ Skills 是 agent 在需要时可以加载的按需知识文档。它们遵循**
 
 另请参阅：
 
-- [捆绑 Skills 目录](/reference/skills-catalog)
-- [官方可选 Skills 目录](/reference/optional-skills-catalog)
+- [捆绑 Skills 目录](../../reference/skills-catalog.md)
+- [官方可选 Skills 目录](../../reference/optional-skills-catalog.md)
 
 ## 使用 Skills
 
@@ -174,7 +174,7 @@ required_environment_variables:
 
 当遇到缺失的值时，Hermes 仅在本地 CLI 中实际加载 skill 时才会安全地请求输入。你可以跳过设置并继续使用该 skill。消息平台不会在聊天中请求密钥——它们会告诉你改用本地的 `hermes setup` 或 `~/.hermes/.env`。
 
-一旦设置，声明的环境变量会**自动传递**到 `execute_code` 和 `terminal` 沙箱——skill 的脚本可以直接使用 `$TENOR_API_KEY`。对于非 skill 的环境变量，使用 `terminal.env_passthrough` 配置选项。详情参见[环境变量传递](/user-guide/security#environment-variable-passthrough)。
+一旦设置，声明的环境变量会**自动传递**到 `execute_code` 和 `terminal` 沙箱——skill 的脚本可以直接使用 `$TENOR_API_KEY`。对于非 skill 的环境变量，使用 `terminal.env_passthrough` 配置选项。详情参见[环境变量传递](../security.md#environment-variable-passthrough)。
 
 ### Skill 配置设置
 
@@ -192,7 +192,7 @@ metadata:
 
 设置存储在 config.yaml 的 `skills.config` 下。`hermes config migrate` 会提示配置未设置的项，`hermes config show` 会显示它们。当 skill 加载时，其解析后的配置值会注入到上下文中，agent 会自动知晓已配置的值。
 
-详情参见 [Skill 设置](/user-guide/configuration#skill-settings) 和[创建 Skills——配置设置](/developer-guide/creating-skills#config-settings-configyaml)。
+详情参见 [Skill 设置](../configuration.md#skill-settings) 和[创建 Skills——配置设置](../../developer-guide/creating-skills.md#config-settings-configyaml)。
 
 ## Skill 目录结构
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/skins.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/skins.md
index 1067e01537..fbf4c653f1 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/skins.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/skins.md
@@ -259,7 +259,7 @@ npm start
 6. 点击 **Save** 将皮肤 YAML 写入 `~/.hermes/skins/`。
 7. 点击 **Activate** 将其设为当前皮肤（更新 `config.yaml` 中的 `display.skin`）。
 
-Hermes Mod 遵循 `HERMES_HOME` 环境变量，因此也适用于[配置文件](/user-guide/profiles)。
+Hermes Mod 遵循 `HERMES_HOME` 环境变量，因此也适用于[配置文件](../profiles.md)。
 
 ## 操作说明
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/tools.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/tools.md
index dfa2771554..746f4d561a 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/tools.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/tools.md
@@ -30,7 +30,7 @@ Hermes 内置了丰富的工具注册表，涵盖网页搜索、浏览器自动
 | **自动化与投递** | `cronjob`, `send_message` | 支持创建/列出/更新/暂停/恢复/运行/删除操作的定时任务，以及出站消息投递。 |
 | **集成** | `ha_*`、MCP server 工具 | Home Assistant、MCP 及其他集成。 |
 
-如需查看由代码派生的权威注册表，请参阅 [内置工具参考](/reference/tools-reference) 和 [工具集参考](/reference/toolsets-reference)。
+如需查看由代码派生的权威注册表，请参阅 [内置工具参考](../../reference/tools-reference.md) 和 [工具集参考](../../reference/toolsets-reference.md)。
 
 :::tip Nous Tool Gateway
 付费 [Nous Portal](https://portal.nousresearch.com) 订阅者可通过 **[Tool Gateway](tool-gateway.md)** 使用网页搜索、图像生成、TTS 和浏览器自动化——无需单独配置 API 密钥。运行 `hermes model` 启用，或通过 `hermes tools` 配置各工具。
@@ -51,7 +51,7 @@ hermes tools
 
 常用工具集包括 `web`、`search`、`terminal`、`file`、`browser`、`vision`、`image_gen`、`moa`、`skills`、`tts`、`todo`、`memory`、`session_search`、`cronjob`、`code_execution`、`delegation`、`clarify`、`homeassistant`、`messaging`、`spotify`、`discord`、`discord_admin`、`debugging` 和 `safe`。
 
-完整列表（包括 `hermes-cli`、`hermes-telegram` 等平台预设以及 `mcp-<server>` 等动态 MCP 工具集）请参阅 [工具集参考](/reference/toolsets-reference)。
+完整列表（包括 `hermes-cli`、`hermes-telegram` 等平台预设以及 `mcp-<server>` 等动态 MCP 工具集）请参阅 [工具集参考](../../reference/toolsets-reference.md)。
 
 ## 终端后端
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/vision.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/vision.md
index 721a454b9c..e61e3940ba 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/vision.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/vision.md
@@ -201,7 +201,7 @@ powershell.exe -NoProfile -Command "Add-Type -AssemblyName System.Windows.Forms;
 
 无需手动配置——Hermes 在提供商元数据中查找当前模型的能力并自动选择正确路径。实际效果：你可以在会话中途切换视觉模型与非视觉模型，图像处理"开箱即用"，无需更改工作流。纯文本模型会获得关于图像的连贯上下文，而不是一个会被拒绝的损坏多模态载荷。
 
-处理文本描述路径的辅助模型可在 `auxiliary.vision` 下配置——参见[辅助模型](/user-guide/configuration#auxiliary-models)。
+处理文本描述路径的辅助模型可在 `auxiliary.vision` 下配置——参见[辅助模型](../configuration.md#auxiliary-models)。
 
 ### `vision_analyze` 具有相同的双重行为
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/voice-mode.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/voice-mode.md
index 6593030880..9578759aa4 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/voice-mode.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/voice-mode.md
@@ -8,13 +8,13 @@ description: "与 Hermes Agent 进行实时语音对话 — CLI、Telegram、Dis
 
 Hermes Agent 支持在 CLI 和消息平台上进行完整的语音交互。通过麦克风与 Agent 对话，听取语音回复，并在 Discord 语音频道中进行实时语音对话。
 
-如需包含推荐配置和实际使用模式的实践指南，请参阅 [使用 Hermes 的语音模式](/guides/use-voice-mode-with-hermes)。
+如需包含推荐配置和实际使用模式的实践指南，请参阅 [使用 Hermes 的语音模式](../../guides/use-voice-mode-with-hermes.md)。
 
 ## 前提条件
 
 使用语音功能前，请确保已完成以下准备：
 
-1. **已安装 Hermes Agent** — 通过安装脚本（参见 [安装](/getting-started/installation)）
+1. **已安装 Hermes Agent** — 通过安装脚本（参见 [安装](../../getting-started/installation.md)）
 2. **已配置 LLM 提供商** — 运行 `hermes model` 或在 `~/.hermes/.env` 中设置首选提供商的凭据
 3. **基础设置正常** — 运行 `hermes` 验证 Agent 能够响应文字消息，再启用语音功能
 
@@ -23,7 +23,7 @@ Hermes Agent 支持在 CLI 和消息平台上进行完整的语音交互。通
 :::
 
 :::tip Nous Portal 同时覆盖两项
-付费的 [Nous Portal](/user-guide/features/tool-gateway) 订阅通过 Tool Gateway 同时提供 LLM（第 2 步）**和** OpenAI TTS — 无需单独的 OpenAI 密钥。全新安装时，`hermes setup --portal` 可一次性完成两项配置。
+付费的 [Nous Portal](./tool-gateway.md) 订阅通过 Tool Gateway 同时提供 LLM（第 2 步）**和** OpenAI TTS — 无需单独的 OpenAI 密钥。全新安装时，`hermes setup --portal` 可一次性完成两项配置。
 :::
 
 ## 概览
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/discord.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/discord.md
index a8f8b07799..587632fb7b 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/discord.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/discord.md
@@ -724,8 +724,8 @@ Hermes Agent 支持 Discord 语音消息：
 - **Discord 语音频道**：Hermes 还可以加入语音频道，聆听用户说话，并在频道中回话。
 
 完整的设置和操作指南，请参阅：
-- [语音模式](/user-guide/features/voice-mode)
-- [与 Hermes 使用语音模式](/guides/use-voice-mode-with-hermes)
+- [语音模式](../features/voice-mode.md)
+- [与 Hermes 使用语音模式](../../guides/use-voice-mode-with-hermes.md)
 
 ## 论坛频道
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/index.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/index.md
index 6afaa0da90..c4b1eb0eaa 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/index.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/index.md
@@ -8,7 +8,7 @@ description: "通过 Telegram、Discord、Slack、WhatsApp、Signal、SMS、Emai
 
 通过 Telegram、Discord、Slack、WhatsApp、Signal、SMS、Email、Home Assistant、Mattermost、Matrix、DingTalk、Feishu/Lark、WeCom、Weixin、BlueBubbles（iMessage）、QQ、Yuanbao、Microsoft Teams、LINE、ntfy 或浏览器与 Hermes 对话。网关是一个单一后台进程，连接所有已配置的平台，管理会话，运行 cron 任务，并传递语音消息。
 
-完整的语音功能集——包括 CLI 麦克风模式、消息中的语音回复以及 Discord 语音频道对话——请参阅 [Voice Mode](/user-guide/features/voice-mode) 和 [Use Voice Mode with Hermes](/guides/use-voice-mode-with-hermes)。
+完整的语音功能集——包括 CLI 麦克风模式、消息中的语音回复以及 Discord 语音频道对话——请参阅 [Voice Mode](../features/voice-mode.md) 和 [Use Voice Mode with Hermes](../../guides/use-voice-mode-with-hermes.md)。
 
 ## 平台对比
 
@@ -261,7 +261,7 @@ gateway:
 
 #### 查看你的权限
 
-在任意平台使用 `/whoami` 查看当前范围、你的层级（管理员 / 普通用户 / 无限制）以及你可以运行的斜杠命令。平台特定示例请参阅 [Telegram](/user-guide/messaging/telegram#slash-command-access-control) 和 [Discord](/user-guide/messaging/discord#slash-command-access-control) 页面。
+在任意平台使用 `/whoami` 查看当前范围、你的层级（管理员 / 普通用户 / 无限制）以及你可以运行的斜杠命令。平台特定示例请参阅 [Telegram](./telegram.md#slash-command-access-control) 和 [Discord](./discord.md#slash-command-access-control) 页面。
 
 ## 中断 Agent
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/msgraph-webhook.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/msgraph-webhook.md
index ce9ff46fe0..f1451d2854 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/msgraph-webhook.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/msgraph-webhook.md
@@ -12,7 +12,7 @@ description: "在 Hermes 中接收 Microsoft Graph 变更通知（会议、日
 
 ## 前提条件
 
-- Microsoft Graph 应用凭据——[注册 Microsoft Graph 应用程序](/guides/microsoft-graph-app-registration)
+- Microsoft Graph 应用凭据——[注册 Microsoft Graph 应用程序](../../guides/microsoft-graph-app-registration.md)
 - 一个 Microsoft Graph 可访问的**公开 HTTPS URL**（Graph 不会调用私有端点）。测试时可使用 dev tunnel；生产环境需要具有有效证书的真实域名。
 - 一个强共享密钥，用作 `clientState` 的值。使用 `openssl rand -hex 32` 生成，并以 `MSGRAPH_WEBHOOK_CLIENT_STATE` 写入 `~/.hermes/.env`。
 
@@ -67,7 +67,7 @@ https://ops.example.com/msgraph/webhook
 | `max_seen_receipts` | `5000` | 通知 ID 的去重缓存大小。达到上限时淘汰最旧的条目。 |
 | `allowed_source_cidrs` | `[]`（允许全部） | 可选的源 IP 白名单。见下文。 |
 
-大多数设置也有对应的环境变量（`MSGRAPH_WEBHOOK_*`），在 gateway 启动时合并到配置中（例外是 `host`，它仅可通过配置文件设置——参见上方说明）——参见[环境变量参考](/reference/environment-variables#microsoft-graph-teams-meetings)。
+大多数设置也有对应的环境变量（`MSGRAPH_WEBHOOK_*`），在 gateway 启动时合并到配置中（例外是 `host`，它仅可通过配置文件设置——参见上方说明）——参见[环境变量参考](../../reference/environment-variables.md#microsoft-graph-teams-meetings)。
 
 ## 安全加固
 
@@ -132,6 +132,6 @@ MSGRAPH_WEBHOOK_ALLOWED_SOURCE_CIDRS="52.96.0.0/14,52.104.0.0/14"
 
 ## 相关文档
 
-- [注册 Microsoft Graph 应用程序](/guides/microsoft-graph-app-registration) — Azure 应用注册前提条件
-- [环境变量 → Microsoft Graph](/reference/environment-variables#microsoft-graph-teams-meetings) — 完整环境变量列表
-- [Microsoft Teams 机器人设置](/user-guide/messaging/teams) — 允许用户在 Teams 中与 Hermes 聊天的另一平台
\ No newline at end of file
+- [注册 Microsoft Graph 应用程序](../../guides/microsoft-graph-app-registration.md) — Azure 应用注册前提条件
+- [环境变量 → Microsoft Graph](../../reference/environment-variables.md#microsoft-graph-teams-meetings) — 完整环境变量列表
+- [Microsoft Teams 机器人设置](./teams.md) — 允许用户在 Teams 中与 Hermes 聊天的另一平台
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/open-webui.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/open-webui.md
index 44d5c54e67..537d326eae 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/open-webui.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/open-webui.md
@@ -233,7 +233,7 @@ Open WebUI 在首次启动后会将 OpenAI 兼容连接设置持久化到其自
 
 ## 多用户设置与 Profiles
 
-要为每个用户运行独立的 Hermes 实例——各自拥有独立的配置、记忆和技能——请使用 [profiles](/user-guide/profiles)。每个 profile 在不同端口上运行自己的 API 服务器，并自动将 profile 名称作为模型名称公告给 Open WebUI。
+要为每个用户运行独立的 Hermes 实例——各自拥有独立的配置、记忆和技能——请使用 [profiles](../profiles.md)。每个 profile 在不同端口上运行自己的 API 服务器，并自动将 profile 名称作为模型名称公告给 Open WebUI。
 
 ### 1. 创建 profiles 并配置 API 服务器
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/sms.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/sms.md
index 235e8f3789..9500600fa6 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/sms.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/sms.md
@@ -10,7 +10,7 @@ description: "通过 Twilio 将 Hermes Agent 设置为 SMS 聊天机器人"
 Hermes 通过 [Twilio](https://www.twilio.com/) API 接入 SMS。用户向你的 Twilio 电话号码发送短信，即可获得 AI 回复——与 Telegram 或 Discord 的对话体验相同，但通过标准短信进行。
 
 :::info 共享凭据
-SMS gateway（网关）与可选的 [telephony skill](/reference/skills-catalog) 共享凭据。如果你已为语音通话或单次 SMS 配置了 Twilio，该 gateway 可直接使用相同的 `TWILIO_ACCOUNT_SID`、`TWILIO_AUTH_TOKEN` 和 `TWILIO_PHONE_NUMBER`。
+SMS gateway（网关）与可选的 [telephony skill](../../reference/skills-catalog.md) 共享凭据。如果你已为语音通话或单次 SMS 配置了 Twilio，该 gateway 可直接使用相同的 `TWILIO_ACCOUNT_SID`、`TWILIO_AUTH_TOKEN` 和 `TWILIO_PHONE_NUMBER`。
 :::
 
 ---
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/teams-meetings.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/teams-meetings.md
index 97179480b1..5256316434 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/teams-meetings.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/teams-meetings.md
@@ -14,7 +14,7 @@ description: "使用 Microsoft Graph webhook 配置 Microsoft Teams 会议摘要
 - Teams 投递模式
 - 流水线配置结构
 
-关于上线后的日常运维、上线检查及运维工作表，请参阅专项指南：[运维 Teams 会议流水线](/guides/operate-teams-meeting-pipeline)。
+关于上线后的日常运维、上线检查及运维工作表，请参阅专项指南：[运维 Teams 会议流水线](../../guides/operate-teams-meeting-pipeline.md)。
 
 ## 功能说明
 
@@ -38,7 +38,7 @@ hermes teams-pipeline maintain-subscriptions
 启用会议流水线前，请确保已具备：
 
 - 可正常运行的 Hermes 安装
-- 若需要 Teams 出站投递，需完成现有的 [Microsoft Teams bot 配置](/user-guide/messaging/teams)
+- 若需要 Teams 出站投递，需完成现有的 [Microsoft Teams bot 配置](./teams.md)
 - 具备订阅所需会议资源权限的 Microsoft Graph 应用凭据
 - Microsoft Graph 可调用的公网 HTTPS URL，用于 webhook 投递
 - 若需要录音加 STT 回退，需安装 `ffmpeg`
@@ -196,11 +196,11 @@ hermes teams-pipeline subscribe \
 
 :::warning Graph 订阅在 72 小时后过期
 
-Microsoft Graph 将 webhook 订阅上限设为 72 小时，且不会自动续期。你**必须**在上线前调度 `hermes teams-pipeline maintain-subscriptions`，否则通知将在手动创建订阅三天后静默停止。请参阅运维手册中的[自动化订阅续期](/guides/operate-teams-meeting-pipeline#automating-subscription-renewal-required-for-production)——提供三种方案（Hermes cron、systemd timer、普通 crontab）。
+Microsoft Graph 将 webhook 订阅上限设为 72 小时，且不会自动续期。你**必须**在上线前调度 `hermes teams-pipeline maintain-subscriptions`，否则通知将在手动创建订阅三天后静默停止。请参阅运维手册中的[自动化订阅续期](../../guides/operate-teams-meeting-pipeline.md#automating-subscription-renewal-required-for-production)——提供三种方案（Hermes cron、systemd timer、普通 crontab）。
 
 :::
 
-关于订阅维护和上线后的运维流程，请继续阅读指南：[运维 Teams 会议流水线](/guides/operate-teams-meeting-pipeline)。
+关于订阅维护和上线后的运维流程，请继续阅读指南：[运维 Teams 会议流水线](../../guides/operate-teams-meeting-pipeline.md)。
 
 ## 验证
 
@@ -229,5 +229,5 @@ hermes teams-pipeline subscriptions
 
 ## 相关文档
 
-- [Microsoft Teams bot 配置](/user-guide/messaging/teams)
-- [运维 Teams 会议流水线](/guides/operate-teams-meeting-pipeline)
\ No newline at end of file
+- [Microsoft Teams bot 配置](./teams.md)
+- [运维 Teams 会议流水线](../../guides/operate-teams-meeting-pipeline.md)
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/teams.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/teams.md
index 60368448b0..530d4b989e 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/teams.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/teams.md
@@ -8,7 +8,7 @@ description: "将 Hermes Agent 设置为 Microsoft Teams 机器人"
 
 将 Hermes Agent 作为机器人接入 Microsoft Teams。与 Slack 的 Socket Mode 不同，Teams 通过调用**公开 HTTPS webhook**（钩子）来投递消息，因此你的实例需要一个可公开访问的端点——本地开发时使用开发隧道，生产环境使用真实域名。
 
-如果你需要的是来自 Microsoft Graph 事件的会议摘要，而非普通的机器人对话，请使用专用设置页面：[Teams 会议](/user-guide/messaging/teams-meetings)。
+如果你需要的是来自 Microsoft Graph 事件的会议摘要，而非普通的机器人对话，请使用专用设置页面：[Teams 会议](./teams-meetings.md)。
 
 ## 机器人的响应方式
 
@@ -170,7 +170,7 @@ platforms:
 
 ### 会议摘要投递（Teams 会议 Pipeline）
 
-当 [Teams 会议 pipeline 插件](/user-guide/messaging/msgraph-webhook)启用后，此适配器同时负责会议摘要的出站投递——一个 Teams 集成面，而非两个。会议转录摘要生成后，写入器会将摘要发布到你指定的 Teams 目标。
+当 [Teams 会议 pipeline 插件](./msgraph-webhook.md)启用后，此适配器同时负责会议摘要的出站投递——一个 Teams 集成面，而非两个。会议转录摘要生成后，写入器会将摘要发布到你指定的 Teams 目标。
 
 Pipeline 摘要投递在 `teams` 平台条目下与机器人配置并列配置：
 
@@ -195,7 +195,7 @@ platforms:
 | 模式 | 适用场景 | 权衡 |
 |------|----------|------|
 | `incoming_webhook` | 使用 Teams 生成的静态 URL，简单地将摘要发布到某个频道。 | 不支持回复线程和表情回应，显示为 webhook 配置的身份。 |
-| `graph` | 通过 Microsoft Graph 以机器人身份发布带线程的频道帖子或 1:1/群聊消息。 | 需要完成 [Graph 应用注册](/guides/microsoft-graph-app-registration)，并具备 `ChannelMessage.Send`（频道）或 `Chat.ReadWrite.All`（聊天）应用权限。 |
+| `graph` | 通过 Microsoft Graph 以机器人身份发布带线程的频道帖子或 1:1/群聊消息。 | 需要完成 [Graph 应用注册](../../guides/microsoft-graph-app-registration.md)，并具备 `ChannelMessage.Send`（频道）或 `Chat.ReadWrite.All`（聊天）应用权限。 |
 
 如果 `teams_pipeline` 插件**未启用**，这些设置不会生效——它们仅在 pipeline 运行时绑定到 Graph webhook 入口时才会激活。
 
@@ -251,5 +251,5 @@ teams app update --id <teamsAppId> --endpoint "https://your-domain.com/api/messa
 
 ## 相关文档
 
-- [Teams 会议](/user-guide/messaging/teams-meetings)
-- [运营 Teams 会议 Pipeline](/guides/operate-teams-meeting-pipeline)
+- [Teams 会议](./teams-meetings.md)
+- [运营 Teams 会议 Pipeline](../../guides/operate-teams-meeting-pipeline.md)
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/telegram.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/telegram.md
index f19d9555cd..665dd1a6ed 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/telegram.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/telegram.md
@@ -1238,4 +1238,4 @@ HERMES_TELEGRAM_NOTIFICATIONS=all
 
 切勿公开分享你的机器人 token。如果泄露，请立即通过 BotFather 的 `/revoke` 命令撤销。
 
-更多详情，请参阅[安全文档](/user-guide/security)。你也可以使用 [DM 配对](/user-guide/messaging#dm-pairing-alternative-to-allowlists) 进行更动态的用户授权方式。
\ No newline at end of file
+更多详情，请参阅[安全文档](../security.md)。你也可以使用 [DM 配对](./index.md#dm-pairing-alternative-to-allowlists) 进行更动态的用户授权方式。
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/whatsapp.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/whatsapp.md
index 87c63d194c..090f662fdd 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/whatsapp.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/whatsapp.md
@@ -103,9 +103,9 @@ WHATSAPP_ALLOWED_USERS=15551234567         # 逗号分隔的手机号（含国
 
 :::tip 允许所有人的简写
 将 `WHATSAPP_ALLOWED_USERS=*` 设置为允许**所有**发送者（等同于 `WHATSAPP_ALLOW_ALL_USERS=true`）。
-这与 [Signal 群组白名单](/reference/environment-variables) 保持一致。
+这与 [Signal 群组白名单](../../reference/environment-variables.md) 保持一致。
 如需使用配对流程，请移除这两个变量，改用
-[私信配对系统](/user-guide/security#dm-pairing-system)。
+[私信配对系统](../security.md#dm-pairing-system)。
 :::
 
 在 `~/.hermes/config.yaml` 中可选的行为设置：
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/yuanbao.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/yuanbao.md
index 62b637b5e8..803d497c97 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/yuanbao.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/yuanbao.md
@@ -336,6 +336,6 @@ hermes chat -q "Send 'Hello from CLI' to yuanbao:group:group_code"
 ## 相关文档
 
 - [消息 Gateway 概览](./index.md)
-- [斜杠命令参考](/reference/slash-commands)
-- [Cron Job](/user-guide/features/cron)
-- [后台会话](/user-guide/cli#background-sessions)
\ No newline at end of file
+- [斜杠命令参考](../../reference/slash-commands.md)
+- [Cron Job](../features/cron.md)
+- [后台会话](../cli.md#background-sessions)
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/profiles.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/profiles.md
index 6775a7ca94..959c436fe0 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/profiles.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/profiles.md
@@ -193,7 +193,7 @@ assistant gateway install     # 创建 hermes-gateway-assistant 服务
 每个 profile 拥有独立的服务名称，各自独立运行。
 
 :::note 在官方 Docker 镜像中
-各 profile 的 gateway 由 [s6-overlay](https://github.com/just-containers/s6-overlay)（容器中的 PID 1）监管，因此 `hermes profile create <name>` 会自动在 `/run/service/gateway-<name>/` 注册 s6 服务槽。`hermes -p <name> gateway start/stop/restart` 会调度到 `s6-svc` 而非直接启动裸进程——崩溃后自动重启，`docker restart` 会保留之前运行的 gateway 集合。详见 [各 profile gateway 监管](/user-guide/docker#per-profile-gateway-supervision)。
+各 profile 的 gateway 由 [s6-overlay](https://github.com/just-containers/s6-overlay)（容器中的 PID 1）监管，因此 `hermes profile create <name>` 会自动在 `/run/service/gateway-<name>/` 注册 s6 服务槽。`hermes -p <name> gateway start/stop/restart` 会调度到 `s6-svc` 而非直接启动裸进程——崩溃后自动重启，`docker restart` 会保留之前运行的 gateway 集合。详见 [各 profile gateway 监管](./docker.md#per-profile-gateway-supervision)。
 :::
 
 ## 配置 profile
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/security.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/security.md
index 200da25afc..421d458db6 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/security.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/security.md
@@ -495,7 +495,7 @@ security:
 
 当请求被阻止的 URL 时，工具会返回一条错误，说明该域名已被策略阻止。黑名单在 `web_search`、`web_extract`、`browser_navigate` 及所有支持 URL 的工具中均强制执行。
 
-完整详情请参见配置指南中的[网站黑名单](/user-guide/configuration#website-blocklist)。
+完整详情请参见配置指南中的[网站黑名单](./configuration.md#website-blocklist)。
 
 ### SSRF 防护
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/sessions.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/sessions.md
index 97392e72cf..0c82602f6d 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/sessions.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/sessions.md
@@ -431,7 +431,7 @@ Total messages: 3847
 Database size: 12.4 MB
 ```
 
-如需更深入的分析——token 用量、费用估算、工具分解和活动模式——请使用 [`hermes insights`](/reference/cli-commands#hermes-insights)。
+如需更深入的分析——token 用量、费用估算、工具分解和活动模式——请使用 [`hermes insights`](../reference/cli-commands.md#hermes-insights)。
 
 ## Session 搜索工具
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/windows-native.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/windows-native.md
index 89555b02cb..d9474632a3 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/windows-native.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/windows-native.md
@@ -9,7 +9,7 @@ sidebar_position: 3
 
 Hermes 可在 Windows 10 和 Windows 11 上原生运行——无需 WSL、Cygwin 或 Docker。本页是深度指南：原生支持哪些功能、哪些仅限 WSL、安装程序实际做了什么，以及你可能需要调整的 Windows 专属配置项。
 
-如果你只是想安装，[首页](/) 或[安装页面](../getting-started/installation#windows原生powershell)上的一行命令就够了。遇到意外情况时再回来查阅本页。
+如果你只是想安装，[首页](../index.mdx) 或[安装页面](../getting-started/installation#windows原生powershell)上的一行命令就够了。遇到意外情况时再回来查阅本页。
 
 :::tip 想用 WSL？
 如果你更倾向于真正的 POSIX 环境（用于 dashboard 内嵌终端、`fork` 语义、Linux 风格文件监视器等），请参阅 **[Windows（WSL2）指南](./windows-wsl-quickstart.md)**。两者可以干净共存：原生数据存放在 `%LOCALAPPDATA%\hermes`，WSL 数据存放在 `~/.hermes`。
@@ -79,7 +79,7 @@ iex (irm https://hermes-agent.nousresearch.com/install.ps1)
 10. **运行 `hermes setup`** — 正常的首次运行向导（模型、提供商、工具集）。使用 `-SkipSetup` 跳过。
 
 :::tip 在 Windows 上跳过繁琐的提供商配置
-在 Windows 上，逐个配置工具 API key（Firecrawl、FAL、Browser Use、OpenAI TTS）是获得可用 agent 摩擦最大的部分。[Nous Portal](/user-guide/features/tool-gateway) 订阅通过一次 OAuth 登录即可覆盖模型**以及**所有这些工具。安装程序完成后，运行 `hermes setup --portal` 完成配置。
+在 Windows 上，逐个配置工具 API key（Firecrawl、FAL、Browser Use、OpenAI TTS）是获得可用 agent 摩擦最大的部分。[Nous Portal](./features/tool-gateway.md) 订阅通过一次 OAuth 登录即可覆盖模型**以及**所有这些工具。安装程序完成后，运行 `hermes setup --portal` 完成配置。
 :::
 
 ## 功能矩阵
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/windows-wsl-quickstart.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/windows-wsl-quickstart.md
index 7b108b8f89..6304a3c065 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/windows-wsl-quickstart.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/windows-wsl-quickstart.md
@@ -65,7 +65,7 @@ Hermes 在 WSL1 上无法可靠运行 —— WSL1 会动态转译 Linux 系统
 
 ### 发行版选择
 
-我们以 Ubuntu（LTS）为测试基准。Debian 同样可用。Arch 和 NixOS 也有人在用，但一键安装脚本假设使用基于 Debian 的 `apt` 系统 —— 如需其他路径，请参阅 [Nix 安装指南](/getting-started/nix-setup)。
+我们以 Ubuntu（LTS）为测试基准。Debian 同样可用。Arch 和 NixOS 也有人在用，但一键安装脚本假设使用基于 Debian 的 `apt` 系统 —— 如需其他路径，请参阅 [Nix 安装指南](../getting-started/nix-setup.md)。
 
 ### 启用 systemd（推荐）
 
@@ -105,7 +105,7 @@ source ~/.bashrc
 hermes
 ```
 
-安装程序将 WSL2 视为普通 Linux —— 无需任何 WSL 专属配置。完整目录结构请参阅[安装说明](/getting-started/installation)。
+安装程序将 WSL2 视为普通 Linux —— 无需任何 WSL 专属配置。完整目录结构请参阅[安装说明](../getting-started/installation.md)。
 
 ## 文件系统：跨越 Windows ↔ WSL2 边界
 
@@ -188,7 +188,7 @@ dos2unix path/to/script.sh
 
 在 WSL 内 clone。始终如此，除非有特殊原因。典型的 Hermes 工作流（`hermes chat`、调用 `rg`/`ripgrep` 搜索仓库的工具、文件监听器、后台 gateway）在 `~/code/myrepo` 下会比在 `/mnt/c/Users/you/myrepo` 下快得多，也更可靠。
 
-一个例外：**启动 Windows 二进制文件的 MCP bridge。** 如果你通过 `cmd.exe` 使用 `chrome-devtools-mcp`（参见 [MCP 指南：WSL → Windows Chrome](/guides/use-mcp-with-hermes#wsl2-bridge-hermes-in-wsl-to-windows-chrome)），当 Hermes 的当前工作目录是 `~` 时，Windows 可能会报 `UNC` 警告。此时请从 `/mnt/c/` 下的某个目录启动 Hermes，以便 Windows 进程拥有一个带盘符的工作目录。
+一个例外：**启动 Windows 二进制文件的 MCP bridge。** 如果你通过 `cmd.exe` 使用 `chrome-devtools-mcp`（参见 [MCP 指南：WSL → Windows Chrome](../guides/use-mcp-with-hermes.md#wsl2-bridge-hermes-in-wsl-to-windows-chrome)），当 Hermes 的当前工作目录是 `~` 时，Windows 可能会报 `UNC` 警告。此时请从 `/mnt/c/` 下的某个目录启动 Hermes，以便 Windows 进程拥有一个带盘符的工作目录。
 
 ## 网络：WSL ↔ Windows
 
@@ -200,7 +200,7 @@ WSL2 在轻量级虚拟机中运行，拥有独立的网络栈。这意味着 WS
 
 最常见的场景：你在 **Windows 上运行 Ollama、LM Studio 或 llama-server**，而 WSL 内的 Hermes 需要访问它。
 
-此场景的权威说明在 providers 指南中：**[WSL2 本地模型网络配置 →](/integrations/providers#wsl2-networking-windows-users)**
+此场景的权威说明在 providers 指南中：**[WSL2 本地模型网络配置 →](../integrations/providers.md#wsl2-networking-windows-users)**
 
 简要说明：
 
@@ -214,7 +214,7 @@ WSL2 在轻量级虚拟机中运行，拥有独立的网络栈。这意味着 WS
 这是反向情况，其他地方较少记录，但以下场景需要用到：
 
 - 从 Windows 浏览器使用 Hermes **Web Dashboard**。
-- 从 Windows 侧工具使用 **OpenAI 兼容 API 服务器**（当 `API_SERVER_ENABLED=true` 时由 `hermes gateway` 暴露）。参见 [API Server 功能页](/user-guide/features/api-server)。
+- 从 Windows 侧工具使用 **OpenAI 兼容 API 服务器**（当 `API_SERVER_ENABLED=true` 时由 `hermes gateway` 暴露）。参见 [API Server 功能页](./features/api-server.md)。
 - 测试**消息 gateway**（Telegram、Discord 等），平台会向本地 webhook URL 发送请求 —— 通常建议使用 `cloudflared`/`ngrok` 而非原始端口转发。
 
 #### 子情况 2a：从 Windows 宿主机本身访问
@@ -254,11 +254,11 @@ WSL2 在轻量级虚拟机中运行，拥有独立的网络栈。这意味着 WS
 
 由于 NAT 模式下 WSL 虚拟机 IP 在每次重启后都会变化，一次性配置的规则在下次 `wsl --shutdown` 后即失效。如需持久化，要么启用镜像模式，要么将端口代理步骤写入 Windows 登录时自动运行的脚本。
 
-对于来自云端消息服务商的 webhook（Telegram `setWebhook`、Slack 事件等），不建议折腾端口转发 —— 请使用 `cloudflared` 隧道。参见 [webhook 指南](/user-guide/messaging/webhooks)。
+对于来自云端消息服务商的 webhook（Telegram `setWebhook`、Slack 事件等），不建议折腾端口转发 —— 请使用 `cloudflared` 隧道。参见 [webhook 指南](./messaging/webhooks.md)。
 
 ## 在 Windows 上长期运行 Hermes 服务
 
-Hermes 的 [Tool Gateway](/user-guide/features/tool-gateway) 和 API 服务器都是长期运行的进程。在 WSL2 中，有以下几种方式保持它们持续运行。
+Hermes 的 [Tool Gateway](./features/tool-gateway.md) 和 API 服务器都是长期运行的进程。在 WSL2 中，有以下几种方式保持它们持续运行。
 
 ### 在 WSL 内使用 systemd（推荐）
 
@@ -292,7 +292,7 @@ AMD ROCm 和 Intel Arc 在 WSL2 内的支持仍在发展中，不在 Hermes 的
 ## 常见问题
 
 **连接 Windows 上的 Ollama / LM Studio 时报"Connection refused"。**
-参见 [WSL2 网络配置](/integrations/providers#wsl2-networking-windows-users)。九成情况是服务绑定在 `127.0.0.1` 上，需要改为 `0.0.0.0`（Ollama：`OLLAMA_HOST=0.0.0.0`），或者缺少防火墙规则。
+参见 [WSL2 网络配置](../integrations/providers.md#wsl2-networking-windows-users)。九成情况是服务绑定在 `127.0.0.1` 上，需要改为 `0.0.0.0`（Ollama：`OLLAMA_HOST=0.0.0.0`），或者缺少防火墙规则。
 
 **`git status` / `hermes chat` 在仓库中极慢。**
 你很可能在 `/mnt/c/...` 下工作。将仓库移到 `~/code/...`（Linux 侧），速度会有数量级的提升。
@@ -326,7 +326,7 @@ WSL2 将虚拟机磁盘存储为 `%LOCALAPPDATA%\Packages\...` 下的稀疏 VHDX
 
 ## 下一步
 
-- **[安装说明](/getting-started/installation)** —— 实际安装步骤（Linux/WSL2/Termux 均使用同一安装程序）。
-- **[集成 → Providers → WSL2 网络配置](/integrations/providers#wsl2-networking-windows-users)** —— 本地模型服务器网络配置的权威深度说明。
-- **[MCP 指南 → WSL → Windows Chrome](/guides/use-mcp-with-hermes#wsl2-bridge-hermes-in-wsl-to-windows-chrome)** —— 从 WSL 中的 Hermes 控制你已登录的 Windows Chrome。
-- **[Tool Gateway](/user-guide/features/tool-gateway)** 和 **[Web Dashboard](/user-guide/features/web-dashboard)** —— 你最常需要从 WSL 暴露到网络其他部分的长期运行服务。
\ No newline at end of file
+- **[安装说明](../getting-started/installation.md)** —— 实际安装步骤（Linux/WSL2/Termux 均使用同一安装程序）。
+- **[集成 → Providers → WSL2 网络配置](../integrations/providers.md#wsl2-networking-windows-users)** —— 本地模型服务器网络配置的权威深度说明。
+- **[MCP 指南 → WSL → Windows Chrome](../guides/use-mcp-with-hermes.md#wsl2-bridge-hermes-in-wsl-to-windows-chrome)** —— 从 WSL 中的 Hermes 控制你已登录的 Windows Chrome。
+- **[Tool Gateway](./features/tool-gateway.md)** 和 **[Web Dashboard](./features/web-dashboard.md)** —— 你最常需要从 WSL 暴露到网络其他部分的长期运行服务。
\ No newline at end of file

From d15208e5f0eaf937e8692301fa89c38f29804b34 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 11:20:15 -0700
Subject: [PATCH 133/190] docs(website): re-run the link sweep over pages
 merged since the rebase

`python3 website/scripts/check_doc_links.py --fix` over the current tree: 126
route-style links in 9 pages (the six that conflicted with #114784/#114806/
#114851 plus google-gemini, cron and secrets) rewritten to relative file paths.
Check mode is clean afterwards.
---
 website/docs/guides/google-gemini.md          |  2 +-
 .../guides/run-hermes-with-nous-portal.md     | 30 ++++----
 website/docs/integrations/nous-portal.md      | 26 +++----
 website/docs/reference/slash-commands.md      | 48 ++++++-------
 website/docs/user-guide/configuration.md      | 72 +++++++++----------
 website/docs/user-guide/features/cron.md      |  2 +-
 website/docs/user-guide/secrets/index.md      |  2 +-
 .../guides/run-hermes-with-nous-portal.md     | 30 ++++----
 .../current/integrations/nous-portal.md       | 26 +++----
 9 files changed, 119 insertions(+), 119 deletions(-)

diff --git a/website/docs/guides/google-gemini.md b/website/docs/guides/google-gemini.md
index 064e202033..f90c00ed2b 100644
--- a/website/docs/guides/google-gemini.md
+++ b/website/docs/guides/google-gemini.md
@@ -124,7 +124,7 @@ express-mode** keys start with `AQ.…` and only authenticate against
 `GEMINI_BASE_URL` to `https://aiplatform.googleapis.com` (with or without `/v1beta1`)
 Hermes completes it to the `publishers/google` form; a base URL on any other host (a
 proxy) is never rewritten. Express keys are separate from the OAuth-based
-[Vertex AI provider](/guides/google-vertex), which needs no API key.
+[Vertex AI provider](./google-vertex.md), which needs no API key.
 
 ## Available Models
 
diff --git a/website/docs/guides/run-hermes-with-nous-portal.md b/website/docs/guides/run-hermes-with-nous-portal.md
index b100f1592b..75ecba41d2 100644
--- a/website/docs/guides/run-hermes-with-nous-portal.md
+++ b/website/docs/guides/run-hermes-with-nous-portal.md
@@ -6,12 +6,12 @@ description: "Start-to-finish walkthrough: subscribe, set up, switch models, ena
 
 # Run Hermes Agent with Nous Portal
 
-This guide walks you through running Hermes Agent on a [Nous Portal](https://portal.nousresearch.com) subscription end to end — from signing up to verifying that every tool routes correctly. If you just want the overview of what the Portal is and what's in the subscription, see the [Nous Portal integration page](/integrations/nous-portal). This page is the task script.
+This guide walks you through running Hermes Agent on a [Nous Portal](https://portal.nousresearch.com) subscription end to end — from signing up to verifying that every tool routes correctly. If you just want the overview of what the Portal is and what's in the subscription, see the [Nous Portal integration page](../integrations/nous-portal.md). This page is the task script.
 
 ## Prerequisites
 
-- Hermes Agent installed ([Quickstart](/getting-started/quickstart))
-- A web browser on the machine you're setting up (or SSH port forwarding — see [OAuth over SSH](/guides/oauth-over-ssh))
+- Hermes Agent installed ([Quickstart](../getting-started/quickstart.md))
+- A web browser on the machine you're setting up (or SSH port forwarding — see [OAuth over SSH](./oauth-over-ssh.md))
 - About 5 minutes
 
 You do **not** need: an OpenAI key, an Anthropic key, a Firecrawl account, a FAL account, a Browser Use account, or any other per-vendor credential. That's the whole point.
@@ -52,7 +52,7 @@ hermes auth add nous --type oauth
 # Then re-run `hermes setup --portal` to wire the provider + gateway
 ```
 
-See [OAuth over SSH / Remote Hosts](/guides/oauth-over-ssh) for the full walkthrough including ProxyJump chains, mosh/tmux, and ControlMaster gotchas.
+See [OAuth over SSH / Remote Hosts](./oauth-over-ssh.md) for the full walkthrough including ProxyJump chains, mosh/tmux, and ControlMaster gotchas.
 
 ## 3. Verify it worked
 
@@ -120,7 +120,7 @@ hermes config set model.default anthropic/claude-sonnet-4.6
 
 ### Don't pick Hermes-4 for agent work
 
-Hermes-4-70B and Hermes-4-405B are available on the Portal at deep discounts, but they're **chat/reasoning models**, not tool-call-tuned. They will struggle with multi-step agent loops. Use them for conversation/research work through the [subscription proxy](/user-guide/features/subscription-proxy) from non-agent tools. For Hermes Agent itself, stick to the frontier agentic models above.
+Hermes-4-70B and Hermes-4-405B are available on the Portal at deep discounts, but they're **chat/reasoning models**, not tool-call-tuned. They will struggle with multi-step agent loops. Use them for conversation/research work through the [subscription proxy](../user-guide/features/subscription-proxy.md) from non-agent tools. For Hermes Agent itself, stick to the frontier agentic models above.
 
 The Portal's own [info page](https://portal.nousresearch.com/info) carries this warning too — it's the official Nous guidance, not just a Hermes-side opinion.
 
@@ -148,7 +148,7 @@ You'll see per-tool routing — `via Nous Portal` for the ones routed through th
 
 ## 7. (Optional) Enable voice mode
 
-Because the Tool Gateway includes OpenAI TTS, [voice mode](/user-guide/features/voice-mode) works without a separate OpenAI key:
+Because the Tool Gateway includes OpenAI TTS, [voice mode](../user-guide/features/voice-mode.md) works without a separate OpenAI key:
 
 ```bash
 hermes setup tts
@@ -160,7 +160,7 @@ Then in any messaging-platform session (Telegram, Discord, Signal, etc.), send a
 
 ## 8. (Optional) Cron + always-on workflows
 
-The Portal subscription works for [cron jobs](/user-guide/features/cron) and [batch processing](/user-guide/features/batch-processing) the same way it works for interactive chat — the OAuth refresh token is reused automatically. No additional setup; just schedule cron jobs and they'll bill against your subscription.
+The Portal subscription works for [cron jobs](../user-guide/features/cron.md) and [batch processing](../user-guide/features/batch-processing.md) the same way it works for interactive chat — the OAuth refresh token is reused automatically. No additional setup; just schedule cron jobs and they'll bill against your subscription.
 
 ```bash
 hermes cron create "0 9 * * *" \
@@ -172,7 +172,7 @@ The cron job runs unattended, calls the model + web search + summarization all t
 
 ## Profiles and multi-user setups
 
-If you use [Hermes profiles](/user-guide/profiles) (e.g. a separate config per project), each profile is an independent credential island: a profile that has never signed in to the Portal fails closed instead of adopting another profile's session. Sign in once per profile with `hermes -p <name> portal` — when a shared Portal session already exists on the machine it offers to import it without a browser round-trip, and from then on the shared token store keeps that profile's token current. See [Profile setup](/integrations/nous-portal#profile-setup).
+If you use [Hermes profiles](../user-guide/profiles.md) (e.g. a separate config per project), each profile is an independent credential island: a profile that has never signed in to the Portal fails closed instead of adopting another profile's session. Sign in once per profile with `hermes -p <name> portal` — when a shared Portal session already exists on the machine it offers to import it without a browser round-trip, and from then on the shared token store keeps that profile's token current. See [Profile setup](../integrations/nous-portal.md#profile-setup).
 
 For team setups where multiple humans share a machine, each human has their own Portal account → each home directory holds its own `~/.hermes/auth.json` → no token sharing across users. This is the right boundary.
 
@@ -186,7 +186,7 @@ The OAuth flow didn't complete. Re-run it:
 hermes portal
 ```
 
-If your browser doesn't open or the callback fails, you're likely on a remote/headless host — see [OAuth over SSH](/guides/oauth-over-ssh) for the port-forwarding workarounds.
+If your browser doesn't open or the callback fails, you're likely on a remote/headless host — see [OAuth over SSH](./oauth-over-ssh.md) for the port-forwarding workarounds.
 
 ### "Model: currently openrouter" (or some other provider) instead of "using Nous as inference provider"
 
@@ -268,9 +268,9 @@ That's the deal. If you're using more than two of those backends anyway, the sub
 
 ## See also
 
-- **[Nous Portal integration page](/integrations/nous-portal)** — Overview of what's in the subscription
-- **[Tool Gateway](/user-guide/features/tool-gateway)** — Full details on every gateway-routed tool
-- **[Subscription proxy](/user-guide/features/subscription-proxy)** — Use your Portal subscription from non-Hermes tools
-- **[Voice mode](/user-guide/features/voice-mode)** — Set up voice conversations on the Portal subscription
-- **[OAuth over SSH](/guides/oauth-over-ssh)** — Remote / headless login patterns
-- **[Profiles](/user-guide/profiles)** — Share one Portal login across multiple Hermes configurations
+- **[Nous Portal integration page](../integrations/nous-portal.md)** — Overview of what's in the subscription
+- **[Tool Gateway](../user-guide/features/tool-gateway.md)** — Full details on every gateway-routed tool
+- **[Subscription proxy](../user-guide/features/subscription-proxy.md)** — Use your Portal subscription from non-Hermes tools
+- **[Voice mode](../user-guide/features/voice-mode.md)** — Set up voice conversations on the Portal subscription
+- **[OAuth over SSH](./oauth-over-ssh.md)** — Remote / headless login patterns
+- **[Profiles](../user-guide/profiles.md)** — Share one Portal login across multiple Hermes configurations
diff --git a/website/docs/integrations/nous-portal.md b/website/docs/integrations/nous-portal.md
index c0095af0bf..9cc2feb5bc 100644
--- a/website/docs/integrations/nous-portal.md
+++ b/website/docs/integrations/nous-portal.md
@@ -50,13 +50,13 @@ Because routing is per-model and not always through OpenRouter, OpenRouter-speci
 
 ### The Nous Tool Gateway
 
-The same subscription unlocks the [Tool Gateway](/user-guide/features/tool-gateway), which routes Hermes Agent's tool calls through Nous-managed infrastructure. Five backends, one login:
+The same subscription unlocks the [Tool Gateway](../user-guide/features/tool-gateway.md), which routes Hermes Agent's tool calls through Nous-managed infrastructure. Five backends, one login:
 
 | Tool | Partner | What it does |
 |------|---------|--------------|
 | **Web search & extract** | Firecrawl | Agent-grade search and full-page extraction. No Firecrawl API key, no rate limit babysitting. |
 | **Image generation** | FAL | Nine models under one endpoint: FLUX 2 Klein 9B, FLUX 2 Pro, Z-Image Turbo, Nano Banana Pro (Gemini 3 Pro Image), GPT Image 1.5, GPT Image 2, Ideogram V3, Recraft V4 Pro, Qwen Image. |
-| **Text-to-speech** | OpenAI TTS | High-quality TTS without a separate OpenAI key. Enables [voice mode](/user-guide/features/voice-mode) across messaging platforms. |
+| **Text-to-speech** | OpenAI TTS | High-quality TTS without a separate OpenAI key. Enables [voice mode](../user-guide/features/voice-mode.md) across messaging platforms. |
 | **Cloud browser automation** | Browser Use | Headless Chromium sessions for `browser_navigate`, `browser_click`, `browser_type`, `browser_vision`. No Browserbase account needed. |
 | **Cloud terminal sandbox** | Modal | Serverless terminal sandboxes for code execution (optional add-on). |
 
@@ -70,13 +70,13 @@ Because everything routes through one OAuth-authenticated Portal session, you do
 
 ### Cross-platform parity
 
-[Native Windows](/user-guide/windows-native) makes per-tool API key setup its rough edge — installing a Firecrawl account, a FAL account, a Browser Use account, an OpenAI key from Windows is the highest-friction part of getting a useful agent. A Portal subscription smooths that out: one OAuth covers the model and every gateway tool, so Windows users get the same experience as macOS/Linux without manually configuring four backends.
+[Native Windows](../user-guide/windows-native.md) makes per-tool API key setup its rough edge — installing a Firecrawl account, a FAL account, a Browser Use account, an OpenAI key from Windows is the highest-friction part of getting a useful agent. A Portal subscription smooths that out: one OAuth covers the model and every gateway tool, so Windows users get the same experience as macOS/Linux without manually configuring four backends.
 
 ## A note on Hermes 4
 
 Nous Research's own **Hermes 4** family (Hermes-4-70B, Hermes-4-405B) is available through the Portal at heavily discounted rates. These are **frontier hybrid-reasoning chat models** — strong at math, science, instruction following, schema adherence, roleplay, and long-form writing.
 
-They are **not recommended for use inside Hermes Agent**, however. Hermes 4 is tuned for chat and reasoning, not the rapid-fire tool-calling loop the agent relies on. Use them for research workflows or via the [subscription proxy](/user-guide/features/subscription-proxy) from other tooling — but for agent work, pick a frontier agentic model from the catalog instead:
+They are **not recommended for use inside Hermes Agent**, however. Hermes 4 is tuned for chat and reasoning, not the rapid-fire tool-calling loop the agent relies on. Use them for research workflows or via the [subscription proxy](../user-guide/features/subscription-proxy.md) from other tooling — but for agent work, pick a frontier agentic model from the catalog instead:
 
 ```bash
 /model anthropic/claude-sonnet-4.6     # best general-purpose agentic model
@@ -120,11 +120,11 @@ Your existing providers stay configured. You can switch between them with `/mode
 
 ### Headless / SSH / remote setup
 
-OAuth needs a browser, but the loopback callback runs on the machine where Hermes is running. For remote hosts, see [OAuth over SSH / Remote Hosts](/guides/oauth-over-ssh) — the same patterns work for the Portal as for any other OAuth-based provider (`ssh -L` port forwarding).
+OAuth needs a browser, but the loopback callback runs on the machine where Hermes is running. For remote hosts, see [OAuth over SSH / Remote Hosts](../guides/oauth-over-ssh.md) — the same patterns work for the Portal as for any other OAuth-based provider (`ssh -L` port forwarding).
 
 ### Profile setup {#profile-setup}
 
-If you use [Hermes profiles](/user-guide/profiles), the Portal refresh token is shared across profiles via a shared token store — but the store **refreshes an existing login, it does not create one**. Profiles are independent islands ([#111724](https://github.com/NousResearch/hermes-agent/issues/111724)), so a profile that has never signed in to the Portal has no Nous credentials of its own: at boot it fails closed with `Profile '<name>' is not connected to any AI provider yet` rather than silently adopting another profile's session.
+If you use [Hermes profiles](../user-guide/profiles.md), the Portal refresh token is shared across profiles via a shared token store — but the store **refreshes an existing login, it does not create one**. Profiles are independent islands ([#111724](https://github.com/NousResearch/hermes-agent/issues/111724)), so a profile that has never signed in to the Portal has no Nous credentials of its own: at boot it fails closed with `Profile '<name>' is not connected to any AI provider yet` rather than silently adopting another profile's session.
 
 Sign in **once per profile** with `hermes -p <name> portal` (alias for `hermes -p <name> auth add nous --type oauth`). When a shared Portal session already exists on the machine, that command offers to import it — one confirmation, no browser round-trip. After that first import the profile keeps its own state, and the shared store keeps its token current whenever any profile refreshes or re-logs in. `hermes profile create <name> --clone-all` from a signed-in profile also carries the Portal login (only single-use grants such as Anthropic/Codex are stripped from clones).
 
@@ -195,7 +195,7 @@ hermes tools
 # → TTS              → "Nous Subscription"
 ```
 
-The Tool Gateway is opt-in per tool, not all-or-nothing. The managed backends show up in `hermes tools` whether or not you're logged into Nous Portal — if you pick "Nous Subscription" before authenticating, Hermes runs the Portal login inline (it won't change your inference provider or touch your other tools). See the [Tool Gateway docs](/user-guide/features/tool-gateway) for the full per-tool configuration matrix.
+The Tool Gateway is opt-in per tool, not all-or-nothing. The managed backends show up in `hermes tools` whether or not you're logged into Nous Portal — if you pick "Nous Subscription" before authenticating, Hermes runs the Portal login inline (it won't change your inference provider or touch your other tools). See the [Tool Gateway docs](../user-guide/features/tool-gateway.md) for the full per-tool configuration matrix.
 
 ### Subscription management
 
@@ -280,9 +280,9 @@ Check `hermes portal info` first — if it shows you're using a different provid
 
 ## See also
 
-- **[Tool Gateway](/user-guide/features/tool-gateway)** — Full details on every gateway tool, per-tool config, and pricing
-- **[Subscription proxy](/user-guide/features/subscription-proxy)** — Use your Portal subscription from non-Hermes tools (other agents, scripts, third-party clients)
-- **[Voice mode](/user-guide/features/voice-mode)** — Voice conversations using the Portal's OpenAI TTS
-- **[AI Providers](/integrations/providers)** — Full provider catalog if you want to compare alternatives
-- **[OAuth over SSH](/guides/oauth-over-ssh)** — Login from remote hosts or browser-only environments
-- **[Profiles](/user-guide/profiles)** — Multiple Hermes configurations sharing one Portal login
+- **[Tool Gateway](../user-guide/features/tool-gateway.md)** — Full details on every gateway tool, per-tool config, and pricing
+- **[Subscription proxy](../user-guide/features/subscription-proxy.md)** — Use your Portal subscription from non-Hermes tools (other agents, scripts, third-party clients)
+- **[Voice mode](../user-guide/features/voice-mode.md)** — Voice conversations using the Portal's OpenAI TTS
+- **[AI Providers](./providers.md)** — Full provider catalog if you want to compare alternatives
+- **[OAuth over SSH](../guides/oauth-over-ssh.md)** — Login from remote hosts or browser-only environments
+- **[Profiles](../user-guide/profiles.md)** — Multiple Hermes configurations sharing one Portal login
diff --git a/website/docs/reference/slash-commands.md b/website/docs/reference/slash-commands.md
index 527735c827..1ecdcf5ab9 100644
--- a/website/docs/reference/slash-commands.md
+++ b/website/docs/reference/slash-commands.md
@@ -51,13 +51,13 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in
 | `/stop` | Kill all running background processes |
 | `/queue <prompt>` (alias: `/q`) | Queue a prompt for the next turn (doesn't interrupt the current agent response). In the CLI, `/queue` with no arguments lists the pending queue, and `/queue list`, `/queue edit N <new prompt>`, `/queue rm N`, `/queue move A B`, and `/queue clear` inspect and manage queued prompts before they are sent. Prompts that begin with a management word can be force-queued with `/queue add <prompt>`. |
 | `/steer <prompt>` | Inject a mid-run note that arrives at the agent **after the next tool call** — no interrupt, no new user turn. The text is appended to the last tool result's content once the current tool completes, giving the agent new context without breaking the current tool-calling loop. Use this to nudge direction mid-task (e.g. "focus on the auth module" while the agent is running tests). |
-| `/goal <text>` | Set a standing goal Hermes works toward across turns — our take on the Ralph loop. After each turn an auxiliary judge model decides whether the goal is done; if not, Hermes auto-continues. Subcommands: `/goal status`, `/goal pause`, `/goal resume`, `/goal clear`. Budget defaults to 20 turns (`goals.max_turns`); any real user message preempts the continuation loop, and state survives `/resume`. See [Persistent Goals](/user-guide/features/goals) for the full walkthrough. |
+| `/goal <text>` | Set a standing goal Hermes works toward across turns — our take on the Ralph loop. After each turn an auxiliary judge model decides whether the goal is done; if not, Hermes auto-continues. Subcommands: `/goal status`, `/goal pause`, `/goal resume`, `/goal clear`. Budget defaults to 20 turns (`goals.max_turns`); any real user message preempts the continuation loop, and state survives `/resume`. See [Persistent Goals](../user-guide/features/goals.md) for the full walkthrough. |
 | `/subgoal <text>` | Append a user-supplied criterion to the active goal mid-loop. The continuation prompt surfaces all subgoals to the agent verbatim, and the judge factors them into its DONE/CONTINUE verdict — so the goal isn't marked done until the original goal **and** every subgoal are met. Subcommands: `/subgoal` (list), `/subgoal remove <N>`, `/subgoal clear`. Requires an active `/goal`. |
-| `/heartbeat every <interval> <prompt>` (alias: `/hb`) | Set a recurring prompt that re-enters **this session** as a normal user turn whenever it's idle and the interval has elapsed (min 60s; missed ticks coalesce). Subcommands: `/heartbeat status`, `/heartbeat pause`, `/heartbeat resume`, `/heartbeat clear`. Session-scoped and in-process — use `hermes cron` for durable isolated schedules. See [Session Heartbeats](/user-guide/features/heartbeat). |
-| `/loop [interval] <prompt> [--times N] [--until <condition>]` (alias: `/proactive`) | Re-run a prompt (or another slash command) on a recurring interval in **this session** — fixed cadence (`/loop 5m check the deploy`) or continuous re-fire when no interval is given. `--times N` caps the run count; `--until <condition>` lets an auxiliary judge stop the loop when the condition is met. Subcommands: `/loop status`, `/loop pause`, `/loop resume`, `/loop stop`. See [Loops](/user-guide/features/loops). |
+| `/heartbeat every <interval> <prompt>` (alias: `/hb`) | Set a recurring prompt that re-enters **this session** as a normal user turn whenever it's idle and the interval has elapsed (min 60s; missed ticks coalesce). Subcommands: `/heartbeat status`, `/heartbeat pause`, `/heartbeat resume`, `/heartbeat clear`. Session-scoped and in-process — use `hermes cron` for durable isolated schedules. See [Session Heartbeats](../user-guide/features/heartbeat.md). |
+| `/loop [interval] <prompt> [--times N] [--until <condition>]` (alias: `/proactive`) | Re-run a prompt (or another slash command) on a recurring interval in **this session** — fixed cadence (`/loop 5m check the deploy`) or continuous re-fire when no interval is given. `--times N` caps the run count; `--until <condition>` lets an auxiliary judge stop the loop when the condition is met. Subcommands: `/loop status`, `/loop pause`, `/loop resume`, `/loop stop`. See [Loops](../user-guide/features/loops.md). |
 | `/refine [focus]` | Run the background memory/skill self-improvement review **now** instead of waiting for the automatic post-turn trigger. Optional focus text steers the review (e.g. `/refine save the deploy workflow as a skill`). Runs in a background fork against a conversation snapshot — the live session and prompt cache are untouched; results are reported when done. |
-| `/review [instructions]` | Spawn an independent, full-privilege reviewer subagent to review the work just discussed — a PR, code, docs, any artifact referenced in the last 10 chat messages. It investigates in the background (opens the PR, reads the diff, runs code) and its full review re-enters this session as a background-subagent completion the primary agent can act on. Pin a dedicated review model via `auxiliary.review` in config.yaml (defaults to your main model). See [Subagent Delegation](/user-guide/features/delegation#the-review-command). |
-| `/moa <prompt>` | Run a single prompt through the default [Mixture of Agents](/user-guide/features/mixture-of-agents) preset, then restore your current model. One-shot — does not change your session model. |
+| `/review [instructions]` | Spawn an independent, full-privilege reviewer subagent to review the work just discussed — a PR, code, docs, any artifact referenced in the last 10 chat messages. It investigates in the background (opens the PR, reads the diff, runs code) and its full review re-enters this session as a background-subagent completion the primary agent can act on. Pin a dedicated review model via `auxiliary.review` in config.yaml (defaults to your main model). See [Subagent Delegation](../user-guide/features/delegation.md#the-review-command). |
+| `/moa <prompt>` | Run a single prompt through the default [Mixture of Agents](../user-guide/features/mixture-of-agents.md) preset, then restore your current model. One-shot — does not change your session model. |
 | `/resume [name]` | Resume a previously-named session. Bare `/resume` lists this chat's named sessions ranked by most recent activity (a long-running conversation that compression has rotated several times counts as one entry, shown at its live tip). In the classic CLI this (and `/sessions <id>`) is refused while a turn is running — the CLI shares one agent across sessions, so switching mid-turn would file the rest of the running turn under the other session. |
 | `/sessions` (TUI alias: `/switch`) | Classic CLI: browse and resume previous sessions in an interactive picker. TUI: open the live session switcher for currently open TUI sessions. Use `/sessions new` in the TUI to start another live session immediately. |
 | `/egress [status]` | Show Docker egress proxy status — enabled/configured/running state, credential source, token mappings, uncovered providers, and next remediation step. Works in CLI, TUI, Desktop chat, and messaging gateway. |
@@ -65,12 +65,12 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in
 | `/status` | Show session info — model, provider, profile, session ID, working directory, title, created/updated timestamps, token totals, agent-running state — followed by a local **Session recap** block (recent user/assistant turn counts, tool result count, top tools used, last few files touched, the latest user prompt, and the latest assistant reply). The recap is computed locally from the in-memory conversation; no LLM call, no prompt-cache impact. |
 | `/context [all]` (alias: `/ctx`) | Visual context-window breakdown. On the CLI/TUI: a 5×20 glyph block grid (each cell ≈ 1% of the model window) plus an estimated per-category table — system prompt, tool definitions, rules, skills index, MCP, subagents, memory, conversation — versus free space. On messaging platforms: a usage gauge with auto-compression threshold/headroom, compression stats, cumulative throughput, and the same category table in plain text. On the CLI, messaging platforms, and TUI/Desktop sessions on a compute host, the output ends with a per-file **Context files** listing (.hermes.md, AGENTS.md chain, CLAUDE.md, .cursorrules + .cursor/rules/*.mdc, SOUL.md) showing each file's token estimate and whether it was loaded, truncated over `context_file_max_chars`, shadowed by a higher-priority context type, blocked by the injection scan, empty/unreadable, or suppressed by the install-tree guard — the answer to "why is my CLAUDE.md ignored?". `/context all` appends per-skill and per-toolset cost listings (index cost vs SKILL.md load cost; schema tokens per toolset). Read-only and computed locally — no LLM call, no prompt-cache impact. |
 | `/agents` (alias: `/tasks`) | Show active agents and running tasks across the current session. |
-| `/bg <prompt>` | Run a prompt in a separate background session. The agent processes your prompt independently — your current session stays free for other work. Results appear as a panel when the task finishes. See [CLI Background Sessions](/user-guide/cli#background-sessions). |
+| `/bg <prompt>` | Run a prompt in a separate background session. The agent processes your prompt independently — your current session stays free for other work. Results appear as a panel when the task finishes. See [CLI Background Sessions](../user-guide/cli.md#background-sessions). |
 | `/btw <question>` | Ask a quick side question **about the current conversation** without interrupting it. A one-shot auxiliary LLM call answers from a read-only snapshot of the transcript — the live session's history and prompt cache are untouched, and the current turn keeps running. For independent work with a fresh context, use `/bg`. |
 | `/branch [name]` (alias: `/fork`) | Branch the current session (explore a different path). Classic CLI: refused mid-turn like `/handoff` — wait for the current response to finish, then retry. |
-| `/worktree [new [name]\|list]` | **CLI only.** Inspect or create isolated git worktrees mid-session (inspired by Copilot CLI's `/worktree new`). Bare `/worktree` shows the active worktree; `/worktree list` lists the repo's worktrees; `/worktree new [name]` creates a worktree under `.worktrees/` (branched from the freshly-fetched remote tip, honoring `worktree_sync`) and retargets the session's terminal and file tools into it. Named trees use your name (`hermes/<name>` branch); unnamed ones get a random `hermes-<id>`. On exit the tree is kept only if it has unpushed commits — same lifecycle as `hermes -w`. See [Git Worktrees](/user-guide/git-worktrees). |
-| `/handoff <platform>` | **CLI only.** Hand the current session off to a messaging platform (Telegram, Discord, Slack, WhatsApp, Signal, Matrix). The gateway picks it up immediately, creates a fresh thread on platforms that support threads (Telegram topics, Discord text-channel threads, Slack and Matrix message-anchored threads), re-binds the destination to your CLI session_id so the full role-aware transcript replays, and forges a synthetic user turn so the agent confirms it's working in the new place. Your CLI exits cleanly on success with a `/resume` hint; resume locally any time with `/resume <title>`. Refused mid-turn. Requires the gateway to be running and a home channel configured for the target platform (`/sethome` from the destination chat). See [Cross-Platform Handoff](/user-guide/sessions#cross-platform-handoff). |
-| `/journey [list\|delete <id>\|edit <id>]` (aliases: `/learning`, `/memory-graph`) | Open the learning journey timeline of learned skills + memories. Works in the classic CLI, as a TUI overlay, and in the desktop app (Star Map panel). Not available on messaging platforms. See [Learning Journey](/user-guide/features/memory#learning-journey-journey). |
+| `/worktree [new [name]\|list]` | **CLI only.** Inspect or create isolated git worktrees mid-session (inspired by Copilot CLI's `/worktree new`). Bare `/worktree` shows the active worktree; `/worktree list` lists the repo's worktrees; `/worktree new [name]` creates a worktree under `.worktrees/` (branched from the freshly-fetched remote tip, honoring `worktree_sync`) and retargets the session's terminal and file tools into it. Named trees use your name (`hermes/<name>` branch); unnamed ones get a random `hermes-<id>`. On exit the tree is kept only if it has unpushed commits — same lifecycle as `hermes -w`. See [Git Worktrees](../user-guide/git-worktrees.md). |
+| `/handoff <platform>` | **CLI only.** Hand the current session off to a messaging platform (Telegram, Discord, Slack, WhatsApp, Signal, Matrix). The gateway picks it up immediately, creates a fresh thread on platforms that support threads (Telegram topics, Discord text-channel threads, Slack and Matrix message-anchored threads), re-binds the destination to your CLI session_id so the full role-aware transcript replays, and forges a synthetic user turn so the agent confirms it's working in the new place. Your CLI exits cleanly on success with a `/resume` hint; resume locally any time with `/resume <title>`. Refused mid-turn. Requires the gateway to be running and a home channel configured for the target platform (`/sethome` from the destination chat). See [Cross-Platform Handoff](../user-guide/sessions.md#cross-platform-handoff). |
+| `/journey [list\|delete <id>\|edit <id>]` (aliases: `/learning`, `/memory-graph`) | Open the learning journey timeline of learned skills + memories. Works in the classic CLI, as a TUI overlay, and in the desktop app (Star Map panel). Not available on messaging platforms. See [Learning Journey](../user-guide/features/memory.md#learning-journey-journey). |
 
 ### Configuration
 
@@ -105,23 +105,23 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in
 | `/tools [list\|disable\|enable] [name...]` | Manage tools: list available tools, or disable/enable specific tools for the current session. Disabling a tool removes it from the agent's toolset and triggers a session reset. |
 | `/toolsets` | List available toolsets |
 | `/browser [connect\|disconnect\|status]` | Manage a local Chromium-family CDP connection. `connect` attaches browser tools to a running Chrome, Brave, Chromium, or Edge instance (default: `http://127.0.0.1:9222`). `disconnect` detaches. `status` shows current connection. Auto-launches a supported Chromium-family browser if no debugger is detected. |
-| `/skills` | Search, install, inspect, or manage skills from online registries. Also the review surface for the skill write-approval gate: `/skills pending`, `/skills diff <id>`, `/skills approve <id>`, `/skills reject <id>`, `/skills approval on\|off`. See [Gating agent skill writes](/user-guide/features/skills#gating-agent-skill-writes-skillswrite_approval). |
-| `/memory [pending\|approve\|reject\|approval]` | Review pending memory writes staged by the write-approval gate (`memory.write_approval`) and toggle the gate. See [Controlling memory writes](/user-guide/features/memory#controlling-memory-writes-write_approval). |
-| `/bundles` | List configured skill bundles — `/<name>` slash aliases that preload several skills at once. Configure under `bundles:` in `~/.hermes/config.yaml`. See [Skill Bundles](/user-guide/features/skills#skill-bundles). |
+| `/skills` | Search, install, inspect, or manage skills from online registries. Also the review surface for the skill write-approval gate: `/skills pending`, `/skills diff <id>`, `/skills approve <id>`, `/skills reject <id>`, `/skills approval on\|off`. See [Gating agent skill writes](../user-guide/features/skills.md#gating-agent-skill-writes-skillswrite_approval). |
+| `/memory [pending\|approve\|reject\|approval]` | Review pending memory writes staged by the write-approval gate (`memory.write_approval`) and toggle the gate. See [Controlling memory writes](../user-guide/features/memory.md#controlling-memory-writes-write_approval). |
+| `/bundles` | List configured skill bundles — `/<name>` slash aliases that preload several skills at once. Configure under `bundles:` in `~/.hermes/config.yaml`. See [Skill Bundles](../user-guide/features/skills.md#skill-bundles). |
 | `/learn <what to learn from>` | Distill a reusable skill from anything you describe — a directory, a URL, the workflow you just walked the agent through, or pasted notes. Open-ended: the agent gathers the sources with its own tools and authors a `SKILL.md` following the house authoring standards. Works in the CLI, the messaging gateway, the TUI, and the dashboard Skills page. |
 | `/plan [task]` | Write a markdown implementation plan to `.hermes/plans/` in the active workspace — planning only, no execution. Empty argument infers the task from the conversation. (Formerly the bundled `plan` skill; now built-in so it survives the Telegram/Discord command-menu caps.) |
 | `/init [notes]` | Generate or update `AGENTS.md` project instructions from a repo scan (port of Codex `/init`). The agent inspects manifests, layout, and toolchain configs with its read-only tools, then writes a concise `AGENTS.md` — or, if one exists, merge-updates it preserving your content. Optional notes steer the emphasis. Works in the CLI, the messaging gateway, and the TUI. |
 | `/cron` | Manage scheduled tasks (list, add/create, edit, pause, resume, run, remove) |
 | `/suggestions [accept\|dismiss N\|catalog\|clear]` (alias: `/suggest`) | Review suggested automations. Use `/suggestions` to list pending suggestions, `/suggestions accept <id>` to create the proposed automation, `/suggestions dismiss <id>` to reject one, `/suggestions catalog` to add curated starter automations, and `/suggestions clear` to clear resolved suggestion records. Accepted jobs preserve the current surface as the delivery origin. |
 | `/blueprint [name] [slot=value ...]` (alias: `/bp`) | Set up an automation from a blueprint template. Bare `/blueprint` lists the catalog; `/blueprint <name>` starts a guided slot-filling flow on the next agent turn; `/blueprint <name> slot=value ...` creates the job directly. |
-| `/curator` | Background skill maintenance — `status`, `run`, `pin`, `archive`. See [Curator](/user-guide/features/curator). |
-| `/kanban <action>` | Drive the multi-profile, multi-project collaboration board without leaving chat. Full `hermes kanban` surface is available: `/kanban list`, `/kanban show t_abc`, `/kanban create "title" --assignee X`, `/kanban comment t_abc "text"`, `/kanban unblock t_abc`, `/kanban dispatch`, etc. Multi-board support included: `/kanban boards list`, `/kanban boards create <slug>`, `/kanban boards switch <slug>`, `/kanban --board <slug> <action>`. See [Kanban slash command](/user-guide/features/kanban#kanban-slash-command). |
+| `/curator` | Background skill maintenance — `status`, `run`, `pin`, `archive`. See [Curator](../user-guide/features/curator.md). |
+| `/kanban <action>` | Drive the multi-profile, multi-project collaboration board without leaving chat. Full `hermes kanban` surface is available: `/kanban list`, `/kanban show t_abc`, `/kanban create "title" --assignee X`, `/kanban comment t_abc "text"`, `/kanban unblock t_abc`, `/kanban dispatch`, etc. Multi-board support included: `/kanban boards list`, `/kanban boards create <slug>`, `/kanban boards switch <slug>`, `/kanban --board <slug> <action>`. See [Kanban slash command](../user-guide/features/kanban.md#kanban-slash-command). |
 | `/reload-mcp` (alias: `/reload_mcp`) | Reload MCP servers from config.yaml and re-probe tool availability (credentials/daemons that appeared mid-session) |
 | `/reload-skills` (alias: `/reload_skills`) | Re-scan `~/.hermes/skills/` for newly installed or removed skills |
 | `/reload` | Reload `.env` variables into the running session (picks up new API keys without restarting) |
 | `/plugins` | List installed plugins and their status |
-| `/pet [list\|<slug>]` | Toggle or adopt a [petdex](/user-guide/features/pets) mascot. `/pet` toggles the pane, `/pet list` shows installed pets, `/pet <slug>` adopts a specific one. |
-| `/hatch <description>` (alias: `/generate-pet`) | Generate a brand-new petdex pet from a text description, using the configured image backend (OpenRouter / Nous Portal). See [Pets](/user-guide/features/pets). |
+| `/pet [list\|<slug>]` | Toggle or adopt a [petdex](../user-guide/features/pets.md) mascot. `/pet` toggles the pane, `/pet list` shows installed pets, `/pet <slug>` adopts a specific one. |
+| `/hatch <description>` (alias: `/generate-pet`) | Generate a brand-new petdex pet from a text description, using the configured image backend (OpenRouter / Nous Portal). See [Pets](../user-guide/features/pets.md). |
 
 ### Info
 
@@ -235,7 +235,7 @@ Commands support prefix matching: typing `/h` resolves to `/help`, `/mod` resolv
 ## Messaging slash commands
 
 > **Slack thread commands (`!` prefix):**
-> Slack itself blocks native slash commands inside message threads ("/queue is not supported in threads. Sorry!") and never delivers them to Hermes. Inside a Slack thread, use the `!` prefix instead — `!stop`, `!new`, `!status` — and the gateway dispatches it exactly like the slash form. `@Hermes !stop` and `@Hermes /stop` work in threads too. Only the first token is checked against the known command list, so messages like `!nice work` pass through to the agent unchanged. See [Using commands inside threads](/user-guide/messaging/slack#using-commands-inside-threads-the-cmd-prefix) for details.
+> Slack itself blocks native slash commands inside message threads ("/queue is not supported in threads. Sorry!") and never delivers them to Hermes. Inside a Slack thread, use the `!` prefix instead — `!stop`, `!new`, `!status` — and the gateway dispatches it exactly like the slash form. `@Hermes !stop` and `@Hermes /stop` work in threads too. Only the first token is checked against the known command list, so messages like `!nice work` pass through to the agent unchanged. See [Using commands inside threads](../user-guide/messaging/slack.md#using-commands-inside-threads-the-cmd-prefix) for details.
 
 The messaging gateway supports the following built-in commands inside Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant, and Teams chats:
 
@@ -253,7 +253,7 @@ The messaging gateway supports the following built-in commands inside Telegram,
 | `/undo` | Remove the last exchange. |
 | `/sethome` (alias: `/set-home`) | Mark the current chat as the platform home channel for deliveries. |
 | `/compress [here [N] \| focus topic]` | Manually compress conversation context. `/compress here [N]` keeps the most recent N exchanges (default 2) verbatim and summarizes the rest. A focus topic narrows what a full summary preserves. |
-| `/topic [off\|help\|session-id]` | **Telegram DM only.** Manage user-managed multi-session topic mode. `/topic` enables it or shows status; `/topic off` disables it and clears bindings; `/topic help` shows usage; `/topic <session-id>` inside a topic restores a previous session. See [Multi-session DM mode](/user-guide/messaging/telegram#multi-session-dm-mode-topic). |
+| `/topic [off\|help\|session-id]` | **Telegram DM only.** Manage user-managed multi-session topic mode. `/topic` enables it or shows status; `/topic off` disables it and clears bindings; `/topic help` shows usage; `/topic <session-id>` inside a topic restores a previous session. See [Multi-session DM mode](../user-guide/messaging/telegram.md#multi-session-dm-mode-topic). |
 | `/title [name]` | Set or show the session title. |
 | `/resume [name]` | Resume a previously named session. |
 | `/sessions [all] [search <query>]` | List previous sessions for this chat; the active session appears with a `(current)` marker. `/sessions search <query>` filters by title/id match (most recently active first); `/sessions all` lists across origins (admin only — non-admins get a notice and the chat-scoped list). |
@@ -266,17 +266,17 @@ The messaging gateway supports the following built-in commands inside Telegram,
 | `/voice [on\|off\|tts\|join\|channel\|leave\|status]` | Control spoken replies in chat. `join`/`channel`/`leave` manage Discord voice-channel mode. |
 | `/rollback [number]` | List or restore filesystem checkpoints. |
 | `/diff [staged\|all\|session] [--stat]` | Show git changes in the working directory (fenced and truncated to platform message limits). `session` shows the cumulative diff of everything Hermes changed; `--stat` shows just the summary. |
-| `/bg <prompt>` | Run a prompt in a separate background session. Results are delivered back to the same chat when the task finishes. See [Messaging Background Sessions](/user-guide/messaging/#background-sessions). |
+| `/bg <prompt>` | Run a prompt in a separate background session. Results are delivered back to the same chat when the task finishes. See [Messaging Background Sessions](../user-guide/messaging/index.md#background-sessions). |
 | `/btw <question>` | Ask a side question about the current conversation without interrupting it. Answered from a transcript snapshot; the answer is sent to the chat when ready. |
 | `/queue <prompt>` (alias: `/q`) | Queue a prompt for the next turn without interrupting the current one. |
 | `/steer <prompt>` | Inject a message after the next tool call without interrupting — the model picks it up on its next iteration rather than as a new turn. |
-| `/goal <text>` | Set a standing goal Hermes works toward across turns — our take on the Ralph loop. A judge model checks after each turn; if not done, Hermes auto-continues until it is, you pause/clear it, or the turn budget (default 20) is hit. Subcommands: `/goal status`, `/goal pause`, `/goal resume`, `/goal clear`. Safe to run mid-agent for status/pause/clear; setting a new goal requires `/stop` first. See [Persistent Goals](/user-guide/features/goals). |
+| `/goal <text>` | Set a standing goal Hermes works toward across turns — our take on the Ralph loop. A judge model checks after each turn; if not done, Hermes auto-continues until it is, you pause/clear it, or the turn budget (default 20) is hit. Subcommands: `/goal status`, `/goal pause`, `/goal resume`, `/goal clear`. Safe to run mid-agent for status/pause/clear; setting a new goal requires `/stop` first. See [Persistent Goals](../user-guide/features/goals.md). |
 | `/subgoal <text>` | Append criteria to the active `/goal` mid-loop (`/subgoal`, `/subgoal remove <N>`, `/subgoal clear`). |
 | `/heartbeat every <interval> <prompt>` (alias: `/hb`) | Set a recurring prompt that re-enters this session when idle. Subcommands: `status`, `pause`, `resume`, `clear`. On Slack use `/hermes heartbeat …`. |
-| `/loop [interval] <prompt> [--times N] [--until <condition>]` (alias: `/proactive`) | Re-run a prompt on a recurring interval in this session. Subcommands: `status`, `pause`, `resume`, `stop`. See [Loops](/user-guide/features/loops). |
+| `/loop [interval] <prompt> [--times N] [--until <condition>]` (alias: `/proactive`) | Re-run a prompt on a recurring interval in this session. Subcommands: `status`, `pause`, `resume`, `stop`. See [Loops](../user-guide/features/loops.md). |
 | `/refine [focus]` | Run the memory/skill self-improvement review now, optionally with focus instructions. On Slack use `/hermes refine …`. |
 | `/review [instructions]` | Spawn an independent reviewer subagent for the work just discussed (PR, code, docs); its review re-enters this chat when done. On Slack use `/hermes review …`. |
-| `/moa <prompt>` | Run one prompt through the default [Mixture of Agents](/user-guide/features/mixture-of-agents) preset, then restore the session model. |
+| `/moa <prompt>` | Run one prompt through the default [Mixture of Agents](../user-guide/features/mixture-of-agents.md) preset, then restore the session model. |
 | `/branch [name]` (alias: `/fork`) | Branch the current session (explore a different path). |
 | `/agents` (alias: `/tasks`) | Show active agents and running tasks. |
 | `/sessions` | Browse and resume previous sessions. |
@@ -291,9 +291,9 @@ The messaging gateway supports the following built-in commands inside Telegram,
 | `/curator [status\|run\|pin\|archive]` | Background skill maintenance controls. |
 | `/suggestions [accept\|dismiss N\|catalog\|clear]` | Review suggested automations right in chat. `/suggestions` lists pending suggestions, `catalog` adds curated starter automations, and `clear` prunes resolved suggestion records. Accepted suggestions keep this chat/thread as the job delivery origin. |
 | `/blueprint [name] [slot=value ...]` | Browse cron blueprints, start a guided slot-filling conversation, or create a blueprint job directly. Directly created jobs deliver back to the current chat/thread. |
-| `/memory [pending\|approve\|reject\|approval]` | Review pending memory writes staged by the write-approval gate (`memory.write_approval`) — approve or reject them right in chat — and toggle the gate with `/memory approval on\|off`. See [Controlling memory writes](/user-guide/features/memory#controlling-memory-writes-write_approval). |
+| `/memory [pending\|approve\|reject\|approval]` | Review pending memory writes staged by the write-approval gate (`memory.write_approval`) — approve or reject them right in chat — and toggle the gate with `/memory approval on\|off`. See [Controlling memory writes](../user-guide/features/memory.md#controlling-memory-writes-write_approval). |
 | `/skills [pending\|approve\|reject\|diff\|approval]` | Review pending **skill** writes staged by the write-approval gate (`skills.write_approval`). Shows a one-line gist per staged write; `/skills diff <id>` is truncated for chat — read the full diff on the CLI or in `~/.hermes/pending/skills/<id>.json`. Only appears when the gate is on (or staged writes remain); search/install stay CLI-only. |
-| `/kanban <action>` | Drive the multi-profile, multi-project collaboration board from chat — identical argument surface to the CLI. Bypasses the running-agent guard, so `/kanban unblock t_abc`, `/kanban comment t_abc "…"`, `/kanban list --mine`, `/kanban boards switch <slug>`, etc. work mid-turn. `/kanban create …` auto-subscribes the originating chat to the new task's terminal events. See [Kanban slash command](/user-guide/features/kanban#kanban-slash-command). |
+| `/kanban <action>` | Drive the multi-profile, multi-project collaboration board from chat — identical argument surface to the CLI. Bypasses the running-agent guard, so `/kanban unblock t_abc`, `/kanban comment t_abc "…"`, `/kanban list --mine`, `/kanban boards switch <slug>`, etc. work mid-turn. `/kanban create …` auto-subscribes the originating chat to the new task's terminal events. See [Kanban slash command](../user-guide/features/kanban.md#kanban-slash-command). |
 | `/platform <list\|pause\|resume> [name]` | Operate a running gateway platform right from chat. `/platform list` shows every adapter and its state (running, paused-by-breaker, manually-paused); `/platform pause <name>` stops dispatching new messages to that adapter without unloading it; `/platform resume <name>` re-enables it and clears a tripped circuit breaker once the upstream is healthy. |
 | `/reload-mcp` (alias: `/reload_mcp`) | Reload MCP servers from config and re-probe tool availability. |
 | `/verbose` | Cycle tool progress display. **Off by default on messaging** — enable with `display.tool_progress_command: true` in `config.yaml`. |
diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md
index 006ecf1cb3..4c8e471466 100644
--- a/website/docs/user-guide/configuration.md
+++ b/website/docs/user-guide/configuration.md
@@ -9,7 +9,7 @@ description: "Configure Hermes Agent — config.yaml, providers, models, API key
 All settings are stored in the `~/.hermes/` directory for easy access.
 
 :::tip Easiest path to a working `config.yaml`
-Run `hermes setup --portal` — one OAuth gets you a model provider and all four Tool Gateway tools without hand-editing YAML. Portal subscribers also get 10% off token-billed providers. See [Nous Portal](/integrations/nous-portal).
+Run `hermes setup --portal` — one OAuth gets you a model provider and all four Tool Gateway tools without hand-editing YAML. Portal subscribers also get 10% off token-billed providers. See [Nous Portal](../integrations/nous-portal.md).
 :::
 
 ## Directory Structure
@@ -66,7 +66,7 @@ Secrets (API keys, bot tokens, passwords) go in `.env`. Everything else (model,
 :::tip Org deployments
 An administrator can pin specific config and secret values that a standard user
 cannot override, via a system-level managed directory. See
-[Managed Scope](/user-guide/managed-scope).
+[Managed Scope](./managed-scope.md).
 :::
 
 ## Runtime Limits
@@ -148,11 +148,11 @@ delegation:
 
 Multiple references in a single value work: `url: "${HOST}:${PORT}"`. If a referenced variable is not set, the placeholder is kept verbatim (`${UNDEFINED_VAR}` stays as-is) and a warning is logged. Bare `$VAR` is not expanded.
 
-Under a [multiplexed multi-profile gateway](/user-guide/multi-profile-gateways), references in a profile's `config.yaml` resolve against **that profile's** `.env` (its secret scope), not the shared process environment — a `${MATRIX_ACCESS_TOKEN}` in profile B stays unresolved (kept verbatim, warning logged) unless B defines the variable itself. This holds wherever B's config is loaded inside the multiplexer: routed gateway turns, B's adapter startup, and B's cron jobs. Single-profile runs are unchanged. See [What is isolated per profile](/user-guide/multi-profile-gateways#what-is-isolated-per-profile) for the full list.
+Under a [multiplexed multi-profile gateway](./multi-profile-gateways.md), references in a profile's `config.yaml` resolve against **that profile's** `.env` (its secret scope), not the shared process environment — a `${MATRIX_ACCESS_TOKEN}` in profile B stays unresolved (kept verbatim, warning logged) unless B defines the variable itself. This holds wherever B's config is loaded inside the multiplexer: routed gateway turns, B's adapter startup, and B's cron jobs. Single-profile runs are unchanged. See [What is isolated per profile](./multi-profile-gateways.md#what-is-isolated-per-profile) for the full list.
 
 Cursor-style SecretRef syntax is also accepted: `${env:VAR_NAME}` resolves exactly like `${VAR_NAME}` (the `env:` prefix is stripped), so MCP or provider snippets copied from Cursor / Claude configs work unchanged in both `config.yaml` and the `mcp_servers` block. Other SecretRef sources (`${file:...}`, `${vault:...}`, `${bitwarden:...}`) are **not** resolved inline — external secret backends inject their values into the environment at startup via the `secrets:` block, so reference them as `${env:NAME}` instead; unknown prefixes warn once and stay verbatim.
 
-For AI provider setup (OpenRouter, Anthropic, Copilot, custom endpoints, self-hosted LLMs, fallback models, etc.), see [AI Providers](/integrations/providers).
+For AI provider setup (OpenRouter, Anthropic, Copilot, custom endpoints, self-hosted LLMs, fallback models, etc.), see [AI Providers](../integrations/providers.md).
 
 ### Provider Timeouts
 
@@ -775,7 +775,7 @@ skills:
 hermes config set skills.config.myplugin.path ~/myplugin-data
 ```
 
-For details on declaring config settings in your own skills, see [Creating Skills — Config Settings](/developer-guide/creating-skills#config-settings-configyaml).
+For details on declaring config settings in your own skills, see [Creating Skills — Config Settings](../developer-guide/creating-skills.md#config-settings-configyaml).
 
 ### Auto-loading skills every session
 
@@ -788,7 +788,7 @@ skills:
     - github-pr-workflow
 ```
 
-Resolved once per session when the system prompt is first built (so the prompt stays cache-stable; edits apply to the next session). Missing or disabled skills warn and are skipped; `--ignore-rules` / `HERMES_IGNORE_RULES=1` suppresses the list. Profile-scoped. See [CLI — persistent auto-load](/user-guide/cli#persistent-auto-load-via-config).
+Resolved once per session when the system prompt is first built (so the prompt stays cache-stable; edits apply to the next session). Missing or disabled skills warn and are skipped; `--ignore-rules` / `HERMES_IGNORE_RULES=1` suppresses the list. Profile-scoped. See [CLI — persistent auto-load](./cli.md#persistent-auto-load-via-config).
 
 ### Guard on agent-created skill writes
 
@@ -810,7 +810,7 @@ skills:
   write_approval: false   # false = write freely (default) | true = stage every write for review
 ```
 
-When on, skill writes are staged under `~/.hermes/pending/skills/` and reviewed with `/skills pending`, `/skills diff <id>`, `/skills approve <id>`, `/skills reject <id>` — from the CLI or any messaging platform. Toggle at runtime with `/skills approval on|off`. Memory has the same gate (`memory.write_approval`, below). Full walkthrough: [Gating agent skill writes](/user-guide/features/skills#gating-agent-skill-writes-skillswrite_approval).
+When on, skill writes are staged under `~/.hermes/pending/skills/` and reviewed with `/skills pending`, `/skills diff <id>`, `/skills approve <id>`, `/skills reject <id>` — from the CLI or any messaging platform. Toggle at runtime with `/skills approval on|off`. Memory has the same gate (`memory.write_approval`, below). Full walkthrough: [Gating agent skill writes](./features/skills.md#gating-agent-skill-writes-skillswrite_approval).
 
 ## Memory Configuration
 
@@ -823,7 +823,7 @@ memory:
   write_approval: false     # true = require approval before any memory write
 ```
 
-With `memory.write_approval: true`, memory writes need your approval before they land: interactive CLI turns prompt inline; messaging sessions and the background self-improvement review stage the write for `/memory pending` → `/memory approve <id>` / `/memory reject <id>` review. Toggle at runtime with `/memory approval on|off`. See [Controlling memory writes](/user-guide/features/memory#controlling-memory-writes-write_approval).
+With `memory.write_approval: true`, memory writes need your approval before they land: interactive CLI turns prompt inline; messaging sessions and the background self-improvement review stage the write for `/memory pending` → `/memory approve <id>` / `/memory reject <id>` review. Toggle at runtime with `/memory approval on|off`. See [Controlling memory writes](./features/memory.md#controlling-memory-writes-write_approval).
 
 ## Context File Truncation
 
@@ -1150,7 +1150,7 @@ Agent cache pressure: anon RSS 6802MB over budget 6656MB — evicting 5 LRU sess
 
 ## Context Engine
 
-The context engine controls how conversations are managed when approaching the model's token limit. The built-in `compressor` engine uses lossy summarization (see [Context Compression](/developer-guide/context-compression-and-caching)). Plugin engines can replace it with alternative strategies.
+The context engine controls how conversations are managed when approaching the model's token limit. The built-in `compressor` engine uses lossy summarization (see [Context Compression](../developer-guide/context-compression-and-caching.md)). Plugin engines can replace it with alternative strategies.
 
 ```yaml
 context:
@@ -1166,7 +1166,7 @@ context:
 
 Plugin engines are **never auto-activated** — you must explicitly set `context.engine` to the plugin name. Available engines can be browsed and selected via `hermes plugins` → Provider Plugins → Context Engine.
 
-See [Memory Providers](/user-guide/features/memory-providers) for the analogous single-select system for memory plugins.
+See [Memory Providers](./features/memory-providers.md) for the analogous single-select system for memory plugins.
 
 ## Iteration Budget
 
@@ -1187,7 +1187,7 @@ agent:
 
 `agent.budget_warning_ratio` is off by default for ordinary and delegated conversations. When set to a value strictly between `0` and `1` alongside a finite `max_turns`, Hermes appends one model-visible checkpoint notice to the latest tool result after the threshold is reached. The notice rearms each conversation turn and uses each agent's own iteration budget. It only appends to a current tool-result tail, never an older turn, and does not add a synthetic user/system message or change the existing exhaustion grace call. Dispatcher-owned Kanban workers receive a completion checkpoint at 90% by default (an explicit ratio changes that threshold), while their tools are still available. The checkpoint asks for verified completion or a durable progress comment, not premature success.
 
-`agent.api_max_retries` controls how many times Hermes retries a provider API call on transient errors (rate limits, connection drops, 5xx) **before** fallback-provider switching engages. The default is `3` — four attempts total. If you have [fallback providers](/user-guide/features/fallback-providers) configured and want to fail over faster, drop this to `0` so the first transient error on your primary immediately hands off to the fallback instead of churning retries against the flaky endpoint.
+`agent.api_max_retries` controls how many times Hermes retries a provider API call on transient errors (rate limits, connection drops, 5xx) **before** fallback-provider switching engages. The default is `3` — four attempts total. If you have [fallback providers](./features/fallback-providers.md) configured and want to fail over faster, drop this to `0` so the first transient error on your primary immediately hands off to the fallback instead of churning retries against the flaky endpoint.
 
 ## Wall-Clock Run Budget
 
@@ -1227,7 +1227,7 @@ agent:
 
 The evidence that feeds this guard (which test/lint/build commands ran, which files were edited since) lives in `~/.hermes/verification_evidence.db`. That ledger is only written or created while the guard is enabled; with `verify_on_stop: false` nothing is recorded and an existing file can be deleted freely.
 
-For a user/plugin policy gate at the same point — keep the agent going with your own checks — see the [`pre_verify` hook](/user-guide/features/hooks#pre_verify).
+For a user/plugin policy gate at the same point — keep the agent going with your own checks — see the [`pre_verify` hook](./features/hooks.md#pre_verify).
 
 ## Standing Goals (`/goal`)
 
@@ -1238,7 +1238,7 @@ goals:
   max_turns: 20   # Max continuation turns before Hermes auto-pauses the goal (default: 20)
 ```
 
-`max_turns` caps how many continuation turns a goal can drive before Hermes auto-pauses it and asks the user to `/goal resume`. It protects against judge false negatives (goal actually done but judge says continue) and unbounded model spend on fuzzy or unachievable goals. See [Goals](/user-guide/features/goals) for the full feature.
+`max_turns` caps how many continuation turns a goal can drive before Hermes auto-pauses it and asks the user to `/goal resume`. It protects against judge false negatives (goal actually done but judge says continue) and unbounded model spend on fuzzy or unachievable goals. See [Goals](./features/goals.md) for the full feature.
 
 ### API Timeouts
 
@@ -1309,7 +1309,7 @@ credential_pool_strategies:
   anthropic: least_used      # always pick the least-used key
 ```
 
-Options: `fill_first` (default), `round_robin`, `least_used`, `random`. See [Credential Pools](/user-guide/features/credential-pools) for full documentation.
+Options: `fill_first` (default), `round_robin`, `least_used`, `random`. See [Credential Pools](./features/credential-pools.md) for full documentation.
 
 ## Prompt caching
 
@@ -1317,7 +1317,7 @@ Hermes turns on cross-session prompt caching automatically when the active provi
 
 For Claude on **native Anthropic**, **OpenRouter**, and **Nous Portal**, Hermes attaches `cache_control` breakpoints with the 1-hour TTL (`ttl: "1h"`) on the system prompt and skill blocks. The first send within a fresh hour pays full input rates; subsequent sends across any session within the same hour pull from the cache at the discounted cached-read rate. This means the system prompt, loaded skill content, and the early portion of any long-context include get reused across `hermes` sessions and across forked subagents for the first hour.
 
-The Qwen Cloud (Alibaba DashScope) upstream caps cache TTL at 5 minutes, so Hermes uses the 5-minute breakpoint TTL there instead. Other Claude-via-third-party paths (AWS Bedrock, Azure Foundry) fall back to the provider's own caching defaults. xAI Grok uses a separate session-pinned conversation-id mechanism — see [xAI prompt caching](/integrations/providers#xai-grok--responses-api--prompt-caching).
+The Qwen Cloud (Alibaba DashScope) upstream caps cache TTL at 5 minutes, so Hermes uses the 5-minute breakpoint TTL there instead. Other Claude-via-third-party paths (AWS Bedrock, Azure Foundry) fall back to the provider's own caching defaults. xAI Grok uses a separate session-pinned conversation-id mechanism — see [xAI prompt caching](../integrations/providers.md#xai-grok--responses-api--prompt-caching).
 
 No knob exists to disable this — caching is always-on and saves money even on single-turn conversations because the system prompt alone is a meaningful fraction of the input token count.
 
@@ -1421,9 +1421,9 @@ This is the per-task counterpart of the global `agent.reasoning_effort`: run com
 
 If the endpoint rejects the reasoning field outright (a chat-only model behind an OpenAI-compatible relay answering `400 Unrecognized request argument supplied: reasoning_effort`, or the reversed wording `400 reasoning_effort 'none' unsupported; use minimal|low|medium|high|xhigh`), the auxiliary call is retried once with every reasoning field omitted, so the task (for example the session title) still completes with the endpoint's default behaviour. The main conversation applies the same recovery: when a route rejects the reasoning-off request Hermes sends for a thinking-only truncated continuation, the disable is dropped for the rest of the session and the request is retried with the route's default.
 
-**Background review is different:** a same-model review fork always inherits the parent's reasoning effort. `auxiliary.background_review.reasoning_effort` is ignored on that path, including when the parent provider/model is explicitly selected. This preserves byte-identical reasoning settings, system prompt, full conversation snapshot, and tool definitions for prompt-cache parity; there is no independent-effort switch for same-model reviews. See [background review reasoning](/user-guide/features/memory#same-model-review-reasoning). When the review is routed to a different provider/model, `reasoning_effort` applies to that routed fork (unset = the routed provider's default). Hermes prints a one-time warning when the key is set but the review runs on the main model.
+**Background review is different:** a same-model review fork always inherits the parent's reasoning effort. `auxiliary.background_review.reasoning_effort` is ignored on that path, including when the parent provider/model is explicitly selected. This preserves byte-identical reasoning settings, system prompt, full conversation snapshot, and tool definitions for prompt-cache parity; there is no independent-effort switch for same-model reviews. See [background review reasoning](./features/memory.md#same-model-review-reasoning). When the review is routed to a different provider/model, `reasoning_effort` applies to that routed fork (unset = the routed provider's default). Hermes prints a one-time warning when the key is set but the review runs on the main model.
 
-**MoA also uses a different configuration:** reasoning depth for Mixture-of-Agents is configured **per slot** in the MoA preset (`moa.presets.<name>.reference_models[].reasoning_effort` / `aggregator.reasoning_effort`), not on the `moa_reference`/`moa_aggregator` auxiliary blocks — see [Mixture of Agents](/user-guide/features/mixture-of-agents).
+**MoA also uses a different configuration:** reasoning depth for Mixture-of-Agents is configured **per slot** in the MoA preset (`moa.presets.<name>.reference_models[].reasoning_effort` / `aggregator.reasoning_effort`), not on the `moa_reference`/`moa_aggregator` auxiliary blocks — see [Mixture of Agents](./features/mixture-of-agents.md).
 
 ```yaml
 auxiliary:
@@ -1435,7 +1435,7 @@ auxiliary:
 
 When `base_url` is set, Hermes ignores the provider and calls that endpoint directly (using `api_key` or `OPENAI_API_KEY` for auth). When only `provider` is set, Hermes uses that provider's built-in auth and base URL.
 
-Available providers for auxiliary tasks: `auto`, `main`, plus any provider in the [provider registry](/reference/environment-variables) — `openrouter`, `nous`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `gemini`, `qwen-oauth`, `zai`, `kimi-coding`, `kimi-coding-cn`, `minimax`, `minimax-cn`, `minimax-oauth`, `deepseek`, `nvidia`, `xai`, `xai-oauth`, `ollama-cloud`, `alibaba`, `bedrock`, `huggingface`, `arcee`, `xiaomi`, `kilocode`, `opencode-zen`, `opencode-go`, `commandcode`, `commandcode-anthropic`, `ai-gateway`, `azure-foundry` — or any named custom provider from your `providers:` dict (e.g. `provider: "beans"`).
+Available providers for auxiliary tasks: `auto`, `main`, plus any provider in the [provider registry](../reference/environment-variables.md) — `openrouter`, `nous`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `gemini`, `qwen-oauth`, `zai`, `kimi-coding`, `kimi-coding-cn`, `minimax`, `minimax-cn`, `minimax-oauth`, `deepseek`, `nvidia`, `xai`, `xai-oauth`, `ollama-cloud`, `alibaba`, `bedrock`, `huggingface`, `arcee`, `xiaomi`, `kilocode`, `opencode-zen`, `opencode-go`, `commandcode`, `commandcode-anthropic`, `ai-gateway`, `azure-foundry` — or any named custom provider from your `providers:` dict (e.g. `provider: "beans"`).
 
 Local OpenAI-compatible servers work under their own names too: `provider: ollama` (also `vllm`, `llamacpp`, `llama.cpp`) with a `base_url` such as `http://127.0.0.1:11434` and an empty `api_key` routes through the custom endpoint with a placeholder key, and a bare `host:port` base_url gets the `/v1` suffix automatically.
 
@@ -1448,7 +1448,7 @@ Local OpenAI-compatible servers work under their own names too: `provider: ollam
 :::
 
 :::warning `"main"` is for auxiliary tasks only
-The `"main"` provider option means "use whatever provider my main agent uses" — it's only valid inside `auxiliary:`, `compression:`, and primary fallback entries (`fallback_providers:` or legacy `fallback_model:`). It is **not** a valid value for your top-level `model.provider` setting. If you use a custom OpenAI-compatible endpoint, set `provider: custom` in your `model:` section. See [AI Providers](/integrations/providers) for all main model provider options.
+The `"main"` provider option means "use whatever provider my main agent uses" — it's only valid inside `auxiliary:`, `compression:`, and primary fallback entries (`fallback_providers:` or legacy `fallback_model:`). It is **not** a valid value for your top-level `model.provider` setting. If you use a custom OpenAI-compatible endpoint, set `provider: custom` in your `model:` section. See [AI Providers](../integrations/providers.md) for all main model provider options.
 :::
 
 ### Full auxiliary config reference
@@ -1553,7 +1553,7 @@ Each auxiliary task has a configurable `timeout` (in seconds). Defaults: vision
 :::
 
 :::info
-Context compression has its own `compression:` block for thresholds and an `auxiliary.compression:` block for model/provider settings — see [Context Compression](#context-compression) above. The primary fallback chain uses a top-level `fallback_providers:` list — see [Fallback Providers](/integrations/providers#fallback-providers). All three follow the same provider/model/base_url pattern.
+Context compression has its own `compression:` block for thresholds and an `auxiliary.compression:` block for model/provider settings — see [Context Compression](#context-compression) above. The primary fallback chain uses a top-level `fallback_providers:` list — see [Fallback Providers](../integrations/providers.md#fallback-providers). All three follow the same provider/model/base_url pattern.
 :::
 
 ### Per-task fallback chain for auxiliary tasks
@@ -1586,7 +1586,7 @@ Each entry supports the same three knobs as any auxiliary task config:
 
 ### Native vision embed budgets (top-level `vision:`)
 
-Separate from `auxiliary.vision` (which picks the describer model): when the *main* model is vision-capable, `vision_analyze` and browser screenshots embed real pixels into tool results that are re-sent every later turn. `vision.embed_target_bytes` (default `262144`, clamped 64 KiB..4 MiB) sizes one embed; `vision.max_calls_per_image` caps how often the same image may be embedded per session (unset = 3 inside delegated subagents, unlimited for the main agent; `0` = unlimited). See [Vision → Native embeds ride the session](/user-guide/features/vision#native-embeds-ride-the-session-visionembed_target_bytes-and-visionmax_calls_per_image).
+Separate from `auxiliary.vision` (which picks the describer model): when the *main* model is vision-capable, `vision_analyze` and browser screenshots embed real pixels into tool results that are re-sent every later turn. `vision.embed_target_bytes` (default `262144`, clamped 64 KiB..4 MiB) sizes one embed; `vision.max_calls_per_image` caps how often the same image may be embedded per session (unset = 3 inside delegated subagents, unlimited for the main agent; `0` = unlimited). See [Vision → Native embeds ride the session](./features/vision.md#native-embeds-ride-the-session-visionembed_target_bytes-and-visionmax_calls_per_image).
 
 ### Limiting auxiliary concurrency
 
@@ -1609,7 +1609,7 @@ The semaphore wraps the entire call including retries and fallbacks, so a single
 
 ### OpenRouter routing & Pareto Code for auxiliary tasks
 
-When an auxiliary task resolves to OpenRouter (either explicitly or via `provider: "main"` while your main agent is on OpenRouter), the main agent's `provider_routing` and `openrouter.min_coding_score` settings **do not propagate** — by design, each auxiliary task is independent. To set OpenRouter provider preferences or use the [Pareto Code router](/integrations/providers#openrouter-pareto-code-router) for a specific aux task, set them per-task via `extra_body`:
+When an auxiliary task resolves to OpenRouter (either explicitly or via `provider: "main"` while your main agent is on OpenRouter), the main agent's `provider_routing` and `openrouter.min_coding_score` settings **do not propagate** — by design, each auxiliary task is independent. To set OpenRouter provider preferences or use the [Pareto Code router](../integrations/providers.md#openrouter-pareto-code-router) for a specific aux task, set them per-task via `extra_body`:
 
 ```yaml
 auxiliary:
@@ -1822,11 +1822,11 @@ The key matching is **spelling-tolerant** — any reasonable spelling will match
 - Exact matches take precedence over variants
 
 :::note
-Model ids contain dots (`claude-opus-4.5`, `qwen3.6:27b`), which `hermes config set` treats as nesting separators. Escape them with a backslash to write the literal key — `hermes config set 'agent.reasoning_overrides.ollama-local/qwen3\.6:27b-q4_k_m' low` — or edit the YAML directly. See [Dots inside key names](/reference/cli-commands#dots-inside-key-names).
+Model ids contain dots (`claude-opus-4.5`, `qwen3.6:27b`), which `hermes config set` treats as nesting separators. Escape them with a backslash to write the literal key — `hermes config set 'agent.reasoning_overrides.ollama-local/qwen3\.6:27b-q4_k_m' low` — or edit the YAML directly. See [Dots inside key names](../reference/cli-commands.md#dots-inside-key-names).
 :::
 
 :::note Local OpenAI-compatible endpoints
-A custom `base_url` (`http://localhost:11434/v1`, a vLLM, SGLang or router endpoint) receives the resolved effort — `agent.reasoning_effort` or the matching per-model override — as the standard top-level `reasoning_effort` request field, clamped to the values the OpenAI-compatible wire accepts (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`). The nested `reasoning` object is reserved for endpoints known to accept it (Nous Portal, OpenRouter reasoning-capable models, GitHub Models) because arbitrary servers reject unknown fields with HTTP 400. If your server reads its thinking budget from a different field (Ollama's `think`, vLLM's `chat_template_kwargs`, a router-specific key), set it under the custom provider's [`extra_body`](/integrations/providers#named-custom-providers), which is merged into every request routed there.
+A custom `base_url` (`http://localhost:11434/v1`, a vLLM, SGLang or router endpoint) receives the resolved effort — `agent.reasoning_effort` or the matching per-model override — as the standard top-level `reasoning_effort` request field, clamped to the values the OpenAI-compatible wire accepts (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`). The nested `reasoning` object is reserved for endpoints known to accept it (Nous Portal, OpenRouter reasoning-capable models, GitHub Models) because arbitrary servers reject unknown fields with HTTP 400. If your server reads its thinking budget from a different field (Ollama's `think`, vLLM's `chat_template_kwargs`, a router-specific key), set it under the custom provider's [`extra_body`](../integrations/providers.md#named-custom-providers), which is merged into every request routed there.
 :::
 
 **Resolution priority:**
@@ -2340,7 +2340,7 @@ stt:
   prompt: "Hermes, Teknium, Nous Research, kanban, Ollama"
 ```
 
-**Composition.** The config value is the base. Plugins that register the [`pre_transcription`](/user-guide/features/hooks#pre_transcription) hook mutate on top of it, last-writer-wins per field. Multiple plugins' hints compose deterministically: plugin discovery loads plugins in sorted order by plugin id, and each plugin's callbacks run in its own registration order, so the same set of plugins always produces the same final prompt. A hook returning an empty string for `prompt` clears the config prompt for that request. Hooks may also override `language` and `model`; `file_path` is read-only and any attempt to change it is logged and dropped. With no hook registered and no `stt.prompt` set, the outgoing request is identical to previous releases.
+**Composition.** The config value is the base. Plugins that register the [`pre_transcription`](./features/hooks.md#pre_transcription) hook mutate on top of it, last-writer-wins per field. Multiple plugins' hints compose deterministically: plugin discovery loads plugins in sorted order by plugin id, and each plugin's callbacks run in its own registration order, so the same set of plugins always produces the same final prompt. A hook returning an empty string for `prompt` clears the config prompt for that request. Hooks may also override `language` and `model`; `file_path` is read-only and any attempt to change it is logged and dropped. With no hook registered and no `stt.prompt` set, the outgoing request is identical to previous releases.
 
 **Provider support.**
 
@@ -2376,7 +2376,7 @@ voice:
   silence_duration: 3.0         # Seconds of silence before auto-stop
 ```
 
-Use `/voice on` in the CLI to enable microphone mode, `record_key` to start/stop recording, and `/voice tts` to toggle spoken replies. See [Voice Mode](/user-guide/features/voice-mode) for end-to-end setup and platform-specific behavior.
+Use `/voice on` in the CLI to enable microphone mode, `record_key` to start/stop recording, and `/voice tts` to toggle spoken replies. See [Voice Mode](./features/voice-mode.md) for end-to-end setup and platform-specific behavior.
 
 ## Streaming
 
@@ -2458,7 +2458,7 @@ group_sessions_per_user: true  # true = per-user isolation in groups/channels, f
 - Direct messages are unaffected. Hermes still keys DMs by chat/DM ID as usual.
 - Threads stay isolated from their parent channel either way; with `true`, each participant also gets their own session inside the thread.
 
-For the behavior details and examples, see [Sessions](/user-guide/sessions) and the [Discord guide](/user-guide/messaging/discord).
+For the behavior details and examples, see [Sessions](./sessions.md) and the [Discord guide](./messaging/discord.md).
 
 ## Unauthorized DM Behavior
 
@@ -2586,9 +2586,9 @@ web:
 | **Perplexity** | `PERPLEXITY_API_KEY` | ✔ | ✔ (query-relevant snippets) |
 | **Exa** | `EXA_API_KEY` (optional — keyless free tier) | ✔ | ✔ |
 
-**Backend selection:** The runtime always uses the stored `web.backend` selection (set via `hermes tools`; `nous` routes through the managed Tool Gateway). Only if no web backend has ever been selected is one auto-detected from available API keys: if only `SEARXNG_URL` is set, SearXNG is used; if only `EXA_API_KEY` is set, Exa; if only `TAVILY_API_KEY` is set, Tavily; if only `PERPLEXITY_API_KEY` is set, Perplexity; if only `PARALLEL_API_KEY` is set, Parallel; if only `KEENABLE_API_KEY` is set, Keenable. With **no selection and no credentials at all**, requests rotate round-robin across the keyless free-tier ring (Exa / Parallel / Firecrawl / Keenable) with automatic next-in-line failover on rate limits — see the [Web Search guide](/user-guide/features/web-search) for details. Once a selection exists, adding a key to `.env` does not change the route. Selecting Tavily, Firecrawl, or Keenable in `hermes tools` also works without a key.
+**Backend selection:** The runtime always uses the stored `web.backend` selection (set via `hermes tools`; `nous` routes through the managed Tool Gateway). Only if no web backend has ever been selected is one auto-detected from available API keys: if only `SEARXNG_URL` is set, SearXNG is used; if only `EXA_API_KEY` is set, Exa; if only `TAVILY_API_KEY` is set, Tavily; if only `PERPLEXITY_API_KEY` is set, Perplexity; if only `PARALLEL_API_KEY` is set, Parallel; if only `KEENABLE_API_KEY` is set, Keenable. With **no selection and no credentials at all**, requests rotate round-robin across the keyless free-tier ring (Exa / Parallel / Firecrawl / Keenable) with automatic next-in-line failover on rate limits — see the [Web Search guide](./features/web-search.md) for details. Once a selection exists, adding a key to `.env` does not change the route. Selecting Tavily, Firecrawl, or Keenable in `hermes tools` also works without a key.
 
-**SearXNG** is a free, self-hosted, privacy-respecting metasearch engine that queries 70+ search engines. No API key needed — just set `SEARXNG_URL` to your instance (e.g., `http://localhost:8080`). SearXNG is search-only; `web_extract` requires a separate extract provider (set `web.extract_backend`). See the [Web Search setup guide](/user-guide/features/web-search) for Docker setup instructions.
+**SearXNG** is a free, self-hosted, privacy-respecting metasearch engine that queries 70+ search engines. No API key needed — just set `SEARXNG_URL` to your instance (e.g., `http://localhost:8080`). SearXNG is search-only; `web_extract` requires a separate extract provider (set `web.extract_backend`). See the [Web Search setup guide](./features/web-search.md) for Docker setup instructions.
 
 **Self-hosted Firecrawl:** Set `FIRECRAWL_API_URL` to point at your own instance. When a custom URL is set, the API key becomes optional (set `USE_DB_AUTHENTICATION=*** on the server to disable auth).
 
@@ -2628,7 +2628,7 @@ browser:
 
 See the [browser feature page](./features/browser.md#browser_dialog) for the full dialog workflow.
 
-The browser toolset supports multiple providers. See the [Browser feature page](/user-guide/features/browser) for details on Browserbase, Browser Use, and local Chromium-family CDP setup.
+The browser toolset supports multiple providers. See the [Browser feature page](./features/browser.md) for details on Browserbase, Browser Use, and local Chromium-family CDP setup.
 
 ## Timezone
 
@@ -2750,7 +2750,7 @@ approvals:
     - "*curl*|*sh*"
 ```
 
-Patterns are case-insensitive fnmatch globs and must be quoted in YAML (a bare leading `*` is a parse error). See [Security — User-Defined Deny Rules](/user-guide/security#user-defined-deny-rules-approvalsdeny) for details.
+Patterns are case-insensitive fnmatch globs and must be quoted in YAML (a bare leading `*` is a parse error). See [Security — User-Defined Deny Rules](./security.md#user-defined-deny-rules-approvalsdeny) for details.
 
 ### Custom smart-approval policy
 
@@ -2766,7 +2766,7 @@ approvals:
 
 ## Checkpoints
 
-Automatic filesystem snapshots before destructive file operations. See the [Checkpoints & Rollback](/user-guide/checkpoints-and-rollback) for details.
+Automatic filesystem snapshots before destructive file operations. See the [Checkpoints & Rollback](./checkpoints-and-rollback.md) for details.
 
 ```yaml
 checkpoints:
@@ -2857,8 +2857,8 @@ Hermes uses two different context scopes:
 - All loaded context files are capped at `context_file_max_chars` characters (default 20,000) with smart truncation.
 
 See also:
-- [Personality & SOUL.md](/user-guide/features/personality)
-- [Context Files](/user-guide/features/context-files)
+- [Personality & SOUL.md](./features/personality.md)
+- [Context Files](./features/context-files.md)
 
 ## Working Directory
 
@@ -2903,7 +2903,7 @@ onboarding:
 
 ## Dashboard
 
-Configuration for the [web dashboard](/user-guide/features/web-dashboard) — visual theme, public URL, and authentication providers. The auth providers (OAuth, basic password, drain) are documented in detail on the web-dashboard page; this is the `config.yaml` shape.
+Configuration for the [web dashboard](./features/web-dashboard.md) — visual theme, public URL, and authentication providers. The auth providers (OAuth, basic password, drain) are documented in detail on the web-dashboard page; this is the `config.yaml` shape.
 
 ```yaml
 dashboard:
@@ -2935,7 +2935,7 @@ dashboard:
 - `show_token_analytics` — off by default. The Analytics page and token/cost figures are a **local lower-bound estimate** (they exclude auxiliary calls, retries, fallbacks, and cache writes), so they can read far below the provider bill. Set `true` only if you understand they're not billing.
 - `public_url` — when set, this is the complete authority (scheme + host + optional path prefix) the OAuth `redirect_uri` is built from. Set it for deploys behind reverse proxies that don't reliably forward `X-Forwarded-*` headers. Leave empty to use proxy-header reconstruction.
 - `trusted_proxies` — IP addresses or bounded CIDR networks allowed to supply `X-Forwarded-Proto` and `X-Forwarded-For`. Loopback remains trusted automatically. Configure this when the TLS reverse proxy connects from another container or host. Prefer the proxy's exact IP; use a small dedicated network only when its address is dynamic. Wildcards and `/0` networks are rejected.
-- `oauth` / `basic_auth` / `drain_auth` — auth provider config read by the bundled dashboard-auth plugins. The drain secret itself is **not** set here; it's provisioned via the `HERMES_DASHBOARD_DRAIN_SECRET` env var. See [Web Dashboard](/user-guide/features/web-dashboard) for full auth setup.
+- `oauth` / `basic_auth` / `drain_auth` — auth provider config read by the bundled dashboard-auth plugins. The drain secret itself is **not** set here; it's provisioned via the `HERMES_DASHBOARD_DRAIN_SECRET` env var. See [Web Dashboard](./features/web-dashboard.md) for full auth setup.
 - `ws_ping_interval` / `ws_ping_timeout` — WebSocket keepalive tuning for non-loopback binds (loopback connections never ping). Raise these on high-latency links (Tailscale, distant SSH tunnels) where the 20 s defaults can manufacture spurious 1006 disconnects.
 - `ssh_isolated_idle_grace_s` (default `900`) — a Desktop-owned `hermes serve --isolated` backend reached over SSH is detached from the SSH session on purpose, so a laptop that sleeps mid-connection cannot tear it down; each dark-wake reconnect used to leave another backend holding `state.db`. The backend now retires itself once no client WebSocket has been connected for this long and no agent turn is running (a turn keeps it alive; an unreadable turn state keeps it alive too). Set high if you rely on a detached backend finishing long work after the laptop sleeps. Such backends also send a slow WebSocket ping (60 s, 10 min timeout) so a half-open tunnel is noticed.
 - `ws_orphan_reap_grace_s` — how long a WS-detached session waits before the orphan reaper collects it. Raise alongside the keepalive values if clients reconnect slowly. Periodic session maintenance also completes cleanup for closed sockets and re-arms a missing orphan timer, so a detached chat cannot keep its ownership lease solely because its initial cleanup or timer was lost. Reconnecting cancels that timer; active delegated work and healthy running turns remain protected by the normal orphan-reaper checks. (`HERMES_TUI_WS_ORPHAN_REAP_GRACE_S` remains as an internal override.)
diff --git a/website/docs/user-guide/features/cron.md b/website/docs/user-guide/features/cron.md
index f9180d2d65..39634741d5 100644
--- a/website/docs/user-guide/features/cron.md
+++ b/website/docs/user-guide/features/cron.md
@@ -875,7 +875,7 @@ Semantics:
 
 #### Giving a script a credential
 
-A script that must authenticate to an external service (an API token, a service-account key) gets it the same way terminal and `execute_code` children do — declare the variable name in the owning profile's `config.yaml` and define the value in that profile's `.env` (or an external [secret source](/user-guide/secrets/)):
+A script that must authenticate to an external service (an API token, a service-account key) gets it the same way terminal and `execute_code` children do — declare the variable name in the owning profile's `config.yaml` and define the value in that profile's `.env` (or an external [secret source](../secrets/index.md)):
 
 ```yaml
 terminal:
diff --git a/website/docs/user-guide/secrets/index.md b/website/docs/user-guide/secrets/index.md
index f2fcb474c7..102b5450ee 100644
--- a/website/docs/user-guide/secrets/index.md
+++ b/website/docs/user-guide/secrets/index.md
@@ -45,7 +45,7 @@ Both apply to every source — bundled and plugin — because they live in the o
 
 ## Secrets in child processes
 
-Terminal commands, `execute_code` sandboxes and [`no_agent` cron scripts](/user-guide/features/cron#giving-a-script-a-credential) run with a sanitized environment: Hermes-managed credentials are stripped, and only variables you declare in `terminal.env_passthrough` (or a loaded skill's `required_environment_variables`) are forwarded. A declared variable is forwarded with the **owning profile's** value — from that profile's `.env` or its secret sources — even when the profile is served by a multi-profile gateway or the Desktop/dashboard backend and its secrets never entered the process environment. A profile's declared value never reaches another profile's children, and the launch profile's `.env` credentials are dropped from children that run for a served profile. Provider credentials cannot be declared; see [Security → Credential scoping](/user-guide/security).
+Terminal commands, `execute_code` sandboxes and [`no_agent` cron scripts](../features/cron.md#giving-a-script-a-credential) run with a sanitized environment: Hermes-managed credentials are stripped, and only variables you declare in `terminal.env_passthrough` (or a loaded skill's `required_environment_variables`) are forwarded. A declared variable is forwarded with the **owning profile's** value — from that profile's `.env` or its secret sources — even when the profile is served by a multi-profile gateway or the Desktop/dashboard backend and its secrets never entered the process environment. A profile's declared value never reaches another profile's children, and the launch profile's `.env` credentials are dropped from children that run for a served profile. Provider credentials cannot be declared; see [Security → Credential scoping](../security.md).
 
 ## Adding your own backend
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/run-hermes-with-nous-portal.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/run-hermes-with-nous-portal.md
index c9b9c1b3b0..2c312207f3 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/run-hermes-with-nous-portal.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/run-hermes-with-nous-portal.md
@@ -6,12 +6,12 @@ description: "完整操作指南：订阅、配置、切换模型、启用 gatew
 
 # 通过 Nous Portal 运行 Hermes Agent
 
-本指南带你从头到尾完成在 [Nous Portal](https://portal.nousresearch.com) 订阅下运行 Hermes Agent 的全过程——从注册账号到验证每个工具的路由是否正确。如果你只想了解 Portal 的概述及订阅内容，请参阅 [Nous Portal 集成页面](/integrations/nous-portal)。本页是操作步骤脚本。
+本指南带你从头到尾完成在 [Nous Portal](https://portal.nousresearch.com) 订阅下运行 Hermes Agent 的全过程——从注册账号到验证每个工具的路由是否正确。如果你只想了解 Portal 的概述及订阅内容，请参阅 [Nous Portal 集成页面](../integrations/nous-portal.md)。本页是操作步骤脚本。
 
 ## 前提条件
 
-- 已安装 Hermes Agent（[快速入门](/getting-started/quickstart)）
-- 在你正在配置的机器上有可用的浏览器（或 SSH 端口转发——参见 [OAuth over SSH](/guides/oauth-over-ssh)）
+- 已安装 Hermes Agent（[快速入门](../getting-started/quickstart.md)）
+- 在你正在配置的机器上有可用的浏览器（或 SSH 端口转发——参见 [OAuth over SSH](./oauth-over-ssh.md)）
 - 约 5 分钟时间
 
 你**不需要**：OpenAI 密钥、Anthropic 密钥、Firecrawl 账号、FAL 账号、Browser Use 账号，或任何其他按供应商分配的凭证。这正是 Portal 的意义所在。
@@ -52,7 +52,7 @@ hermes auth add nous --type oauth
 # 然后重新运行 `hermes setup --portal` 以连接 provider + gateway
 ```
 
-完整操作说明（包括 ProxyJump 链、mosh/tmux 和 ControlMaster 注意事项）请参阅 [OAuth over SSH / 远程主机](/guides/oauth-over-ssh)。
+完整操作说明（包括 ProxyJump 链、mosh/tmux 和 ControlMaster 注意事项）请参阅 [OAuth over SSH / 远程主机](./oauth-over-ssh.md)。
 
 ## 3. 验证配置是否成功
 
@@ -120,7 +120,7 @@ hermes config set model.default anthropic/claude-sonnet-4.6
 
 ### 不要在 agent 任务中使用 Hermes-4
 
-Hermes-4-70B 和 Hermes-4-405B 在 Portal 上以大幅折扣提供，但它们是**对话/推理模型**，并非针对工具调用优化的模型。它们在多步骤 agent 循环中表现不佳。请通过[订阅代理](/user-guide/features/subscription-proxy)从非 agent 工具中将它们用于对话或研究工作。对于 Hermes Agent 本身，请坚持使用上述前沿 agentic 模型。
+Hermes-4-70B 和 Hermes-4-405B 在 Portal 上以大幅折扣提供，但它们是**对话/推理模型**，并非针对工具调用优化的模型。它们在多步骤 agent 循环中表现不佳。请通过[订阅代理](../user-guide/features/subscription-proxy.md)从非 agent 工具中将它们用于对话或研究工作。对于 Hermes Agent 本身，请坚持使用上述前沿 agentic 模型。
 
 Portal 的[信息页面](https://portal.nousresearch.com/info)也有此说明——这是 Nous 官方指导，并非仅代表 Hermes 一方的意见。
 
@@ -146,7 +146,7 @@ hermes portal tools
 
 ## 7. （可选）启用语音模式
 
-由于 Tool Gateway 包含 OpenAI TTS，无需单独的 OpenAI 密钥即可使用[语音模式](/user-guide/features/voice-mode)：
+由于 Tool Gateway 包含 OpenAI TTS，无需单独的 OpenAI 密钥即可使用[语音模式](../user-guide/features/voice-mode.md)：
 
 ```bash
 hermes setup voice
@@ -158,7 +158,7 @@ hermes setup voice
 
 ## 8. （可选）Cron 定时任务与常驻工作流
 
-Portal 订阅对 [cron 定时任务](/user-guide/features/cron)和[批处理](/user-guide/features/batch-processing)的支持方式与交互式对话相同——OAuth refresh token 会自动复用。无需额外配置，直接安排 cron 任务，费用将计入你的订阅。
+Portal 订阅对 [cron 定时任务](../user-guide/features/cron.md)和[批处理](../user-guide/features/batch-processing.md)的支持方式与交互式对话相同——OAuth refresh token 会自动复用。无需额外配置，直接安排 cron 任务，费用将计入你的订阅。
 
 ```bash
 hermes cron add "Daily AI news summary" "every day at 9am" \
@@ -169,7 +169,7 @@ hermes cron add "Daily AI news summary" "every day at 9am" \
 
 ## Profiles 与多用户配置
 
-如果你使用 [Hermes profiles](/user-guide/profiles)（例如每个项目单独一套配置），每个 profile 都是独立的凭证孤岛：从未登录过 Portal 的 profile 会直接失败，而不会采用其他 profile 的会话。请在每个 profile 上用 `hermes -p <name> portal` 登录一次——如果机器上已有共享的 Portal 会话，它会提示导入且无需再走浏览器流程；此后共享 token 存储会让该 profile 的令牌保持最新。参见 [Profile 配置](/integrations/nous-portal#profile-setup)。
+如果你使用 [Hermes profiles](../user-guide/profiles.md)（例如每个项目单独一套配置），每个 profile 都是独立的凭证孤岛：从未登录过 Portal 的 profile 会直接失败，而不会采用其他 profile 的会话。请在每个 profile 上用 `hermes -p <name> portal` 登录一次——如果机器上已有共享的 Portal 会话，它会提示导入且无需再走浏览器流程；此后共享 token 存储会让该 profile 的令牌保持最新。参见 [Profile 配置](../integrations/nous-portal.md#profile-setup)。
 
 对于多人共用一台机器的团队场景，每个人有自己的 Portal 账号 → 每个 home 目录保存各自的 `~/.hermes/auth.json` → 用户之间不共享 token。这是正确的边界划分。
 
@@ -183,7 +183,7 @@ OAuth 流程未完成。重新运行：
 hermes portal
 ```
 
-如果浏览器未打开或回调失败，你可能在远程/无头主机上——参见 [OAuth over SSH](/guides/oauth-over-ssh) 了解端口转发的解决方案。
+如果浏览器未打开或回调失败，你可能在远程/无头主机上——参见 [OAuth over SSH](./oauth-over-ssh.md) 了解端口转发的解决方案。
 
 ### "Model: currently openrouter"（或其他 provider）而非"using Nous as inference provider"
 
@@ -265,9 +265,9 @@ hermes auth logout nous       # 清除本地 refresh token
 
 ## 另请参阅
 
-- **[Nous Portal 集成页面](/integrations/nous-portal)** — 订阅内容概述
-- **[Tool Gateway](/user-guide/features/tool-gateway)** — 每个 gateway 路由工具的完整说明
-- **[订阅代理](/user-guide/features/subscription-proxy)** — 在非 Hermes 工具中使用你的 Portal 订阅
-- **[语音模式](/user-guide/features/voice-mode)** — 在 Portal 订阅上配置语音对话
-- **[OAuth over SSH](/guides/oauth-over-ssh)** — 远程/无头主机登录方案
-- **[Profiles](/user-guide/profiles)** — 在多个 Hermes 配置之间共享一个 Portal 登录
+- **[Nous Portal 集成页面](../integrations/nous-portal.md)** — 订阅内容概述
+- **[Tool Gateway](../user-guide/features/tool-gateway.md)** — 每个 gateway 路由工具的完整说明
+- **[订阅代理](../user-guide/features/subscription-proxy.md)** — 在非 Hermes 工具中使用你的 Portal 订阅
+- **[语音模式](../user-guide/features/voice-mode.md)** — 在 Portal 订阅上配置语音对话
+- **[OAuth over SSH](./oauth-over-ssh.md)** — 远程/无头主机登录方案
+- **[Profiles](../user-guide/profiles.md)** — 在多个 Hermes 配置之间共享一个 Portal 登录
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/nous-portal.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/nous-portal.md
index ac0776acda..c7f74eac67 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/nous-portal.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/nous-portal.md
@@ -46,13 +46,13 @@ Portal 代理了来自整个生态系统的精选 agentic 模型目录——统
 
 ### Nous Tool Gateway
 
-同一订阅还解锁了 [Tool Gateway](/user-guide/features/tool-gateway)，将 Hermes Agent 的工具调用路由至 Nous 托管的基础设施。五个后端，一次登录：
+同一订阅还解锁了 [Tool Gateway](../user-guide/features/tool-gateway.md)，将 Hermes Agent 的工具调用路由至 Nous 托管的基础设施。五个后端，一次登录：
 
 | 工具 | 合作方 | 功能说明 |
 |------|---------|--------------|
 | **网页搜索与抓取** | Firecrawl | Agent 级搜索与整页内容提取。无需 Firecrawl API 密钥，无需管理速率限制。 |
 | **图像生成** | FAL | 单一端点下的九个模型：FLUX 2 Klein 9B、FLUX 2 Pro、Z-Image Turbo、Nano Banana Pro（Gemini 3 Pro Image）、GPT Image 1.5、GPT Image 2、Ideogram V3、Recraft V4 Pro、Qwen Image。 |
-| **文字转语音** | OpenAI TTS | 无需独立 OpenAI 密钥的高质量 TTS。在各消息平台上启用[语音模式](/user-guide/features/voice-mode)。 |
+| **文字转语音** | OpenAI TTS | 无需独立 OpenAI 密钥的高质量 TTS。在各消息平台上启用[语音模式](../user-guide/features/voice-mode.md)。 |
 | **云端浏览器自动化** | Browser Use | 用于 `browser_navigate`、`browser_click`、`browser_type`、`browser_vision` 的无头 Chromium 会话。无需 Browserbase 账号。 |
 | **云端终端沙箱** | Modal | 用于代码执行的无服务器终端沙箱（可选附加项）。 |
 
@@ -66,13 +66,13 @@ Portal 代理了来自整个生态系统的精选 agentic 模型目录——统
 
 ### 跨平台一致性
 
-[原生 Windows](/user-guide/windows-native) 上，逐个配置 API 密钥是其最大痛点——在 Windows 上分别安装 Firecrawl 账号、FAL 账号、Browser Use 账号、OpenAI 密钥，是整个 agent 配置过程中摩擦最高的部分。Portal 订阅消除了这一问题：一次 OAuth 覆盖模型和所有 gateway 工具，Windows 用户无需手动配置四个后端，即可获得与 macOS/Linux 相同的体验。
+[原生 Windows](../user-guide/windows-native.md) 上，逐个配置 API 密钥是其最大痛点——在 Windows 上分别安装 Firecrawl 账号、FAL 账号、Browser Use 账号、OpenAI 密钥，是整个 agent 配置过程中摩擦最高的部分。Portal 订阅消除了这一问题：一次 OAuth 覆盖模型和所有 gateway 工具，Windows 用户无需手动配置四个后端，即可获得与 macOS/Linux 相同的体验。
 
 ## 关于 Hermes 4 的说明
 
 Nous Research 自家的 **Hermes 4** 系列（Hermes-4-70B、Hermes-4-405B）通过 Portal 提供，享有大幅折扣。这些是**前沿混合推理对话模型**——在数学、科学、指令遵循、schema 遵从、角色扮演和长文写作方面表现出色。
 
-但**不建议在 Hermes Agent 内部使用它们**。Hermes 4 针对对话和推理进行了调优，而非 agent 所依赖的高频工具调用循环。请将它们用于研究工作流，或通过[订阅代理](/user-guide/features/subscription-proxy)从其他工具调用——但在 agent 场景下，请从目录中选择前沿 agentic 模型：
+但**不建议在 Hermes Agent 内部使用它们**。Hermes 4 针对对话和推理进行了调优，而非 agent 所依赖的高频工具调用循环。请将它们用于研究工作流，或通过[订阅代理](../user-guide/features/subscription-proxy.md)从其他工具调用——但在 agent 场景下，请从目录中选择前沿 agentic 模型：
 
 ```bash
 /model anthropic/claude-sonnet-4.6     # 最佳通用 agentic 模型
@@ -116,11 +116,11 @@ hermes model
 
 ### 无头环境 / SSH / 远程配置
 
-OAuth 需要浏览器，但回调的 loopback 运行在 Hermes 所在的机器上。对于远程主机，请参阅 [OAuth over SSH / 远程主机](/guides/oauth-over-ssh)——与其他基于 OAuth 的提供商相同的方式同样适用于 Portal（`ssh -L` 端口转发）。
+OAuth 需要浏览器，但回调的 loopback 运行在 Hermes 所在的机器上。对于远程主机，请参阅 [OAuth over SSH / 远程主机](../guides/oauth-over-ssh.md)——与其他基于 OAuth 的提供商相同的方式同样适用于 Portal（`ssh -L` 端口转发）。
 
 ### Profile 配置 {#profile-setup}
 
-如果你使用 [Hermes profiles（配置文件）](/user-guide/profiles)，Portal 的 refresh token 会通过共享令牌存储在各 profile 间共享——但该存储**只刷新已有的登录，不会创建新登录**。各 profile 是相互独立的孤岛（[#111724](https://github.com/NousResearch/hermes-agent/issues/111724)），因此从未登录过 Portal 的 profile 没有自己的 Nous 凭证：启动时它会直接失败，提示 `Profile '<name>' is not connected to any AI provider yet`，而不会静默采用其他 profile 的会话。
+如果你使用 [Hermes profiles（配置文件）](../user-guide/profiles.md)，Portal 的 refresh token 会通过共享令牌存储在各 profile 间共享——但该存储**只刷新已有的登录，不会创建新登录**。各 profile 是相互独立的孤岛（[#111724](https://github.com/NousResearch/hermes-agent/issues/111724)），因此从未登录过 Portal 的 profile 没有自己的 Nous 凭证：启动时它会直接失败，提示 `Profile '<name>' is not connected to any AI provider yet`，而不会静默采用其他 profile 的会话。
 
 **每个 profile 都需登录一次**，命令为 `hermes -p <name> portal`（即 `hermes -p <name> auth add nous --type oauth` 的别名）。如果机器上已有共享的 Portal 会话，该命令会提示导入——确认一次即可，无需再走浏览器流程。首次导入后该 profile 保留自己的状态，只要任一 profile 刷新或重新登录，共享存储便会让它的令牌保持最新。从已登录的 profile 执行 `hermes profile create <name> --clone-all` 也会一并带上 Portal 登录（克隆时只会剥离 Anthropic/Codex 这类一次性授权）。
 
@@ -190,7 +190,7 @@ hermes tools
 # → TTS            → "Nous Subscription"
 ```
 
-Tool Gateway 是按工具单独选择启用的，而非全部或全不。完整的每工具配置矩阵请参阅 [Tool Gateway 文档](/user-guide/features/tool-gateway)。
+Tool Gateway 是按工具单独选择启用的，而非全部或全不。完整的每工具配置矩阵请参阅 [Tool Gateway 文档](../user-guide/features/tool-gateway.md)。
 
 ### 订阅管理
 
@@ -266,9 +266,9 @@ Portal 会为每个模型选择合适的后端——部分模型通过 OpenRoute
 
 ## 另请参阅
 
-- **[Tool Gateway](/user-guide/features/tool-gateway)** —— 每个 gateway 工具的完整详情、每工具配置及定价
-- **[订阅代理](/user-guide/features/subscription-proxy)** —— 在非 Hermes 工具（其他 agent、脚本、第三方客户端）中使用你的 Portal 订阅
-- **[语音模式](/user-guide/features/voice-mode)** —— 使用 Portal 的 OpenAI TTS 进行语音对话
-- **[AI 提供商](/integrations/providers)** —— 完整提供商目录，供对比参考
-- **[OAuth over SSH](/guides/oauth-over-ssh)** —— 从远程主机或纯浏览器环境登录
-- **[Profiles](/user-guide/profiles)** —— 多个 Hermes 配置共享一个 Portal 登录
+- **[Tool Gateway](../user-guide/features/tool-gateway.md)** —— 每个 gateway 工具的完整详情、每工具配置及定价
+- **[订阅代理](../user-guide/features/subscription-proxy.md)** —— 在非 Hermes 工具（其他 agent、脚本、第三方客户端）中使用你的 Portal 订阅
+- **[语音模式](../user-guide/features/voice-mode.md)** —— 使用 Portal 的 OpenAI TTS 进行语音对话
+- **[AI 提供商](./providers.md)** —— 完整提供商目录，供对比参考
+- **[OAuth over SSH](../guides/oauth-over-ssh.md)** —— 从远程主机或纯浏览器环境登录
+- **[Profiles](../user-guide/profiles.md)** —— 多个 Hermes 配置共享一个 Portal 登录

From 244ee11d2f1e693a6a6c3d785aa5a5554a91ffa0 Mon Sep 17 00:00:00 2001
From: charles m <charleszhupc@126.com>
Date: Thu, 17 Sep 2026 12:09:50 +0800
Subject: [PATCH 134/190] feat(catalog): add by2kb video-to-knowledge plugin

---
 plugin-catalog/by2kb.yaml | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
 create mode 100644 plugin-catalog/by2kb.yaml

diff --git a/plugin-catalog/by2kb.yaml b/plugin-catalog/by2kb.yaml
new file mode 100644
index 0000000000..0ec267cb3e
--- /dev/null
+++ b/plugin-catalog/by2kb.yaml
@@ -0,0 +1,17 @@
+name: by2kb
+repo: https://github.com/Charlesmpc/by2kb
+sha: b246da30e3ebe7a869b18b857ef9a8125761f13f
+subdir: by2kb/integrations/hermes
+description: Turn Bilibili and YouTube videos into transcripts, short abstracts, and Markdown study notes using the Hermes host model.
+maintainer: Charlesmpc
+tier: community
+category: tools
+version: "0.6.0"
+docs_url: https://github.com/Charlesmpc/by2kb/blob/v0.6.0/docs/agent-integration.md
+platforms: []
+capabilities:
+  provides_tools: []
+  provides_hooks:
+    - pre_gateway_dispatch
+  provides_middleware: []
+  requires_env: []

From 1acb8559e6cb7aee093d2dc3221acb7dd07d2ecb Mon Sep 17 00:00:00 2001
From: teknium <teknium@nousresearch.com>
Date: Fri, 18 Sep 2026 14:05:36 -0700
Subject: [PATCH 135/190] chore: map contributor email for @Charlesmpc

So check-attribution passes on the catalog PR.
---
 contributors/emails/charleszhupc@126.com | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 contributors/emails/charleszhupc@126.com

diff --git a/contributors/emails/charleszhupc@126.com b/contributors/emails/charleszhupc@126.com
new file mode 100644
index 0000000000..d78e1a152b
--- /dev/null
+++ b/contributors/emails/charleszhupc@126.com
@@ -0,0 +1 @@
+Charlesmpc

From 8862ea2ab7f17da8d22431669ff8806e30c44b76 Mon Sep 17 00:00:00 2001
From: Luke The Dev <luke@claw3d.ai>
Date: Thu, 17 Sep 2026 10:48:17 +1000
Subject: [PATCH 136/190] catalog: add hud-teach

---
 plugin-catalog/hud-teach.yaml | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
 create mode 100644 plugin-catalog/hud-teach.yaml

diff --git a/plugin-catalog/hud-teach.yaml b/plugin-catalog/hud-teach.yaml
new file mode 100644
index 0000000000..5826a46f2e
--- /dev/null
+++ b/plugin-catalog/hud-teach.yaml
@@ -0,0 +1,18 @@
+name: hud-teach
+repo: https://github.com/iamlukethedev/hermes-hud-teach
+sha: 35f64257532ce3d716d93c9f3ff9b5faec81a93b
+description: Numbered how-to marks on the live Mac app underneath Hermes HUD.
+maintainer: iamlukethedev
+tier: community
+category: desktop
+requires_hermes: ">=0.20.0"
+docs_url: https://github.com/iamlukethedev/hermes-hud-teach
+version: "0.1.2"
+platforms: [macos]
+capabilities:
+  provides_tools:
+    - teach_screen
+  provides_hooks:
+    - on_session_end
+  provides_middleware: []
+  requires_env: []

From ca82a6342f53b52b0996243b4445a77aa5b651ce Mon Sep 17 00:00:00 2001
From: Luke The Dev <luke@claw3d.ai>
Date: Thu, 17 Sep 2026 12:28:31 +1000
Subject: [PATCH 137/190] catalog: clarify hud-teach works on chess and any Mac
 window

---
 plugin-catalog/hud-teach.yaml | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/plugin-catalog/hud-teach.yaml b/plugin-catalog/hud-teach.yaml
index 5826a46f2e..54ff8275f7 100644
--- a/plugin-catalog/hud-teach.yaml
+++ b/plugin-catalog/hud-teach.yaml
@@ -1,13 +1,15 @@
 name: hud-teach
 repo: https://github.com/iamlukethedev/hermes-hud-teach
-sha: 35f64257532ce3d716d93c9f3ff9b5faec81a93b
-description: Numbered how-to marks on the live Mac app underneath Hermes HUD.
+sha: faa71902eaaf0b82af58c37a58a117daf159021a
+description: 'Click-through numbered marks on any live Mac window — chess, games,
+  Photoshop, Settings — so Hermes can teach on the real UI without clicking for
+  the user.'
 maintainer: iamlukethedev
 tier: community
 category: desktop
 requires_hermes: ">=0.20.0"
 docs_url: https://github.com/iamlukethedev/hermes-hud-teach
-version: "0.1.2"
+version: "0.1.3"
 platforms: [macos]
 capabilities:
   provides_tools:

From 03c9fc892f5cf3f2e02aa4a4888a30ae292d256d Mon Sep 17 00:00:00 2001
From: teknium <teknium@nousresearch.com>
Date: Fri, 18 Sep 2026 14:04:54 -0700
Subject: [PATCH 138/190] chore: map contributor email for @iamlukethedev

So check-attribution passes on the catalog PR.
---
 contributors/emails/luke@claw3d.ai | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 contributors/emails/luke@claw3d.ai

diff --git a/contributors/emails/luke@claw3d.ai b/contributors/emails/luke@claw3d.ai
new file mode 100644
index 0000000000..f794ee6640
--- /dev/null
+++ b/contributors/emails/luke@claw3d.ai
@@ -0,0 +1 @@
+iamlukethedev

From 48cb45a39ffc6ebae4a82941fb3dad05d43527c0 Mon Sep 17 00:00:00 2001
From: LisandroNahuelH <226882487+LisandroNahuelH@users.noreply.github.com>
Date: Wed, 16 Sep 2026 20:15:16 -0300
Subject: [PATCH 139/190] chore(plugin-catalog): bump composer-modes to 2.0.1
 (staging fix)

---
 plugin-catalog/composer-modes.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugin-catalog/composer-modes.yaml b/plugin-catalog/composer-modes.yaml
index 7ab9b47953..2ae3bdd6ab 100644
--- a/plugin-catalog/composer-modes.yaml
+++ b/plugin-catalog/composer-modes.yaml
@@ -1,6 +1,6 @@
 name: composer-modes
 repo: https://github.com/LisandroNahuelH/hermes-composer-modes
-sha: 4f4e1c0b36165d84a9e2db7c71516f5a0c627d72
+sha: de372aa34ecfe6adb424f86c04ca2de924984cb0
 description: Cursor-style composer modes (ask / agent / plan / debug) for the Hermes desktop —
   the mode's operating note reaches the model inside the turn's model-facing bytes, never the
   bubble, transcript or session titles, and ask mode is enforced read-only on the tool side.

From 9478d543daa52ac7e51daf0207741833014bbcb5 Mon Sep 17 00:00:00 2001
From: tomekdot <73403480+tomekdot@users.noreply.github.com>
Date: Thu, 17 Sep 2026 01:10:14 +0200
Subject: [PATCH 140/190] chore(catalog): add my-github desktop and dashboard
 plugin

---
 plugin-catalog/my-github.yaml | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
 create mode 100644 plugin-catalog/my-github.yaml

diff --git a/plugin-catalog/my-github.yaml b/plugin-catalog/my-github.yaml
new file mode 100644
index 0000000000..b4ad062ba7
--- /dev/null
+++ b/plugin-catalog/my-github.yaml
@@ -0,0 +1,15 @@
+name: my-github
+repo: https://github.com/tomekdot/hermes-my-github-plugin
+sha: 21f78065692294de9d52bccb8c4939fe51588b68
+description: 'Desktop and dashboard plugin: statusbar chip, palette command, and dashboard tab listing your GitHub repos (public + private) via the gh CLI.'
+maintainer: tomekdot
+tier: community
+category: desktop
+requires_hermes: ">=0.21"
+docs_url: https://github.com/tomekdot/hermes-my-github-plugin
+platforms: []
+capabilities:
+  provides_tools: []
+  provides_hooks: []
+  provides_middleware: []
+  requires_env: []

From 6e8209df73011fb13f67ea3592018988ad961fbc Mon Sep 17 00:00:00 2001
From: Thiago Chu <thiago@zhu.dev>
Date: Wed, 16 Sep 2026 09:39:14 -0300
Subject: [PATCH 141/190] feat(plugin-catalog): add billing community plugin
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Owner-submitted (anotherchu/billing). Desktop-half-only package: root
plugin.yaml + desktop/plugin.js, no __init__.py — the manifest-only path
home-dashboard also takes, so the capability probe is skipped.

At the pinned commit: scripts/validate_plugin_catalog.py passes;
`hermes plugins validate` passes (manifest fields, requires_hermes,
built-in collisions); the CI's pinned-source clone/checkout/validate
sequence was reproduced locally. Self-updater grep over every .js file:
clean. requires_hermes ">=0.19" — the desktop plugin SDK surface and the
billing.state gateway RPC both exist as of v2026.7.20 (0.19.0).
---
 plugin-catalog/billing.yaml | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
 create mode 100644 plugin-catalog/billing.yaml

diff --git a/plugin-catalog/billing.yaml b/plugin-catalog/billing.yaml
new file mode 100644
index 0000000000..a5dbb9e075
--- /dev/null
+++ b/plugin-catalog/billing.yaml
@@ -0,0 +1,14 @@
+name: billing
+repo: https://github.com/anotherchu/billing
+sha: 2dfcc8ef346c1be65861bc8e8295c9727eb77c39
+description: Nous Portal usage widget for the Hermes desktop statusbar — remaining credits plus plan-usage percentage, with portal detail on hover.
+maintainer: anotherchu
+tier: community
+category: desktop
+requires_hermes: ">=0.19"
+docs_url: https://github.com/anotherchu/billing#readme
+capabilities:
+  provides_tools: []
+  provides_hooks: []
+  provides_middleware: []
+  requires_env: []

From 2d667fbf7803f6a28aa6b94e89ecba962cec77f2 Mon Sep 17 00:00:00 2001
From: teknium <teknium@nousresearch.com>
Date: Fri, 18 Sep 2026 14:04:13 -0700
Subject: [PATCH 142/190] chore: map contributor email for @anotherchu

So check-attribution passes on the catalog PR.
---
 contributors/emails/thiago@zhu.dev | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 contributors/emails/thiago@zhu.dev

diff --git a/contributors/emails/thiago@zhu.dev b/contributors/emails/thiago@zhu.dev
new file mode 100644
index 0000000000..64a959e80e
--- /dev/null
+++ b/contributors/emails/thiago@zhu.dev
@@ -0,0 +1 @@
+anotherchu

From 3090f9c62509ed5170572fb490778659924129cf Mon Sep 17 00:00:00 2001
From: Adolanium <94890352+Adolanium@users.noreply.github.com>
Date: Wed, 16 Sep 2026 08:01:30 +0300
Subject: [PATCH 143/190] feat(catalog): add ClinePass model provider

---
 plugin-catalog/clinepass.yaml | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
 create mode 100644 plugin-catalog/clinepass.yaml

diff --git a/plugin-catalog/clinepass.yaml b/plugin-catalog/clinepass.yaml
new file mode 100644
index 0000000000..26440c5f23
--- /dev/null
+++ b/plugin-catalog/clinepass.yaml
@@ -0,0 +1,15 @@
+name: clinepass
+repo: https://github.com/Adolanium/hermes-clinepass
+sha: 022bf7244cafb3e651f9b844f2783e28d0b5b40f
+subdir: clinepass
+description: ClinePass model provider with live model discovery and a curated fallback catalog.
+maintainer: Adolanium
+tier: community
+category: models
+docs_url: https://github.com/Adolanium/hermes-clinepass#readme
+capabilities:
+  provides_tools: []
+  provides_hooks: []
+  provides_middleware: []
+  requires_env:
+    - CLINE_API_KEY

From b25ce1574640caa2d25794d14ffea6008101c1c7 Mon Sep 17 00:00:00 2001
From: fred0m <fred0m@users.noreply.github.com>
Date: Wed, 16 Sep 2026 10:43:44 +0800
Subject: [PATCH 144/190] plugin-catalog: add memobase memory provider

Self-hosted Memobase (user profile + event timeline) as a MemoryProvider.
Hybrid BM25 + vector + entity RRF recall, temporal boost on time-window
queries, and a conditional cross-encoder rerank.

The reranker is opt-in with no default endpoint: it runs only when the
deployment sets both rerank_base_url and rerank_api_key, so a default
install talks only to the user's own Memobase server.

Pinned to 4e8e447 of fred0m/hermes-memobase-provider. Declares the two env
vars the install must prompt for.
---
 plugin-catalog/memobase.yaml | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)
 create mode 100644 plugin-catalog/memobase.yaml

diff --git a/plugin-catalog/memobase.yaml b/plugin-catalog/memobase.yaml
new file mode 100644
index 0000000000..c5ae376808
--- /dev/null
+++ b/plugin-catalog/memobase.yaml
@@ -0,0 +1,16 @@
+name: memobase
+repo: https://github.com/fred0m/hermes-memobase-provider
+sha: 4e8e447966acefaea372395e2db96ca0d0127f18
+description: Memobase memory provider — self-hosted user profile + event timeline
+  recall, with hybrid BM25/vector/entity retrieval and automatic per-turn prefetch.
+maintainer: fred0m
+tier: community
+category: memory
+docs_url: https://github.com/fred0m/hermes-memobase-provider#readme
+capabilities:
+  provides_tools: []
+  provides_hooks: []
+  provides_middleware: []
+  requires_env:
+  - MEMOBASE_API_KEY
+  - MEMOBASE_BASE_URL

From 85b00c145aea1bbe703dba079b47683bfd7468ac Mon Sep 17 00:00:00 2001
From: vollegrewar <52601680+vollegrewar@users.noreply.github.com>
Date: Wed, 16 Sep 2026 02:45:23 +0800
Subject: [PATCH 145/190] catalog: add anysearch (community web search/extract
 plugin)

---
 plugin-catalog/anysearch.yaml | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)
 create mode 100644 plugin-catalog/anysearch.yaml

diff --git a/plugin-catalog/anysearch.yaml b/plugin-catalog/anysearch.yaml
new file mode 100644
index 0000000000..40678e9c98
--- /dev/null
+++ b/plugin-catalog/anysearch.yaml
@@ -0,0 +1,16 @@
+name: anysearch
+repo: https://github.com/vollegrewar/hermes-anysearch
+sha: 43c1757a5d12d4d7adb4e74326c99182f4957b6f
+description: 'AnySearch web search and extraction plus two real-time fallback chains: when a primary backend fails (Exa quota, Firecrawl timeout), the same call is served by AnySearch (1,000 free requests/day).'
+maintainer: vollegrewar
+tier: community
+category: web
+requires_hermes: ">=0.21"
+docs_url: https://github.com/vollegrewar/hermes-anysearch#readme
+platforms: []
+capabilities:
+  provides_tools: []
+  provides_hooks: []
+  provides_middleware: []
+  requires_env:
+    - ANYSEARCH_API_KEY

From 1904c5e812abdc229ef67e9769581cb851455308 Mon Sep 17 00:00:00 2001
From: vollegrewar <52601680+vollegrewar@users.noreply.github.com>
Date: Wed, 16 Sep 2026 03:45:54 +0800
Subject: [PATCH 146/190] catalog: fix anysearch repo URLs and optional
 requires_env

---
 plugin-catalog/anysearch.yaml | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/plugin-catalog/anysearch.yaml b/plugin-catalog/anysearch.yaml
index 40678e9c98..24461ff887 100644
--- a/plugin-catalog/anysearch.yaml
+++ b/plugin-catalog/anysearch.yaml
@@ -1,16 +1,15 @@
 name: anysearch
-repo: https://github.com/vollegrewar/hermes-anysearch
+repo: https://github.com/vollegrewar/hermes-plugin-anysearch
 sha: 43c1757a5d12d4d7adb4e74326c99182f4957b6f
 description: 'AnySearch web search and extraction plus two real-time fallback chains: when a primary backend fails (Exa quota, Firecrawl timeout), the same call is served by AnySearch (1,000 free requests/day).'
 maintainer: vollegrewar
 tier: community
 category: web
 requires_hermes: ">=0.21"
-docs_url: https://github.com/vollegrewar/hermes-anysearch#readme
+docs_url: https://github.com/vollegrewar/hermes-plugin-anysearch#readme
 platforms: []
 capabilities:
   provides_tools: []
   provides_hooks: []
   provides_middleware: []
-  requires_env:
-    - ANYSEARCH_API_KEY
+  requires_env: []

From 2ac562f155153769c9bda8b6844b1762572f7cab Mon Sep 17 00:00:00 2001
From: Neal <nealzhou@me.com>
Date: Fri, 18 Sep 2026 14:02:52 +0800
Subject: [PATCH 147/190] Add hermes-subscription-meter to plugin catalog

---
 plugin-catalog/hermes-subscription-meter.yaml | 13 +++++++++++++
 1 file changed, 13 insertions(+)
 create mode 100644 plugin-catalog/hermes-subscription-meter.yaml

diff --git a/plugin-catalog/hermes-subscription-meter.yaml b/plugin-catalog/hermes-subscription-meter.yaml
new file mode 100644
index 0000000000..c0755b4bd9
--- /dev/null
+++ b/plugin-catalog/hermes-subscription-meter.yaml
@@ -0,0 +1,13 @@
+name: hermes-subscription-meter
+repo: https://github.com/NealZhouPanda/hermes-subscription-meter
+sha: 345ef9de0f8a75cb0da9e23e3962739766041732
+description: Provider-neutral subscription quota matrix panel — each provider's subscription window as a single time x quota row (elapsed vs remaining at a glance), with UI-side show/hide per provider row.
+maintainer: NealZhouPanda
+tier: community
+category: desktop
+docs_url: https://github.com/NealZhouPanda/hermes-subscription-meter#readme
+capabilities:
+  provides_tools: []
+  provides_hooks: []
+  provides_middleware: []
+  requires_env: []

From 21948acc6defeaeb2d222bb6ca5a8997705933d6 Mon Sep 17 00:00:00 2001
From: Neal <nealzhou@me.com>
Date: Fri, 18 Sep 2026 14:04:12 +0800
Subject: [PATCH 148/190] Fix pinned sha to actual v0.1.1 commit

---
 plugin-catalog/hermes-subscription-meter.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugin-catalog/hermes-subscription-meter.yaml b/plugin-catalog/hermes-subscription-meter.yaml
index c0755b4bd9..ab0c667b2a 100644
--- a/plugin-catalog/hermes-subscription-meter.yaml
+++ b/plugin-catalog/hermes-subscription-meter.yaml
@@ -1,6 +1,6 @@
 name: hermes-subscription-meter
 repo: https://github.com/NealZhouPanda/hermes-subscription-meter
-sha: 345ef9de0f8a75cb0da9e23e3962739766041732
+sha: 345ef9d5055d1053f189045e800965e8417c8421
 description: Provider-neutral subscription quota matrix panel — each provider's subscription window as a single time x quota row (elapsed vs remaining at a glance), with UI-side show/hide per provider row.
 maintainer: NealZhouPanda
 tier: community

From c0dcb13f7aca33001855c25a9453d266a11010d2 Mon Sep 17 00:00:00 2001
From: teknium <teknium@nousresearch.com>
Date: Fri, 18 Sep 2026 14:07:39 -0700
Subject: [PATCH 149/190] chore: map contributor email for @NealZhouPanda

So check-attribution passes on the catalog PR.
---
 contributors/emails/nealzhou@me.com | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 contributors/emails/nealzhou@me.com

diff --git a/contributors/emails/nealzhou@me.com b/contributors/emails/nealzhou@me.com
new file mode 100644
index 0000000000..56082b9755
--- /dev/null
+++ b/contributors/emails/nealzhou@me.com
@@ -0,0 +1 @@
+NealZhouPanda

From b09f7a8f1afca614c02626c7b8381d221eb6bd9f Mon Sep 17 00:00:00 2001
From: KeelTrace <218190424+keeltrace@users.noreply.github.com>
Date: Thu, 17 Sep 2026 16:49:48 -0700
Subject: [PATCH 150/190] feat(plugin-catalog): add Hermes Outpost

---
 plugin-catalog/hermes-outpost.yaml | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)
 create mode 100644 plugin-catalog/hermes-outpost.yaml

diff --git a/plugin-catalog/hermes-outpost.yaml b/plugin-catalog/hermes-outpost.yaml
new file mode 100644
index 0000000000..2f88731b93
--- /dev/null
+++ b/plugin-catalog/hermes-outpost.yaml
@@ -0,0 +1,20 @@
+name: hermes-outpost
+repo: https://github.com/keeltrace/hermes-outpost
+sha: 9764b4fd0fb7f7923b8c5796b0e17036046858f0
+description: Dispatch durable tasks to independent Hermes agents on configured SSH-reachable machines.
+maintainer: keeltrace
+tier: community
+category: automation
+requires_hermes: ">=0.21"
+docs_url: https://github.com/keeltrace/hermes-outpost#readme
+version: "0.1.0"
+platforms: [linux]
+capabilities:
+  provides_tools:
+  - remote_delegate_task
+  - remote_worker_status
+  - remote_worker_result
+  - remote_worker_cancel
+  provides_hooks: []
+  provides_middleware: []
+  requires_env: []

From 82749226abd03157b756d25137ca4199d574a9f6 Mon Sep 17 00:00:00 2001
From: Tony Simons <tony@aiowa.dev>
Date: Thu, 17 Sep 2026 01:34:40 -0500
Subject: [PATCH 151/190] plugin-catalog: bump hermes-newswire pin deccdc4 ->
 e6b438e
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adopts the DNS-rebinding-pinned transport hardening (repo issues #2/#3,
PR #3) and the starter-feed/settings failure-surfacing + SSRF-gated icon
proxy fix (issue #6, PR #8). Full range in
tony-simons-aiowa/hermes-newswire deccdc4..e6b438e (13 commits):

Security-relevant highlights:
- All outbound fetches (feeds, redirects, icons) now go through a pinned
  transport: the SSRF gate's validated address set is bound to the actual
  connection — no second DNS lookup, so DNS rebinding/TOCTOU has no
  window; the plugin fails closed if the pin seam changes.
- New GET /icon.json proxies favicons through the same gate and returns
  base64 data URLs — the renderer's <img> no longer performs unpinned
  DNS resolutions of feed-controlled hostnames. 64 KB cap enforced
  mid-transfer; image content-type allowlist; bounded, normalized TTL
  cache.
- Renderer surfaces backend failures (settings/sources banners,
  starter-feed inline errors) instead of silent no-ops.

Capabilities unchanged (all empty — dashboard plugin, no tools/hooks/
env). Verification at the new pin: 129 pytest, 33 renderer interaction
checks, 26 ESM render smoke, hermes plugins validate clean.
---
 plugin-catalog/hermes-newswire.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugin-catalog/hermes-newswire.yaml b/plugin-catalog/hermes-newswire.yaml
index c3efa25fb2..4d89a3dd06 100644
--- a/plugin-catalog/hermes-newswire.yaml
+++ b/plugin-catalog/hermes-newswire.yaml
@@ -1,6 +1,6 @@
 name: hermes-newswire
 repo: https://github.com/tony-simons-aiowa/hermes-newswire
-sha: deccdc4575ff45461fbf3f3c61e0945f188ef620
+sha: e6b438ee617f9b3c1ef9fe008cce2b7291abd949
 description: 'Breaking-news ticker for Hermes Desktop: a scrolling RSS/Atom/JSON-Feed strip above the
   statusbar with per-source favicons, feed search + discovery, grouping modes, offline cache, and
   in-app reading. Zero API keys, zero model tokens.'

From 24fd6ca65a1d57858244921c89bf569a5cd2bf0d Mon Sep 17 00:00:00 2001
From: Adolanium <94890352+Adolanium@users.noreply.github.com>
Date: Wed, 16 Sep 2026 22:38:00 +0300
Subject: [PATCH 152/190] feat(catalog): add Session Diff desktop plugin

---
 plugin-catalog/hermes-session-diff.yaml | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
 create mode 100644 plugin-catalog/hermes-session-diff.yaml

diff --git a/plugin-catalog/hermes-session-diff.yaml b/plugin-catalog/hermes-session-diff.yaml
new file mode 100644
index 0000000000..a72fcaa8fb
--- /dev/null
+++ b/plugin-catalog/hermes-session-diff.yaml
@@ -0,0 +1,14 @@
+name: hermes-session-diff
+repo: https://github.com/Adolanium/hermes-session-diff
+sha: 6c4928c3cb717ffba217faf986da5507dcb6e885
+description: Persistent session file diffs, run comparisons, and individual edit history in Hermes Desktop.
+maintainer: Adolanium
+tier: community
+category: desktop
+requires_hermes: ">=0.21.3"
+docs_url: https://github.com/Adolanium/hermes-session-diff#readme
+capabilities:
+  provides_tools: []
+  provides_hooks: [pre_llm_call]
+  provides_middleware: [tool_execution]
+  requires_env: []

From 369d3b49caa03e9f2d6886bd946050711f2eec3c Mon Sep 17 00:00:00 2001
From: Adolanium <94890352+Adolanium@users.noreply.github.com>
Date: Wed, 16 Sep 2026 10:23:25 +0300
Subject: [PATCH 153/190] feat(catalog): add Toolsmith desktop plugin

---
 plugin-catalog/hermes-toolsmith.yaml | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
 create mode 100644 plugin-catalog/hermes-toolsmith.yaml

diff --git a/plugin-catalog/hermes-toolsmith.yaml b/plugin-catalog/hermes-toolsmith.yaml
new file mode 100644
index 0000000000..c7beb39dbe
--- /dev/null
+++ b/plugin-catalog/hermes-toolsmith.yaml
@@ -0,0 +1,14 @@
+name: hermes-toolsmith
+repo: https://github.com/Adolanium/hermes-toolsmith
+sha: b66068edbd9642d76b4bbb023b47b7e560a7922a
+description: Local developer tools, transformation recipes, and reviewed chat handoff inside Hermes Desktop.
+maintainer: Adolanium
+tier: community
+category: desktop
+requires_hermes: ">=0.21.3"
+docs_url: https://github.com/Adolanium/hermes-toolsmith#readme
+capabilities:
+  provides_tools: []
+  provides_hooks: []
+  provides_middleware: []
+  requires_env: []

From 6a627e6eb38e28ac421d5ad8df3f676e49d0c287 Mon Sep 17 00:00:00 2001
From: chenfeijiang95-ui <293811298+chenfeijiang95-ui@users.noreply.github.com>
Date: Fri, 18 Sep 2026 09:48:06 +0800
Subject: [PATCH 154/190] feat(plugin-catalog): add live-time plugin entry

---
 plugin-catalog/live-time.yaml | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)
 create mode 100644 plugin-catalog/live-time.yaml

diff --git a/plugin-catalog/live-time.yaml b/plugin-catalog/live-time.yaml
new file mode 100644
index 0000000000..b2a0566c35
--- /dev/null
+++ b/plugin-catalog/live-time.yaml
@@ -0,0 +1,16 @@
+name: live-time
+repo: https://github.com/chenfeijiang95-ui/hermes-live-time
+sha: 338f52dffc1b3221c17b342e54589d6833a5d2b6
+description: Inject live current time into every LLM call via the pre_llm_call hook — fixes stale session-start timestamps in long/cross-day conversations.
+maintainer: chenfeijiang95-ui
+tier: community
+category: general
+docs_url: https://github.com/chenfeijiang95-ui/hermes-live-time#readme
+version: "1.0.0"
+platforms: []
+capabilities:
+  provides_tools: []
+  provides_hooks:
+  - pre_llm_call
+  provides_middleware: []
+  requires_env: []

From 558cc3bd631859750180773797f402b20746463b Mon Sep 17 00:00:00 2001
From: liuhao1024 <sunsky.lau@gmail.com>
Date: Sat, 5 Sep 2026 10:49:31 +0800
Subject: [PATCH 155/190] fix(state): self-heal pre-v3 telegram topic tables on
 read
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reads on the telegram topic tables swallowed every OperationalError as an
empty result, including 'no such column: profile_name' from v2 tables left
by upgrades that enabled DM topic mode before #76423. Topic mode then read
as disabled on every path (auto-rename lane, binding lookups), and because
the write-only v2->v3 migration only runs on /topic opt-in or bind, it was
never reached — a self-reinforcing silent failure.

_topic_read_one and list_telegram_topic_bindings_for_chat now heal a
pre-v3 table once via apply_telegram_topic_migration() and retry the read.
Absent tables still read as empty and are still never created, preserving
the deliberate opt-in-only migration contract.

Fixes #103363
---
 hermes_state_telegram.py                      |  28 ++++-
 ...est_telegram_topic_read_selfheal_103363.py | 108 ++++++++++++++++++
 2 files changed, 131 insertions(+), 5 deletions(-)
 create mode 100644 tests/gateway/test_telegram_topic_read_selfheal_103363.py

diff --git a/hermes_state_telegram.py b/hermes_state_telegram.py
index 995a68c1b3..8afd59543b 100644
--- a/hermes_state_telegram.py
+++ b/hermes_state_telegram.py
@@ -101,11 +101,19 @@ class SessionTelegramTopicsMixin:
     ``enable``/``bind`` run the migration."""
 
     def _topic_read_one(self, sql: str, params):
-        """``fetchone`` that treats an unmigrated table as None."""
+        """``fetchone`` that treats an unmigrated table as None. A pre-v3 table left by an
+        upgrade (issue #103363) is healed to v3 once and the read retried, so topic mode
+        keeps working on existing installs instead of silently reading as empty."""
         try:
             return self._read_one(sql, params)
-        except sqlite3.OperationalError:
-            return None
+        except sqlite3.OperationalError as exc:
+            if "no such column: profile_name" not in str(exc):
+                return None
+            self.apply_telegram_topic_migration()
+            try:
+                return self._read_one(sql, params)
+            except sqlite3.OperationalError:
+                return None
 
     def apply_telegram_topic_migration(self) -> None:
         """Create Telegram DM topic-mode tables on explicit /topic opt-in. Deliberately NOT
@@ -233,8 +241,18 @@ class SessionTelegramTopicsMixin:
                 "SELECT * FROM telegram_dm_topic_bindings WHERE profile_name = ? AND chat_id = ? ORDER BY updated_at DESC",
                 (profile_name, str(chat_id)),
             )
-        except sqlite3.OperationalError:
-            return []
+        except sqlite3.OperationalError as exc:
+            if "no such column: profile_name" not in str(exc):
+                return []
+            # Same pre-v3 self-heal as _topic_read_one (issue #103363).
+            self.apply_telegram_topic_migration()
+            try:
+                rows = self._read_all(
+                    "SELECT * FROM telegram_dm_topic_bindings WHERE profile_name = ? AND chat_id = ? ORDER BY updated_at DESC",
+                    (profile_name, str(chat_id)),
+                )
+            except sqlite3.OperationalError:
+                return []
         return [dict(row) for row in rows]
 
     def get_telegram_topic_binding_by_session(self, *, session_id: str) -> Optional[Dict[str, Any]]:
diff --git a/tests/gateway/test_telegram_topic_read_selfheal_103363.py b/tests/gateway/test_telegram_topic_read_selfheal_103363.py
new file mode 100644
index 0000000000..4f59362434
--- /dev/null
+++ b/tests/gateway/test_telegram_topic_read_selfheal_103363.py
@@ -0,0 +1,108 @@
+"""Issue #103363 — reading pre-v3 telegram topic tables self-heals to v3.
+
+Upgrades that enabled DM topic mode before #76423 keep v2 tables (no
+``profile_name`` column). Reads used to swallow ``no such column`` as an empty
+result, so auto topic-rename silently died on existing installs; the write-only
+migration was never reached. Reads now heal the table once and retry.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+from hermes_state import SessionDB
+
+
+CHAT = "208214988"
+
+
+def _create_v2_state(db_path: Path) -> None:
+    """The schema an install predating #76423 has on disk after upgrading."""
+    conn = sqlite3.connect(str(db_path))
+    conn.executescript(
+        f"""
+        CREATE TABLE state_meta (key TEXT PRIMARY KEY, value TEXT);
+        INSERT INTO state_meta(key, value) VALUES ('telegram_dm_topic_schema_version', '2');
+        CREATE TABLE sessions (
+            id TEXT PRIMARY KEY, source TEXT, user_id TEXT, model TEXT,
+            model_config TEXT, system_prompt TEXT, parent_session_id TEXT,
+            started_at REAL, ended_at REAL, end_reason TEXT,
+            message_count INTEGER DEFAULT 0, tool_call_count INTEGER DEFAULT 0,
+            input_tokens INTEGER DEFAULT 0, output_tokens INTEGER DEFAULT 0
+        );
+        INSERT INTO sessions(id, source, user_id, started_at)
+            VALUES ('legacy-sess', 'telegram', '{CHAT}', 1.0);
+        CREATE TABLE telegram_dm_topic_mode (
+            chat_id TEXT PRIMARY KEY, user_id TEXT NOT NULL,
+            enabled INTEGER NOT NULL DEFAULT 1,
+            activated_at REAL NOT NULL, updated_at REAL NOT NULL,
+            has_topics_enabled INTEGER, allows_users_to_create_topics INTEGER,
+            capability_checked_at REAL, intro_message_id TEXT, pinned_message_id TEXT
+        );
+        INSERT INTO telegram_dm_topic_mode(chat_id, user_id, enabled, activated_at, updated_at)
+            VALUES ('{CHAT}', '{CHAT}', 1, 1.0, 1.0);
+        CREATE TABLE telegram_dm_topic_bindings (
+            chat_id TEXT NOT NULL, thread_id TEXT NOT NULL, user_id TEXT NOT NULL,
+            session_key TEXT NOT NULL,
+            session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+            managed_mode TEXT NOT NULL DEFAULT 'auto',
+            linked_at REAL NOT NULL, updated_at REAL NOT NULL,
+            PRIMARY KEY (chat_id, thread_id)
+        );
+        INSERT INTO telegram_dm_topic_bindings
+            VALUES ('{CHAT}', '99', '{CHAT}', 'k', 'legacy-sess', 'auto', 1.0, 1.0);
+        """
+    )
+    conn.close()
+
+
+def test_topic_reads_selfheal_pre_v3_tables(tmp_path: Path):
+    db_path = tmp_path / "v2-upgrade.db"
+    _create_v2_state(db_path)
+    db = SessionDB(db_path=db_path)
+
+    # Reads on the un-migrated v2 tables return the legacy rows instead of
+    # silently reading as empty, and land them in the 'default' namespace.
+    assert db.is_telegram_topic_mode_enabled(
+        chat_id=CHAT, user_id=CHAT, profile_name="default",
+    )
+    binding = db.get_telegram_topic_binding(chat_id=CHAT, thread_id="99", profile_name="default")
+    assert binding is not None
+    assert binding["session_id"] == "legacy-sess"
+    assert db.get_meta("telegram_dm_topic_schema_version") == "3"
+    # Profile isolation still holds after the heal.
+    assert not db.is_telegram_topic_mode_enabled(
+        chat_id=CHAT, user_id=CHAT, profile_name="coder",
+    )
+    assert db.get_telegram_topic_binding(chat_id=CHAT, thread_id="99", profile_name="coder") is None
+    db.close()
+
+
+def test_list_bindings_selfheals_pre_v3_table(tmp_path: Path):
+    db_path = tmp_path / "v2-upgrade.db"
+    _create_v2_state(db_path)
+    db = SessionDB(db_path=db_path)
+
+    rows = db.list_telegram_topic_bindings_for_chat(chat_id=CHAT, profile_name="default")
+    assert [row["session_id"] for row in rows] == ["legacy-sess"]
+    assert db.get_meta("telegram_dm_topic_schema_version") == "3"
+    db.close()
+
+
+def test_absent_tables_still_read_empty_and_are_not_created(tmp_path: Path):
+    db = SessionDB(db_path=tmp_path / "fresh.db")
+
+    assert not db.is_telegram_topic_mode_enabled(chat_id=CHAT, user_id=CHAT)
+    assert db.get_telegram_topic_binding(chat_id=CHAT, thread_id="99") is None
+    assert db.list_telegram_topic_bindings_for_chat(chat_id=CHAT) == []
+    # The deliberate "reads never create the tables" contract is preserved.
+    tables = {
+        row[0]
+        for row in db._conn.execute(
+            "SELECT name FROM sqlite_master WHERE type = 'table'"
+        ).fetchall()
+    }
+    assert "telegram_dm_topic_bindings" not in tables
+    assert "telegram_dm_topic_mode" not in tables
+    db.close()

From 7ef48e2e51d856eb586e8c4ac691fbaaeb1d4e39 Mon Sep 17 00:00:00 2001
From: liuhao1024 <sunsky.lau@gmail.com>
Date: Sat, 5 Sep 2026 23:15:36 +0800
Subject: [PATCH 156/190] fix(state): make the v2->v3 topic heal atomic and
 non-silent on failure
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fold #42004's fix shape into the topic migration: the rebuild now uses
plain execute() inside _execute_write's BEGIN IMMEDIATE instead of
executescript, which implicitly committed the open transaction and ran
each statement in autocommit — a crash after the DROP stranded legacy
rows in {table}_new and the retry built an empty v3 table, breaking the
whole-callback retry contract.

A failing heal (lock timeout, cross-process race) no longer surfaces
through the readers as the silent-return shape this PR exists to fix:
the guarded helper warns once via the hermes_state logger and degrades
the read to its empty value until the next read retries the heal.

Docstrings updated: reads self-heal pre-v3 tables; absent tables stay
read-only and are never created.
---
 hermes_state_telegram.py                      | 65 ++++++++++-----
 ...est_telegram_topic_read_selfheal_103363.py | 82 +++++++++++++++++++
 2 files changed, 125 insertions(+), 22 deletions(-)

diff --git a/hermes_state_telegram.py b/hermes_state_telegram.py
index 8afd59543b..04383fb290 100644
--- a/hermes_state_telegram.py
+++ b/hermes_state_telegram.py
@@ -97,8 +97,8 @@ _UNLINKED_SCOPE_CLAUSES = """                      AND COALESCE(NULLIF(TRIM(s.pr
 
 class SessionTelegramTopicsMixin:
     """Telegram DM topic-mode tables, bindings and lookups. Read paths tolerate absent
-    tables (nobody ran ``/topic``) by returning their empty value; only
-    ``enable``/``bind`` run the migration."""
+    tables (nobody ran ``/topic``) by returning their empty value and never create them;
+    pre-v3 tables left by an upgrade are self-healed on read."""
 
     def _topic_read_one(self, sql: str, params):
         """``fetchone`` that treats an unmigrated table as None. A pre-v3 table left by an
@@ -109,16 +109,31 @@ class SessionTelegramTopicsMixin:
         except sqlite3.OperationalError as exc:
             if "no such column: profile_name" not in str(exc):
                 return None
-            self.apply_telegram_topic_migration()
+            self._heal_pre_v3_topic_tables()
             try:
                 return self._read_one(sql, params)
             except sqlite3.OperationalError:
                 return None
 
+    def _heal_pre_v3_topic_tables(self) -> None:
+        """Heal pre-v3 topic tables left by an upgrade. A failed heal (lock timeout,
+        cross-process race) warns once instead of surfacing through the readers as the
+        silent-return shape they exist to avoid; the next read retries the heal."""
+        try:
+            self.apply_telegram_topic_migration()
+        except sqlite3.Error:
+            if not getattr(self, "_topic_heal_warned", False):
+                self._topic_heal_warned = True
+                logger.warning(
+                    "telegram topic self-heal to v3 failed; reads keep hitting the "
+                    "pre-v3 schema and read as empty until the heal succeeds",
+                    exc_info=True,
+                )
+
     def apply_telegram_topic_migration(self) -> None:
-        """Create Telegram DM topic-mode tables on explicit /topic opt-in. Deliberately NOT
-        part of startup reconciliation: operators can upgrade and keep the old bot
-        behavior until a user runs /topic. Schema versions: v1 initial; v2 session_id FK
+        """Create Telegram DM topic-mode tables on explicit /topic opt-in and self-heal
+        pre-v3 tables on read (#103363); absent tables stay read-only, and startup
+        reconciliation never runs this. Schema versions: v1 initial; v2 session_id FK
         ON DELETE CASCADE (pruning clears bindings); v3 ``profile_name`` on both tables so
         multiplexed gateways sharing one state.db isolate topic state per profile.
 
@@ -131,23 +146,29 @@ class SessionTelegramTopicsMixin:
                 if "profile_name" in have:
                     continue
                 # v1/v2 → v3. SQLite can't ALTER a PK or FK, so rebuild (also supplies v2's
-                # ON DELETE CASCADE). Legacy rows land in "default" only.
+                # ON DELETE CASCADE). Legacy rows land in "default" only. Plain execute()
+                # keeps every statement inside _execute_write's BEGIN IMMEDIATE:
+                # executescript would implicitly commit the open transaction and run each
+                # statement in autocommit, so a crash after the DROP strands legacy rows
+                # in {table}_new (#42004 diagnosed the same shape for v1→v2) and breaks
+                # the whole-callback retry contract.
                 legacy_columns = columns.replace("profile_name, ", "", 1)
-                conn.executescript(f"""
-                    CREATE TABLE {table}_new ({ddl});
-                    INSERT INTO {table}_new ({columns})
-                        SELECT 'default', {legacy_columns} FROM {table};
-                    DROP TABLE {table};
-                    ALTER TABLE {table}_new RENAME TO {table};
-                    """)
+                conn.execute(f"CREATE TABLE {table}_new ({ddl})")
+                conn.execute(
+                    f"INSERT INTO {table}_new ({columns}) "
+                    f"SELECT 'default', {legacy_columns} FROM {table}"
+                )
+                conn.execute(f"DROP TABLE {table}")
+                conn.execute(f"ALTER TABLE {table}_new RENAME TO {table}")
             # Indexes after any rebuild: the user index needs profile_name.
-            conn.executescript("""
-                CREATE UNIQUE INDEX IF NOT EXISTS idx_telegram_dm_topic_bindings_session
-                ON telegram_dm_topic_bindings(session_id);
-
-                CREATE INDEX IF NOT EXISTS idx_telegram_dm_topic_bindings_user
-                ON telegram_dm_topic_bindings(profile_name, user_id, chat_id);
-                """)
+            conn.execute(
+                "CREATE UNIQUE INDEX IF NOT EXISTS idx_telegram_dm_topic_bindings_session "
+                "ON telegram_dm_topic_bindings(session_id)"
+            )
+            conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_telegram_dm_topic_bindings_user "
+                "ON telegram_dm_topic_bindings(profile_name, user_id, chat_id)"
+            )
             conn.execute(
                 "INSERT INTO state_meta (key, value) VALUES (?, ?) "
                 "ON CONFLICT(key) DO UPDATE SET value = excluded.value",
@@ -245,7 +266,7 @@ class SessionTelegramTopicsMixin:
             if "no such column: profile_name" not in str(exc):
                 return []
             # Same pre-v3 self-heal as _topic_read_one (issue #103363).
-            self.apply_telegram_topic_migration()
+            self._heal_pre_v3_topic_tables()
             try:
                 rows = self._read_all(
                     "SELECT * FROM telegram_dm_topic_bindings WHERE profile_name = ? AND chat_id = ? ORDER BY updated_at DESC",
diff --git a/tests/gateway/test_telegram_topic_read_selfheal_103363.py b/tests/gateway/test_telegram_topic_read_selfheal_103363.py
index 4f59362434..bdc6b448db 100644
--- a/tests/gateway/test_telegram_topic_read_selfheal_103363.py
+++ b/tests/gateway/test_telegram_topic_read_selfheal_103363.py
@@ -8,8 +8,10 @@ migration was never reached. Reads now heal the table once and retry.
 
 from __future__ import annotations
 
+import logging
 import sqlite3
 from pathlib import Path
+from unittest import mock
 
 from hermes_state import SessionDB
 
@@ -106,3 +108,83 @@ def test_absent_tables_still_read_empty_and_are_not_created(tmp_path: Path):
     assert "telegram_dm_topic_bindings" not in tables
     assert "telegram_dm_topic_mode" not in tables
     db.close()
+
+
+def test_heal_rebuild_rolls_back_atomically(tmp_path: Path):
+    """The v2→v3 rebuild must stay inside _execute_write's transaction.
+
+    Pre-fix the rebuild ran via executescript, which implicitly commits the
+    open transaction and then autocommits each statement: a failure once the
+    rebuild reaches the DROP strands legacy rows in {table}_new (#42004
+    diagnosed the same shape for the v1→v2 rebuild) and the retry then builds
+    an empty v3 table. The same mid-rebuild failure must now roll back to the
+    intact v2 table so the next read can heal cleanly.
+    """
+    db_path = tmp_path / "v2-upgrade.db"
+    _create_v2_state(db_path)
+    db = SessionDB(db_path=db_path)
+
+    ok = getattr(sqlite3, "SQLITE_OK", 0)
+    deny = getattr(sqlite3, "SQLITE_DENY", 2)
+    drop_table = getattr(sqlite3, "SQLITE_DROP_TABLE", 11)
+
+    def deny_topic_rebuild_drop(action, arg1, arg2, db_name, trigger):
+        if action == drop_table and arg1 and arg1.startswith("telegram_dm_topic"):
+            return deny
+        return ok
+
+    db._conn.set_authorizer(deny_topic_rebuild_drop)
+    try:
+        # The guarded read degrades to "off" instead of raising...
+        assert not db.is_telegram_topic_mode_enabled(
+            chat_id=CHAT, user_id=CHAT, profile_name="default",
+        )
+    finally:
+        db._conn.set_authorizer(None)
+
+    # ...and the interrupted rebuild rolled back completely: the v2 table and
+    # its legacy row are intact, with nothing stranded in *_new.
+    tables = {
+        row[0]
+        for row in db._conn.execute(
+            "SELECT name FROM sqlite_master WHERE type = 'table'"
+        ).fetchall()
+    }
+    assert "telegram_dm_topic_mode" in tables
+    assert not any(t.endswith("_new") for t in tables)
+    mode_row = db._conn.execute(
+        "SELECT enabled FROM telegram_dm_topic_mode WHERE chat_id = ?", (CHAT,)
+    ).fetchone()
+    assert mode_row is not None and mode_row[0] == 1
+
+    # Idempotent under retry (the _execute_write contract): the next clean
+    # read heals and keeps the legacy rows.
+    assert db.is_telegram_topic_mode_enabled(
+        chat_id=CHAT, user_id=CHAT, profile_name="default",
+    )
+    db.close()
+
+
+def test_failed_heal_warns_once_and_degrades_to_empty(tmp_path: Path, caplog):
+    """A failing heal (lock timeout, cross-process race) must not surface as the
+    silent-return shape the readers exist to fix: one warning per instance,
+    reads keep returning their empty value."""
+    db_path = tmp_path / "v2-upgrade.db"
+    _create_v2_state(db_path)
+    db = SessionDB(db_path=db_path)
+
+    def locked(*args, **kwargs):
+        raise sqlite3.OperationalError("database is locked")
+
+    with mock.patch.object(SessionDB, "apply_telegram_topic_migration", locked):
+        with caplog.at_level(logging.WARNING, logger="hermes_state"):
+            assert not db.is_telegram_topic_mode_enabled(
+                chat_id=CHAT, user_id=CHAT, profile_name="default",
+            )
+            assert db.get_telegram_topic_binding(
+                chat_id=CHAT, thread_id="99", profile_name="default",
+            ) is None
+            assert db.list_telegram_topic_bindings_for_chat(chat_id=CHAT) == []
+    # One warning across every reader, not one per read.
+    assert len([r for r in caplog.records if "self-heal" in r.getMessage()]) == 1
+    db.close()

From d612e2d15aa14a08d31f3efa6a4390c7b1a2f989 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Fri, 18 Sep 2026 23:50:26 +0530
Subject: [PATCH 157/190] refactor(state): one heal-and-retry helper for every
 topic read; trim tests

Both pre-v3 read seams (_topic_read_one and list_telegram_topic_bindings_for_chat)
carried their own copy of the heal/retry ladder; _topic_read owns it once and takes
the reader plus its empty value. A failed heal logs a warning on every attempt
instead of once per instance: the whole defect was silence, and the heal only runs
while the table is still v2, so the log stops the moment it succeeds.

Tests trimmed to the invariant bar: pre-v3 reads heal and answer (all three
readers, profile isolation kept), absent tables stay read-only, and the rebuild
rolls back atomically. Moved under tests/hermes_state/ (mirrors the source module)
without the issue number in the filename.
---
 hermes_state_telegram.py                      | 57 ++++++-------------
 .../test_telegram_topic_selfheal.py}          | 42 +-------------
 2 files changed, 20 insertions(+), 79 deletions(-)
 rename tests/{gateway/test_telegram_topic_read_selfheal_103363.py => hermes_state/test_telegram_topic_selfheal.py} (80%)

diff --git a/hermes_state_telegram.py b/hermes_state_telegram.py
index 04383fb290..c73a6d5162 100644
--- a/hermes_state_telegram.py
+++ b/hermes_state_telegram.py
@@ -100,35 +100,24 @@ class SessionTelegramTopicsMixin:
     tables (nobody ran ``/topic``) by returning their empty value and never create them;
     pre-v3 tables left by an upgrade are self-healed on read."""
 
-    def _topic_read_one(self, sql: str, params):
-        """``fetchone`` that treats an unmigrated table as None. A pre-v3 table left by an
-        upgrade (issue #103363) is healed to v3 once and the read retried, so topic mode
-        keeps working on existing installs instead of silently reading as empty."""
+    def _topic_read(self, read, sql: str, params, empty):
+        """Run ``read(sql, params)``; an absent table reads as ``empty``. A pre-v3 table left by an
+        upgrade (#103363) raises ``no such column: profile_name`` — heal it and retry, otherwise the
+        write-only migration is never reached and topic mode silently reads as off forever."""
         try:
-            return self._read_one(sql, params)
+            return read(sql, params)
         except sqlite3.OperationalError as exc:
             if "no such column: profile_name" not in str(exc):
-                return None
-            self._heal_pre_v3_topic_tables()
-            try:
-                return self._read_one(sql, params)
-            except sqlite3.OperationalError:
-                return None
-
-    def _heal_pre_v3_topic_tables(self) -> None:
-        """Heal pre-v3 topic tables left by an upgrade. A failed heal (lock timeout,
-        cross-process race) warns once instead of surfacing through the readers as the
-        silent-return shape they exist to avoid; the next read retries the heal."""
+                return empty
         try:
             self.apply_telegram_topic_migration()
+            return read(sql, params)
         except sqlite3.Error:
-            if not getattr(self, "_topic_heal_warned", False):
-                self._topic_heal_warned = True
-                logger.warning(
-                    "telegram topic self-heal to v3 failed; reads keep hitting the "
-                    "pre-v3 schema and read as empty until the heal succeeds",
-                    exc_info=True,
-                )
+            logger.warning("telegram topic tables are pre-v3 and the heal failed; reading as empty", exc_info=True)
+            return empty
+
+    def _topic_read_one(self, sql: str, params):
+        return self._topic_read(self._read_one, sql, params, None)
 
     def apply_telegram_topic_migration(self) -> None:
         """Create Telegram DM topic-mode tables on explicit /topic opt-in and self-heal
@@ -257,23 +246,11 @@ class SessionTelegramTopicsMixin:
     ) -> List[Dict[str, Any]]:
         """All bindings for one chat, newest first ([] when the table is absent)."""
         profile_name = _normalize_telegram_topic_profile_name(profile_name)
-        try:
-            rows = self._read_all(
-                "SELECT * FROM telegram_dm_topic_bindings WHERE profile_name = ? AND chat_id = ? ORDER BY updated_at DESC",
-                (profile_name, str(chat_id)),
-            )
-        except sqlite3.OperationalError as exc:
-            if "no such column: profile_name" not in str(exc):
-                return []
-            # Same pre-v3 self-heal as _topic_read_one (issue #103363).
-            self._heal_pre_v3_topic_tables()
-            try:
-                rows = self._read_all(
-                    "SELECT * FROM telegram_dm_topic_bindings WHERE profile_name = ? AND chat_id = ? ORDER BY updated_at DESC",
-                    (profile_name, str(chat_id)),
-                )
-            except sqlite3.OperationalError:
-                return []
+        rows = self._topic_read(
+            self._read_all,
+            "SELECT * FROM telegram_dm_topic_bindings WHERE profile_name = ? AND chat_id = ? ORDER BY updated_at DESC",
+            (profile_name, str(chat_id)), [],
+        )
         return [dict(row) for row in rows]
 
     def get_telegram_topic_binding_by_session(self, *, session_id: str) -> Optional[Dict[str, Any]]:
diff --git a/tests/gateway/test_telegram_topic_read_selfheal_103363.py b/tests/hermes_state/test_telegram_topic_selfheal.py
similarity index 80%
rename from tests/gateway/test_telegram_topic_read_selfheal_103363.py
rename to tests/hermes_state/test_telegram_topic_selfheal.py
index bdc6b448db..4a3b3d28c6 100644
--- a/tests/gateway/test_telegram_topic_read_selfheal_103363.py
+++ b/tests/hermes_state/test_telegram_topic_selfheal.py
@@ -1,4 +1,4 @@
-"""Issue #103363 — reading pre-v3 telegram topic tables self-heals to v3.
+"""Regression for #103363 — reading pre-v3 telegram topic tables self-heals to v3.
 
 Upgrades that enabled DM topic mode before #76423 keep v2 tables (no
 ``profile_name`` column). Reads used to swallow ``no such column`` as an empty
@@ -8,10 +8,8 @@ migration was never reached. Reads now heal the table once and retry.
 
 from __future__ import annotations
 
-import logging
 import sqlite3
 from pathlib import Path
-from unittest import mock
 
 from hermes_state import SessionDB
 
@@ -72,6 +70,8 @@ def test_topic_reads_selfheal_pre_v3_tables(tmp_path: Path):
     binding = db.get_telegram_topic_binding(chat_id=CHAT, thread_id="99", profile_name="default")
     assert binding is not None
     assert binding["session_id"] == "legacy-sess"
+    rows = db.list_telegram_topic_bindings_for_chat(chat_id=CHAT, profile_name="default")
+    assert [row["session_id"] for row in rows] == ["legacy-sess"]
     assert db.get_meta("telegram_dm_topic_schema_version") == "3"
     # Profile isolation still holds after the heal.
     assert not db.is_telegram_topic_mode_enabled(
@@ -81,17 +81,6 @@ def test_topic_reads_selfheal_pre_v3_tables(tmp_path: Path):
     db.close()
 
 
-def test_list_bindings_selfheals_pre_v3_table(tmp_path: Path):
-    db_path = tmp_path / "v2-upgrade.db"
-    _create_v2_state(db_path)
-    db = SessionDB(db_path=db_path)
-
-    rows = db.list_telegram_topic_bindings_for_chat(chat_id=CHAT, profile_name="default")
-    assert [row["session_id"] for row in rows] == ["legacy-sess"]
-    assert db.get_meta("telegram_dm_topic_schema_version") == "3"
-    db.close()
-
-
 def test_absent_tables_still_read_empty_and_are_not_created(tmp_path: Path):
     db = SessionDB(db_path=tmp_path / "fresh.db")
 
@@ -163,28 +152,3 @@ def test_heal_rebuild_rolls_back_atomically(tmp_path: Path):
         chat_id=CHAT, user_id=CHAT, profile_name="default",
     )
     db.close()
-
-
-def test_failed_heal_warns_once_and_degrades_to_empty(tmp_path: Path, caplog):
-    """A failing heal (lock timeout, cross-process race) must not surface as the
-    silent-return shape the readers exist to fix: one warning per instance,
-    reads keep returning their empty value."""
-    db_path = tmp_path / "v2-upgrade.db"
-    _create_v2_state(db_path)
-    db = SessionDB(db_path=db_path)
-
-    def locked(*args, **kwargs):
-        raise sqlite3.OperationalError("database is locked")
-
-    with mock.patch.object(SessionDB, "apply_telegram_topic_migration", locked):
-        with caplog.at_level(logging.WARNING, logger="hermes_state"):
-            assert not db.is_telegram_topic_mode_enabled(
-                chat_id=CHAT, user_id=CHAT, profile_name="default",
-            )
-            assert db.get_telegram_topic_binding(
-                chat_id=CHAT, thread_id="99", profile_name="default",
-            ) is None
-            assert db.list_telegram_topic_bindings_for_chat(chat_id=CHAT) == []
-    # One warning across every reader, not one per read.
-    assert len([r for r in caplog.records if "self-heal" in r.getMessage()]) == 1
-    db.close()

From 83b50f6bea9024c8c434de97a95374721dd5a235 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:59:52 +0530
Subject: [PATCH 158/190] =?UTF-8?q?fix(state):=20v2=E2=86=92v3=20topic=20r?=
 =?UTF-8?q?ebuild=20survives=20orphan=20bindings=20and=20a=20stranded=20sc?=
 =?UTF-8?q?ratch=20table?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review of the heal-on-read stack found two ways the rebuild fails deterministically
on exactly the installs it targets, and a failed heal is retried (with a WARNING
traceback) on every topic read — several per inbound Telegram message:

- v1 bindings had no ON DELETE CASCADE, so pruned sessions left orphan rows; the
  writer connection runs foreign_keys=ON, so copying them into the v3 table raises
  IntegrityError. Copy only rows whose session still exists — what a CASCADE would
  have kept.
- An older build's executescript rebuild that crashed after CREATE leaves
  {table}_new behind; the new CREATE then fails with "already exists". Drop the
  scratch table first — the legacy table is still intact to re-copy.

Also from review: the post-heal retry read is no longer inside the heal's
except (a SELECT error after a successful heal propagated before and does again),
_topic_read takes a thunk so _topic_read_one/_topic_read_all mirror _read_one/
_read_all, the migration docstring keeps its original WHY for staying out of
startup reconciliation, and the tests use public reads (get_meta, the topic
readers) instead of db._conn probes. The v2 fixture now carries an orphan binding
and a stranded scratch table; without either fix above the heal test fails with
the corresponding SQLite error.
---
 hermes_state_telegram.py                      | 43 +++++++++--------
 .../test_telegram_topic_selfheal.py           | 47 +++++++------------
 2 files changed, 40 insertions(+), 50 deletions(-)

diff --git a/hermes_state_telegram.py b/hermes_state_telegram.py
index c73a6d5162..a54775443f 100644
--- a/hermes_state_telegram.py
+++ b/hermes_state_telegram.py
@@ -100,29 +100,33 @@ class SessionTelegramTopicsMixin:
     tables (nobody ran ``/topic``) by returning their empty value and never create them;
     pre-v3 tables left by an upgrade are self-healed on read."""
 
-    def _topic_read(self, read, sql: str, params, empty):
-        """Run ``read(sql, params)``; an absent table reads as ``empty``. A pre-v3 table left by an
-        upgrade (#103363) raises ``no such column: profile_name`` — heal it and retry, otherwise the
+    def _topic_read(self, read, empty):
+        """Run ``read()``; an absent table reads as ``empty``. A pre-v3 table left by an upgrade
+        (#103363) raises ``no such column: profile_name`` — heal it and retry, otherwise the
         write-only migration is never reached and topic mode silently reads as off forever."""
         try:
-            return read(sql, params)
+            return read()
         except sqlite3.OperationalError as exc:
             if "no such column: profile_name" not in str(exc):
                 return empty
         try:
             self.apply_telegram_topic_migration()
-            return read(sql, params)
         except sqlite3.Error:
             logger.warning("telegram topic tables are pre-v3 and the heal failed; reading as empty", exc_info=True)
             return empty
+        return read()
 
     def _topic_read_one(self, sql: str, params):
-        return self._topic_read(self._read_one, sql, params, None)
+        return self._topic_read(lambda: self._read_one(sql, params), None)
+
+    def _topic_read_all(self, sql: str, params):
+        return self._topic_read(lambda: self._read_all(sql, params), [])
 
     def apply_telegram_topic_migration(self) -> None:
-        """Create Telegram DM topic-mode tables on explicit /topic opt-in and self-heal
-        pre-v3 tables on read (#103363); absent tables stay read-only, and startup
-        reconciliation never runs this. Schema versions: v1 initial; v2 session_id FK
+        """Create Telegram DM topic-mode tables on explicit /topic opt-in. Deliberately NOT
+        part of startup reconciliation: operators can upgrade and keep the old bot
+        behavior until a user runs /topic. Also invoked by ``_topic_read`` to heal a
+        pre-v3 table an upgrade left behind (#103363). Schema versions: v1 initial; v2 session_id FK
         ON DELETE CASCADE (pruning clears bindings); v3 ``profile_name`` on both tables so
         multiplexed gateways sharing one state.db isolate topic state per profile.
 
@@ -135,17 +139,19 @@ class SessionTelegramTopicsMixin:
                 if "profile_name" in have:
                     continue
                 # v1/v2 → v3. SQLite can't ALTER a PK or FK, so rebuild (also supplies v2's
-                # ON DELETE CASCADE). Legacy rows land in "default" only. Plain execute()
-                # keeps every statement inside _execute_write's BEGIN IMMEDIATE:
-                # executescript would implicitly commit the open transaction and run each
-                # statement in autocommit, so a crash after the DROP strands legacy rows
-                # in {table}_new (#42004 diagnosed the same shape for v1→v2) and breaks
-                # the whole-callback retry contract.
+                # ON DELETE CASCADE). Legacy rows land in "default" only. execute(), not
+                # executescript(): executescript COMMITs the open BEGIN IMMEDIATE, so a crash after
+                # the DROP strands rows in {table}_new (#42004). A {table}_new left by such a crash
+                # on an older build is dropped first; the legacy table is still intact to re-copy.
+                # v1 bindings had no ON DELETE CASCADE, so pruned sessions left orphan rows that
+                # the v3 FK (foreign_keys=ON on the writer) would reject — copy only live ones.
                 legacy_columns = columns.replace("profile_name, ", "", 1)
+                live = " WHERE EXISTS (SELECT 1 FROM sessions s WHERE s.id = session_id)" if "session_id" in columns else ""
+                conn.execute(f"DROP TABLE IF EXISTS {table}_new")
                 conn.execute(f"CREATE TABLE {table}_new ({ddl})")
                 conn.execute(
                     f"INSERT INTO {table}_new ({columns}) "
-                    f"SELECT 'default', {legacy_columns} FROM {table}"
+                    f"SELECT 'default', {legacy_columns} FROM {table}{live}"
                 )
                 conn.execute(f"DROP TABLE {table}")
                 conn.execute(f"ALTER TABLE {table}_new RENAME TO {table}")
@@ -246,10 +252,9 @@ class SessionTelegramTopicsMixin:
     ) -> List[Dict[str, Any]]:
         """All bindings for one chat, newest first ([] when the table is absent)."""
         profile_name = _normalize_telegram_topic_profile_name(profile_name)
-        rows = self._topic_read(
-            self._read_all,
+        rows = self._topic_read_all(
             "SELECT * FROM telegram_dm_topic_bindings WHERE profile_name = ? AND chat_id = ? ORDER BY updated_at DESC",
-            (profile_name, str(chat_id)), [],
+            (profile_name, str(chat_id)),
         )
         return [dict(row) for row in rows]
 
diff --git a/tests/hermes_state/test_telegram_topic_selfheal.py b/tests/hermes_state/test_telegram_topic_selfheal.py
index 4a3b3d28c6..82d7a1f1c5 100644
--- a/tests/hermes_state/test_telegram_topic_selfheal.py
+++ b/tests/hermes_state/test_telegram_topic_selfheal.py
@@ -52,6 +52,11 @@ def _create_v2_state(db_path: Path) -> None:
         );
         INSERT INTO telegram_dm_topic_bindings
             VALUES ('{CHAT}', '99', '{CHAT}', 'k', 'legacy-sess', 'auto', 1.0, 1.0);
+        -- v1 had no ON DELETE CASCADE: a pruned session leaves an orphan binding behind.
+        INSERT INTO telegram_dm_topic_bindings
+            VALUES ('{CHAT}', '7', '{CHAT}', 'k7', 'pruned-sess', 'auto', 1.0, 1.0);
+        -- an older build's executescript rebuild crashed after CREATE: the scratch table is stranded.
+        CREATE TABLE telegram_dm_topic_mode_new (profile_name TEXT, chat_id TEXT);
         """
     )
     conn.close()
@@ -70,8 +75,10 @@ def test_topic_reads_selfheal_pre_v3_tables(tmp_path: Path):
     binding = db.get_telegram_topic_binding(chat_id=CHAT, thread_id="99", profile_name="default")
     assert binding is not None
     assert binding["session_id"] == "legacy-sess"
+    # The orphan row is dropped (a v2/v3 CASCADE would have removed it) and the stranded scratch table is gone.
     rows = db.list_telegram_topic_bindings_for_chat(chat_id=CHAT, profile_name="default")
     assert [row["session_id"] for row in rows] == ["legacy-sess"]
+    assert db.get_telegram_topic_binding(chat_id=CHAT, thread_id="7", profile_name="default") is None
     assert db.get_meta("telegram_dm_topic_schema_version") == "3"
     # Profile isolation still holds after the heal.
     assert not db.is_telegram_topic_mode_enabled(
@@ -87,15 +94,9 @@ def test_absent_tables_still_read_empty_and_are_not_created(tmp_path: Path):
     assert not db.is_telegram_topic_mode_enabled(chat_id=CHAT, user_id=CHAT)
     assert db.get_telegram_topic_binding(chat_id=CHAT, thread_id="99") is None
     assert db.list_telegram_topic_bindings_for_chat(chat_id=CHAT) == []
-    # The deliberate "reads never create the tables" contract is preserved.
-    tables = {
-        row[0]
-        for row in db._conn.execute(
-            "SELECT name FROM sqlite_master WHERE type = 'table'"
-        ).fetchall()
-    }
-    assert "telegram_dm_topic_bindings" not in tables
-    assert "telegram_dm_topic_mode" not in tables
+    # The deliberate "reads never create the tables" contract is preserved: the migration is the only
+    # creator and always stamps the schema version in the same transaction.
+    assert db.get_meta("telegram_dm_topic_schema_version") is None
     db.close()
 
 
@@ -113,14 +114,10 @@ def test_heal_rebuild_rolls_back_atomically(tmp_path: Path):
     _create_v2_state(db_path)
     db = SessionDB(db_path=db_path)
 
-    ok = getattr(sqlite3, "SQLITE_OK", 0)
-    deny = getattr(sqlite3, "SQLITE_DENY", 2)
-    drop_table = getattr(sqlite3, "SQLITE_DROP_TABLE", 11)
-
     def deny_topic_rebuild_drop(action, arg1, arg2, db_name, trigger):
-        if action == drop_table and arg1 and arg1.startswith("telegram_dm_topic"):
-            return deny
-        return ok
+        if action == sqlite3.SQLITE_DROP_TABLE and arg1 and arg1.startswith("telegram_dm_topic"):
+            return sqlite3.SQLITE_DENY
+        return sqlite3.SQLITE_OK
 
     db._conn.set_authorizer(deny_topic_rebuild_drop)
     try:
@@ -131,21 +128,9 @@ def test_heal_rebuild_rolls_back_atomically(tmp_path: Path):
     finally:
         db._conn.set_authorizer(None)
 
-    # ...and the interrupted rebuild rolled back completely: the v2 table and
-    # its legacy row are intact, with nothing stranded in *_new.
-    tables = {
-        row[0]
-        for row in db._conn.execute(
-            "SELECT name FROM sqlite_master WHERE type = 'table'"
-        ).fetchall()
-    }
-    assert "telegram_dm_topic_mode" in tables
-    assert not any(t.endswith("_new") for t in tables)
-    mode_row = db._conn.execute(
-        "SELECT enabled FROM telegram_dm_topic_mode WHERE chat_id = ?", (CHAT,)
-    ).fetchone()
-    assert mode_row is not None and mode_row[0] == 1
-
+    # ...and the interrupted rebuild rolled back completely (a stranded *_new or a dropped original
+    # would make the retry below read as off, and the version stamp rolled back with it).
+    assert db.get_meta("telegram_dm_topic_schema_version") == "2"
     # Idempotent under retry (the _execute_write contract): the next clean
     # read heals and keeps the legacy rows.
     assert db.is_telegram_topic_mode_enabled(

From 0a5046ec92046fa8d54d97f2324da61fcad40475 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 01:26:30 +0530
Subject: [PATCH 159/190] test(state): atomicity probe fails the rebuild's
 final RENAME, not its first DROP

Denying every DROP TABLE on the topic tables now trips on the new
'DROP TABLE IF EXISTS {table}_new' before anything is written, so the probe
passed even with an executescript rebuild. Deny the RENAME of the scratch
table instead: the legacy table is already dropped at that point, and only a
transactional rebuild still has its rows on retry (verified red with
executescript swapped back in).
---
 tests/hermes_state/test_telegram_topic_selfheal.py | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/tests/hermes_state/test_telegram_topic_selfheal.py b/tests/hermes_state/test_telegram_topic_selfheal.py
index 82d7a1f1c5..5e51ae23a4 100644
--- a/tests/hermes_state/test_telegram_topic_selfheal.py
+++ b/tests/hermes_state/test_telegram_topic_selfheal.py
@@ -114,12 +114,14 @@ def test_heal_rebuild_rolls_back_atomically(tmp_path: Path):
     _create_v2_state(db_path)
     db = SessionDB(db_path=db_path)
 
-    def deny_topic_rebuild_drop(action, arg1, arg2, db_name, trigger):
-        if action == sqlite3.SQLITE_DROP_TABLE and arg1 and arg1.startswith("telegram_dm_topic"):
+    def deny_topic_rebuild_rename(action, arg1, arg2, db_name, trigger):
+        # Fail the rebuild's LAST statement, after the legacy table is already dropped: only a
+        # transactional rebuild still has the rows at that point.
+        if action == sqlite3.SQLITE_ALTER_TABLE and arg2 == "telegram_dm_topic_mode_new":
             return sqlite3.SQLITE_DENY
         return sqlite3.SQLITE_OK
 
-    db._conn.set_authorizer(deny_topic_rebuild_drop)
+    db._conn.set_authorizer(deny_topic_rebuild_rename)
     try:
         # The guarded read degrades to "off" instead of raising...
         assert not db.is_telegram_topic_mode_enabled(
@@ -128,8 +130,8 @@ def test_heal_rebuild_rolls_back_atomically(tmp_path: Path):
     finally:
         db._conn.set_authorizer(None)
 
-    # ...and the interrupted rebuild rolled back completely (a stranded *_new or a dropped original
-    # would make the retry below read as off, and the version stamp rolled back with it).
+    # ...and the interrupted rebuild rolled back completely: the dropped original is back
+    # (otherwise the retry below builds an empty v3 table and reads as off) and so is the version stamp.
     assert db.get_meta("telegram_dm_topic_schema_version") == "2"
     # Idempotent under retry (the _execute_write contract): the next clean
     # read heals and keeps the legacy rows.

From 8b038f36659a65b436084889e564a71857c2d660 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 02:45:15 +0530
Subject: [PATCH 160/190] refactor(state): topic rebuild goes through
 _rebuild_table; heal also swallows a replaced state.db

The hand-rolled CREATE/INSERT/DROP/RENAME duplicated SessionSchemaMixin._rebuild_table,
which already runs inside a caller-owned transaction and has its own atomicity test.
The stranded {table}_new drop stays: older builds crashed with that scratch name.

_execute_write probes the DB generation before running the callback and raises
StateDbReplacedError (a RuntimeError, not sqlite3.Error); _read_ctx never does, so
the heal must not let it escape a read path that promises the empty value.

Atomicity probe now denies the copy into the fresh table: a non-transactional
rebuild leaves an empty v3 table the retry skips (verified red with executescript).
---
 hermes_state_telegram.py                      | 19 ++++++--------
 .../test_telegram_topic_selfheal.py           | 26 +++++++------------
 2 files changed, 18 insertions(+), 27 deletions(-)

diff --git a/hermes_state_telegram.py b/hermes_state_telegram.py
index a54775443f..34d57e3924 100644
--- a/hermes_state_telegram.py
+++ b/hermes_state_telegram.py
@@ -9,6 +9,7 @@ import time
 from typing import Any, Dict, List, Optional
 
 from hermes_state_common import _PREVIEW_ELIGIBLE_SQL, _PREVIEW_RAW_SELECT, _sql_session_last_active
+from hermes_state_errors import StateDbReplacedError
 
 # caplog tests pin the "hermes_state" logger name.
 logger = logging.getLogger("hermes_state")
@@ -111,7 +112,7 @@ class SessionTelegramTopicsMixin:
                 return empty
         try:
             self.apply_telegram_topic_migration()
-        except sqlite3.Error:
+        except (sqlite3.Error, StateDbReplacedError):
             logger.warning("telegram topic tables are pre-v3 and the heal failed; reading as empty", exc_info=True)
             return empty
         return read()
@@ -139,22 +140,18 @@ class SessionTelegramTopicsMixin:
                 if "profile_name" in have:
                     continue
                 # v1/v2 → v3. SQLite can't ALTER a PK or FK, so rebuild (also supplies v2's
-                # ON DELETE CASCADE). Legacy rows land in "default" only. execute(), not
-                # executescript(): executescript COMMITs the open BEGIN IMMEDIATE, so a crash after
-                # the DROP strands rows in {table}_new (#42004). A {table}_new left by such a crash
-                # on an older build is dropped first; the legacy table is still intact to re-copy.
+                # ON DELETE CASCADE); _rebuild_table runs inside the open BEGIN IMMEDIATE so a crash
+                # rolls back instead of stranding rows (#42004). A {table}_new left by an older
+                # build's executescript crash is dropped first; its legacy table is still intact.
                 # v1 bindings had no ON DELETE CASCADE, so pruned sessions left orphan rows that
                 # the v3 FK (foreign_keys=ON on the writer) would reject — copy only live ones.
                 legacy_columns = columns.replace("profile_name, ", "", 1)
                 live = " WHERE EXISTS (SELECT 1 FROM sessions s WHERE s.id = session_id)" if "session_id" in columns else ""
                 conn.execute(f"DROP TABLE IF EXISTS {table}_new")
-                conn.execute(f"CREATE TABLE {table}_new ({ddl})")
-                conn.execute(
-                    f"INSERT INTO {table}_new ({columns}) "
-                    f"SELECT 'default', {legacy_columns} FROM {table}{live}"
+                self._rebuild_table(
+                    conn.cursor(), table, f"{table}_legacy", f"CREATE TABLE {table} ({ddl})",
+                    f"INSERT INTO {table} ({columns}) SELECT 'default', {legacy_columns} FROM {table}_legacy{live}",
                 )
-                conn.execute(f"DROP TABLE {table}")
-                conn.execute(f"ALTER TABLE {table}_new RENAME TO {table}")
             # Indexes after any rebuild: the user index needs profile_name.
             conn.execute(
                 "CREATE UNIQUE INDEX IF NOT EXISTS idx_telegram_dm_topic_bindings_session "
diff --git a/tests/hermes_state/test_telegram_topic_selfheal.py b/tests/hermes_state/test_telegram_topic_selfheal.py
index 5e51ae23a4..ed36153791 100644
--- a/tests/hermes_state/test_telegram_topic_selfheal.py
+++ b/tests/hermes_state/test_telegram_topic_selfheal.py
@@ -101,27 +101,21 @@ def test_absent_tables_still_read_empty_and_are_not_created(tmp_path: Path):
 
 
 def test_heal_rebuild_rolls_back_atomically(tmp_path: Path):
-    """The v2→v3 rebuild must stay inside _execute_write's transaction.
-
-    Pre-fix the rebuild ran via executescript, which implicitly commits the
-    open transaction and then autocommits each statement: a failure once the
-    rebuild reaches the DROP strands legacy rows in {table}_new (#42004
-    diagnosed the same shape for the v1→v2 rebuild) and the retry then builds
-    an empty v3 table. The same mid-rebuild failure must now roll back to the
-    intact v2 table so the next read can heal cleanly.
-    """
+    """The v2→v3 rebuild must stay inside _execute_write's transaction: a mid-rebuild
+    failure leaves the intact v2 table (and its version stamp) for the next read to heal,
+    never a half-built v3 table the retry would mistake for a finished one (#42004)."""
     db_path = tmp_path / "v2-upgrade.db"
     _create_v2_state(db_path)
     db = SessionDB(db_path=db_path)
 
-    def deny_topic_rebuild_rename(action, arg1, arg2, db_name, trigger):
-        # Fail the rebuild's LAST statement, after the legacy table is already dropped: only a
-        # transactional rebuild still has the rows at that point.
-        if action == sqlite3.SQLITE_ALTER_TABLE and arg2 == "telegram_dm_topic_mode_new":
+    def deny_topic_rebuild_copy(action, arg1, arg2, db_name, trigger):
+        # Fail the copy into the fresh table, after the live table was renamed away: a
+        # non-transactional rebuild leaves an empty v3 table behind and the retry skips it.
+        if action == sqlite3.SQLITE_INSERT and arg1 == "telegram_dm_topic_mode":
             return sqlite3.SQLITE_DENY
         return sqlite3.SQLITE_OK
 
-    db._conn.set_authorizer(deny_topic_rebuild_rename)
+    db._conn.set_authorizer(deny_topic_rebuild_copy)
     try:
         # The guarded read degrades to "off" instead of raising...
         assert not db.is_telegram_topic_mode_enabled(
@@ -130,8 +124,8 @@ def test_heal_rebuild_rolls_back_atomically(tmp_path: Path):
     finally:
         db._conn.set_authorizer(None)
 
-    # ...and the interrupted rebuild rolled back completely: the dropped original is back
-    # (otherwise the retry below builds an empty v3 table and reads as off) and so is the version stamp.
+    # ...and the interrupted rebuild rolled back completely: the renamed-away original is back
+    # (otherwise the retry below finds no legacy table, builds an empty v3 one and reads as off).
     assert db.get_meta("telegram_dm_topic_schema_version") == "2"
     # Idempotent under retry (the _execute_write contract): the next clean
     # read heals and keeps the legacy rows.

From 2bfb95b3961f6cdc175121a5094c245a976dceaf Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 02:47:28 +0530
Subject: [PATCH 161/190] chore: map amitcse, eduardo and jinlingzi-cmd
 contributor emails

---
 contributors/emails/431013+amitcse@users.noreply.github.com | 2 ++
 contributors/emails/tong.xd@outlook.com                     | 2 ++
 contributors/emails/waldo@minicat.local                     | 2 ++
 3 files changed, 6 insertions(+)
 create mode 100644 contributors/emails/431013+amitcse@users.noreply.github.com
 create mode 100644 contributors/emails/tong.xd@outlook.com
 create mode 100644 contributors/emails/waldo@minicat.local

diff --git a/contributors/emails/431013+amitcse@users.noreply.github.com b/contributors/emails/431013+amitcse@users.noreply.github.com
new file mode 100644
index 0000000000..8d460b1e5f
--- /dev/null
+++ b/contributors/emails/431013+amitcse@users.noreply.github.com
@@ -0,0 +1,2 @@
+amitcse
+# WhatsApp group-intake / LID salvage (#63416, #73465, #72592)
diff --git a/contributors/emails/tong.xd@outlook.com b/contributors/emails/tong.xd@outlook.com
new file mode 100644
index 0000000000..922485ece3
--- /dev/null
+++ b/contributors/emails/tong.xd@outlook.com
@@ -0,0 +1,2 @@
+jinlingzi-cmd
+# WhatsApp group-intake / LID salvage (#63416, #73465, #72592)
diff --git a/contributors/emails/waldo@minicat.local b/contributors/emails/waldo@minicat.local
new file mode 100644
index 0000000000..4eb4e1e25e
--- /dev/null
+++ b/contributors/emails/waldo@minicat.local
@@ -0,0 +1,2 @@
+eduardo
+# WhatsApp group-intake / LID salvage (#63416, #73465, #72592)

From 8a55373dbf425fc71f6bb4c1ab95b05caf4a50cb Mon Sep 17 00:00:00 2001
From: Amit C <431013+amitcse@users.noreply.github.com>
Date: Mon, 13 Jul 2026 02:38:27 +0530
Subject: [PATCH 162/190] fix(whatsapp): authorize first-contact LID senders

---
 scripts/whatsapp-bridge/allowlist.js       |  9 +++++++++
 scripts/whatsapp-bridge/allowlist.test.mjs | 22 ++++++++++++++++++++++
 scripts/whatsapp-bridge/bridge.js          | 10 ++++++----
 3 files changed, 37 insertions(+), 4 deletions(-)

diff --git a/scripts/whatsapp-bridge/allowlist.js b/scripts/whatsapp-bridge/allowlist.js
index ffc8949a7b..2cb5c634a8 100644
--- a/scripts/whatsapp-bridge/allowlist.js
+++ b/scripts/whatsapp-bridge/allowlist.js
@@ -63,6 +63,15 @@ export function expandWhatsAppIdentifiers(identifier, sessionDir) {
   return resolved;
 }
 
+export function matchesAllowedSender(senderId, senderPn, allowedUsers, sessionDir) {
+  // WhatsApp Multi-Device can expose a first-contact sender as an opaque LID
+  // before it persists LID mapping files. Baileys supplies the same sender's
+  // authenticated phone JID separately in msg.key.senderPn, so consult it
+  // as an additional alias without changing the allowlist itself.
+  return matchesAllowedUser(senderId, allowedUsers, sessionDir)
+    || matchesAllowedUser(senderPn, allowedUsers, sessionDir);
+}
+
 export function matchesAllowedUser(senderId, allowedUsers, sessionDir) {
   // Empty allowlist = NO ONE allowed (secure default, #8389).  Operators
   // who want an open bot must set ``WHATSAPP_ALLOWED_USERS=*`` explicitly.
diff --git a/scripts/whatsapp-bridge/allowlist.test.mjs b/scripts/whatsapp-bridge/allowlist.test.mjs
index c6ca1cb3c4..42fde36804 100644
--- a/scripts/whatsapp-bridge/allowlist.test.mjs
+++ b/scripts/whatsapp-bridge/allowlist.test.mjs
@@ -6,6 +6,7 @@ import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 
 import {
   expandWhatsAppIdentifiers,
+  matchesAllowedSender,
   matchesAllowedUser,
   normalizeWhatsAppIdentifier,
   parseAllowedUsers,
@@ -46,6 +47,27 @@ test('matchesAllowedUser accepts mapped lid sender when allowlist only contains
   }
 });
 
+test('matchesAllowedSender accepts Baileys senderPn when a first-contact LID has no mapping yet', () => {
+  const sessionDir = mkdtempSync(path.join(os.tmpdir(), 'hermes-wa-allowlist-'));
+
+  try {
+    const allowedUsers = parseAllowedUsers('+19175395595');
+    // On a first message from a WhatsApp Multi-Device contact, Baileys can
+    // emit a LID as senderId before it has written LID mapping files, while
+    // senderPn carries WhatsApp's authenticated phone JID.
+    assert.equal(
+      matchesAllowedSender('267383306489914@lid', '19175395595@s.whatsapp.net', allowedUsers, sessionDir),
+      true,
+    );
+    assert.equal(
+      matchesAllowedSender('267383306489914@lid', '18881234567@s.whatsapp.net', allowedUsers, sessionDir),
+      false,
+    );
+  } finally {
+    rmSync(sessionDir, { recursive: true, force: true });
+  }
+});
+
 test('matchesAllowedUser treats * as allow-all wildcard', () => {
   const sessionDir = mkdtempSync(path.join(os.tmpdir(), 'hermes-wa-allowlist-'));
 
diff --git a/scripts/whatsapp-bridge/bridge.js b/scripts/whatsapp-bridge/bridge.js
index b00a1fec02..830247f10d 100644
--- a/scripts/whatsapp-bridge/bridge.js
+++ b/scripts/whatsapp-bridge/bridge.js
@@ -30,7 +30,7 @@ import { randomBytes, createHash } from 'crypto';
 import { execFileSync } from 'child_process';
 import { tmpdir } from 'os';
 import qrcode from 'qrcode-terminal';
-import { matchesAllowedUser, parseAllowedUsers } from './allowlist.js';
+import { matchesAllowedSender, matchesAllowedUser, parseAllowedUsers } from './allowlist.js';
 import { createOutboundIdTracker } from './outbound_ids.js';
 import { classifyOwnerMessageGate } from './owner_message_gate.js';
 import {
@@ -525,8 +525,10 @@ async function startSocket() {
 
       const chatId = msg.key.remoteJid;
       const senderId = msg.key.participant || chatId;
+      const senderPn = msg.key.senderPn || '';
+      const resolvedSenderId = senderPn || senderId;
       const isGroup = chatId.endsWith('@g.us');
-      const senderNumber = senderId.replace(/@.*/, '');
+      const senderNumber = resolvedSenderId.replace(/@.*/, '');
       emitDebugEvent({
         stage: 'upsert',
         type,
@@ -627,7 +629,7 @@ async function startSocket() {
           } catch {}
           continue;
         }
-        if (WHATSAPP_DM_POLICY !== 'pairing' && !matchesAllowedUser(senderId, ALLOWED_USERS, SESSION_DIR)) {
+        if (WHATSAPP_DM_POLICY !== 'pairing' && !matchesAllowedSender(senderId, senderPn, ALLOWED_USERS, SESSION_DIR)) {
           try {
             console.log(JSON.stringify({
               event: 'ignored',
@@ -703,7 +705,7 @@ async function startSocket() {
       const event = await extractBridgeEvent({
         msg,
         chatId,
-        senderId,
+        senderId: resolvedSenderId,
         senderNumber,
         botIds,
         isGroup,

From 3926c4209c7848515d96635a1512a67788974649 Mon Sep 17 00:00:00 2001
From: jinlingzi-cmd <tong.xd@outlook.com>
Date: Mon, 27 Jul 2026 17:50:28 +0800
Subject: [PATCH 163/190] fix: WhatsApp group messages dropped when LID sender
 has no lid-mapping (#72529)

---
 scripts/whatsapp-bridge/allowlist.js       |  9 +++--
 scripts/whatsapp-bridge/allowlist.test.mjs | 46 ++++++++++++++++++++++
 scripts/whatsapp-bridge/bridge.js          | 11 ++++--
 3 files changed, 59 insertions(+), 7 deletions(-)

diff --git a/scripts/whatsapp-bridge/allowlist.js b/scripts/whatsapp-bridge/allowlist.js
index 2cb5c634a8..9b02507420 100644
--- a/scripts/whatsapp-bridge/allowlist.js
+++ b/scripts/whatsapp-bridge/allowlist.js
@@ -63,13 +63,14 @@ export function expandWhatsAppIdentifiers(identifier, sessionDir) {
   return resolved;
 }
 
-export function matchesAllowedSender(senderId, senderPn, allowedUsers, sessionDir) {
+export function matchesAllowedSender(senderId, senderAltId, allowedUsers, sessionDir) {
   // WhatsApp Multi-Device can expose a first-contact sender as an opaque LID
   // before it persists LID mapping files. Baileys supplies the same sender's
-  // authenticated phone JID separately in msg.key.senderPn, so consult it
-  // as an additional alias without changing the allowlist itself.
+  // phone JID separately (key.remoteJidAlt for DMs, key.participantAlt in
+  // groups), so consult it as an additional alias without changing the
+  // allowlist itself (#63415, #72529).
   return matchesAllowedUser(senderId, allowedUsers, sessionDir)
-    || matchesAllowedUser(senderPn, allowedUsers, sessionDir);
+    || matchesAllowedUser(senderAltId, allowedUsers, sessionDir);
 }
 
 export function matchesAllowedUser(senderId, allowedUsers, sessionDir) {
diff --git a/scripts/whatsapp-bridge/allowlist.test.mjs b/scripts/whatsapp-bridge/allowlist.test.mjs
index 42fde36804..bac652fedf 100644
--- a/scripts/whatsapp-bridge/allowlist.test.mjs
+++ b/scripts/whatsapp-bridge/allowlist.test.mjs
@@ -100,3 +100,49 @@ test('matchesAllowedUser rejects everyone when allowlist is empty (#8389)', () =
     rmSync(sessionDir, { recursive: true, force: true });
   }
 });
+
+test('matchesAllowedSender falls back to participantAlt when no lid mapping exists (#72529)', () => {
+  // Baileys v7 group messages arrive with key.participant in LID form and
+  // the phone number only in key.participantAlt. A fresh bot session has no
+  // lid-mapping-*.json files, so the LID alone can never match a phone
+  // allowlist — the alt identifier must be consulted as a fallback.
+  const sessionDir = mkdtempSync(path.join(os.tmpdir(), 'hermes-wa-allowlist-'));
+
+  try {
+    const allowedUsers = parseAllowedUsers('+19175395595');
+
+    // No mapping file: LID by itself is rejected today (the #72529 drop)…
+    assert.equal(matchesAllowedUser('267383306489914@lid', allowedUsers, sessionDir), false);
+    // …but the alt phone identifier rescues the match.
+    assert.equal(
+      matchesAllowedSender('267383306489914@lid', '19175395595@s.whatsapp.net', allowedUsers, sessionDir),
+      true
+    );
+
+    // A stranger's LID with a non-allowlisted alt stays rejected.
+    assert.equal(
+      matchesAllowedSender('188012763865257@lid', '15550001111@s.whatsapp.net', allowedUsers, sessionDir),
+      false
+    );
+
+    // Missing / empty alt keeps the existing behaviour.
+    assert.equal(matchesAllowedSender('267383306489914@lid', '', allowedUsers, sessionDir), false);
+    assert.equal(matchesAllowedSender('267383306489914@lid', undefined, allowedUsers, sessionDir), false);
+  } finally {
+    rmSync(sessionDir, { recursive: true, force: true });
+  }
+});
+
+test('matchesAllowedSender still resolves via lid-mapping files without an alt', () => {
+  const sessionDir = mkdtempSync(path.join(os.tmpdir(), 'hermes-wa-allowlist-'));
+
+  try {
+    writeFileSync(path.join(sessionDir, 'lid-mapping-19175395595.json'), JSON.stringify('267383306489914'));
+    writeFileSync(path.join(sessionDir, 'lid-mapping-267383306489914_reverse.json'), JSON.stringify('19175395595'));
+
+    const allowedUsers = parseAllowedUsers('+19175395595');
+    assert.equal(matchesAllowedSender('267383306489914@lid', '', allowedUsers, sessionDir), true);
+  } finally {
+    rmSync(sessionDir, { recursive: true, force: true });
+  }
+});
diff --git a/scripts/whatsapp-bridge/bridge.js b/scripts/whatsapp-bridge/bridge.js
index 830247f10d..74718afd59 100644
--- a/scripts/whatsapp-bridge/bridge.js
+++ b/scripts/whatsapp-bridge/bridge.js
@@ -525,8 +525,12 @@ async function startSocket() {
 
       const chatId = msg.key.remoteJid;
       const senderId = msg.key.participant || chatId;
-      const senderPn = msg.key.senderPn || '';
-      const resolvedSenderId = senderPn || senderId;
+      // Baileys v7 carries the other form of the sender here (group: key.participantAlt,
+      // DM: key.remoteJidAlt). A LID sender's phone twin makes a phone allowlist match with no
+      // lid-mapping file yet (#63415, #72529) and is the identity Python sees, so first
+      // contacts key the same session they will once the mapping exists.
+      const senderAltId = normalizeWhatsAppId(msg.key.participantAlt || msg.key.remoteJidAlt || '');
+      const resolvedSenderId = senderAltId.endsWith('@s.whatsapp.net') ? senderAltId : senderId;
       const isGroup = chatId.endsWith('@g.us');
       const senderNumber = resolvedSenderId.replace(/@.*/, '');
       emitDebugEvent({
@@ -629,13 +633,14 @@ async function startSocket() {
           } catch {}
           continue;
         }
-        if (WHATSAPP_DM_POLICY !== 'pairing' && !matchesAllowedSender(senderId, senderPn, ALLOWED_USERS, SESSION_DIR)) {
+        if (WHATSAPP_DM_POLICY !== 'pairing' && !matchesAllowedSender(senderId, senderAltId, ALLOWED_USERS, SESSION_DIR)) {
           try {
             console.log(JSON.stringify({
               event: 'ignored',
               reason: 'allowlist_mismatch',
               chatId,
               senderId,
+              senderAltId,
             }));
           } catch {}
           continue;

From 81fd9dc77356e7ab087920e0fd16d2fc9e43159b Mon Sep 17 00:00:00 2001
From: Waldo <waldo@minicat.local>
Date: Fri, 24 Jul 2026 02:58:02 +0200
Subject: [PATCH 164/190] fix(whatsapp): honor group ingress policy in bridge

Use the configured group policy and group-JID allowlist at Node bridge intake instead of applying the DM sender allowlist to group participants.

Co-authored-by: Martin Gontovnikas <m@gon.to>
---
 scripts/whatsapp-bridge/allowlist.js       | 15 +++++++++++++++
 scripts/whatsapp-bridge/allowlist.test.mjs | 22 ++++++++++++++++++++++
 scripts/whatsapp-bridge/bridge.js          | 19 ++++++++++++++++---
 3 files changed, 53 insertions(+), 3 deletions(-)

diff --git a/scripts/whatsapp-bridge/allowlist.js b/scripts/whatsapp-bridge/allowlist.js
index 9b02507420..67aa03ce84 100644
--- a/scripts/whatsapp-bridge/allowlist.js
+++ b/scripts/whatsapp-bridge/allowlist.js
@@ -73,6 +73,21 @@ export function matchesAllowedSender(senderId, senderAltId, allowedUsers, sessio
     || matchesAllowedUser(senderAltId, allowedUsers, sessionDir);
 }
 
+export function matchesInboundWhatsAppGroup({
+  chatId,
+  groupPolicy,
+  groupAllowedUsers,
+  sessionDir,
+}) {
+  if (groupPolicy === 'disabled' || groupPolicy === 'pairing') {
+    return false;
+  }
+  if (groupPolicy === 'allowlist') {
+    return matchesAllowedUser(chatId, groupAllowedUsers, sessionDir);
+  }
+  return groupPolicy === 'open';
+}
+
 export function matchesAllowedUser(senderId, allowedUsers, sessionDir) {
   // Empty allowlist = NO ONE allowed (secure default, #8389).  Operators
   // who want an open bot must set ``WHATSAPP_ALLOWED_USERS=*`` explicitly.
diff --git a/scripts/whatsapp-bridge/allowlist.test.mjs b/scripts/whatsapp-bridge/allowlist.test.mjs
index bac652fedf..daa85cb740 100644
--- a/scripts/whatsapp-bridge/allowlist.test.mjs
+++ b/scripts/whatsapp-bridge/allowlist.test.mjs
@@ -7,6 +7,7 @@ import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import {
   expandWhatsAppIdentifiers,
   matchesAllowedSender,
+  matchesInboundWhatsAppGroup,
   matchesAllowedUser,
   normalizeWhatsAppIdentifier,
   parseAllowedUsers,
@@ -80,6 +81,27 @@ test('matchesAllowedUser treats * as allow-all wildcard', () => {
   }
 });
 
+test('group intake follows group policy and group-JID allowlist independently of DM users', () => {
+  const sessionDir = mkdtempSync(path.join(os.tmpdir(), 'hermes-wa-allowlist-'));
+
+  try {
+    const groupAllowedUsers = parseAllowedUsers('120363001234567890@g.us');
+    const base = {
+      chatId: '120363001234567890@g.us',
+      groupAllowedUsers,
+      sessionDir,
+    };
+
+    assert.equal(matchesInboundWhatsAppGroup({ ...base, groupPolicy: 'allowlist' }), true);
+    assert.equal(matchesInboundWhatsAppGroup({ ...base, chatId: 'other@g.us', groupPolicy: 'allowlist' }), false);
+    assert.equal(matchesInboundWhatsAppGroup({ ...base, chatId: 'other@g.us', groupPolicy: 'open' }), true);
+    assert.equal(matchesInboundWhatsAppGroup({ ...base, groupPolicy: 'disabled' }), false);
+    assert.equal(matchesInboundWhatsAppGroup({ ...base, groupPolicy: 'pairing' }), false);
+  } finally {
+    rmSync(sessionDir, { recursive: true, force: true });
+  }
+});
+
 test('matchesAllowedUser rejects everyone when allowlist is empty (#8389)', () => {
   // Regression guard: empty allowlist used to return true (allow-everyone),
   // which let any stranger DM the bridge and trigger a Python-side
diff --git a/scripts/whatsapp-bridge/bridge.js b/scripts/whatsapp-bridge/bridge.js
index 74718afd59..26489896e2 100644
--- a/scripts/whatsapp-bridge/bridge.js
+++ b/scripts/whatsapp-bridge/bridge.js
@@ -30,7 +30,7 @@ import { randomBytes, createHash } from 'crypto';
 import { execFileSync } from 'child_process';
 import { tmpdir } from 'os';
 import qrcode from 'qrcode-terminal';
-import { matchesAllowedSender, matchesAllowedUser, parseAllowedUsers } from './allowlist.js';
+import { matchesAllowedSender, matchesAllowedUser, matchesInboundWhatsAppGroup, parseAllowedUsers } from './allowlist.js';
 import { createOutboundIdTracker } from './outbound_ids.js';
 import { classifyOwnerMessageGate } from './owner_message_gate.js';
 import {
@@ -116,7 +116,11 @@ const PAIR_ONLY = args.includes('--pair-only');
 const PAIR_JSON = args.includes('--pair-json');
 const WHATSAPP_MODE = getArg('mode', process.env.WHATSAPP_MODE || 'self-chat'); // "bot" or "self-chat"
 const WHATSAPP_DM_POLICY = String(process.env.WHATSAPP_DM_POLICY || 'open').trim().toLowerCase();
+const WHATSAPP_GROUP_POLICY = String(process.env.WHATSAPP_GROUP_POLICY || 'pairing').trim().toLowerCase();
 const ALLOWED_USERS = parseAllowedUsers(process.env.WHATSAPP_ALLOWED_USERS || '');
+// Group authorization is by group JID, not by every participant's JID.  The
+// Python adapter still applies group policy and mention rules after intake.
+const GROUP_ALLOWED_USERS = parseAllowedUsers(process.env.WHATSAPP_GROUP_ALLOWED_USERS || '');
 const DEFAULT_REPLY_PREFIX = '☤ *Hermes Agent*\n────────────\n';
 const REPLY_PREFIX = process.env.WHATSAPP_REPLY_PREFIX === undefined
   ? DEFAULT_REPLY_PREFIX
@@ -633,11 +637,20 @@ async function startSocket() {
           } catch {}
           continue;
         }
-        if (WHATSAPP_DM_POLICY !== 'pairing' && !matchesAllowedSender(senderId, senderAltId, ALLOWED_USERS, SESSION_DIR)) {
+        const intakeAllowed = isGroup
+          ? matchesInboundWhatsAppGroup({
+              chatId,
+              groupPolicy: WHATSAPP_GROUP_POLICY,
+              groupAllowedUsers: GROUP_ALLOWED_USERS,
+              sessionDir: SESSION_DIR,
+            })
+          : WHATSAPP_DM_POLICY === 'pairing'
+            || matchesAllowedSender(senderId, senderAltId, ALLOWED_USERS, SESSION_DIR);
+        if (!intakeAllowed) {
           try {
             console.log(JSON.stringify({
               event: 'ignored',
-              reason: 'allowlist_mismatch',
+              reason: isGroup ? 'group_policy_rejected' : 'allowlist_mismatch',
               chatId,
               senderId,
               senderAltId,

From 477afd24209e8411a825908a081e7546d4d1f789 Mon Sep 17 00:00:00 2001
From: sal <salch-cred@users.noreply.github.com>
Date: Mon, 14 Sep 2026 23:21:00 +0530
Subject: [PATCH 165/190] fix(whatsapp): adapter reads
 WHATSAPP_GROUP_ALLOWED_USERS for the group allowlist (#72529)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Node bridge receives WHATSAPP_GROUP_ALLOWED_USERS via
_BRIDGE_PASSTHROUGH_ENV and the YAML bridge maps config.yaml
whatsapp.group_allow_from onto the same env carrier, but
WhatsAppAdapter.__init__ seeded _group_allow_from from config.extra
alone — an install that set the group allowlist only through the
documented env var silently ran group gating with an empty allowlist:
with group_policy=allowlist every group chat was rejected at intake
(the second failure mode triaged on #72529, the half with 'no PR yet').

Mirror the DM path's precedence: config keys win by key presence
(explicit empty list stays authoritative), then the profile-scoped
WHATSAPP_GROUP_ALLOW_FROM / WHATSAPP_GROUP_ALLOWED_USERS env CSV —
multiplex-safe through _wenv, like every other WHATSAPP_* read.

Tests pin the full precedence matrix: env-only seeding, the
allow_from-style alias, config-wins-over-env, the legacy groupAllowFrom
key, empty-by-default, the scoped .env read under multiplex, and the
group-policy gating outcome for an env-seeded allowlist.
---
 plugins/platforms/whatsapp/adapter.py         | 10 +-
 .../test_whatsapp_group_allowlist_env.py      | 99 +++++++++++++++++++
 2 files changed, 108 insertions(+), 1 deletion(-)
 create mode 100644 tests/gateway/test_whatsapp_group_allowlist_env.py

diff --git a/plugins/platforms/whatsapp/adapter.py b/plugins/platforms/whatsapp/adapter.py
index 81185b4663..eec8836de4 100644
--- a/plugins/platforms/whatsapp/adapter.py
+++ b/plugins/platforms/whatsapp/adapter.py
@@ -275,7 +275,15 @@ class WhatsAppAdapter(WhatsAppBehaviorMixin, BasePlatformAdapter):
         self._dm_policy = str(_extra_or_secret(extra, "dm_policy", "WHATSAPP_DM_POLICY", "pairing")).strip().lower()
         self._allow_from = self._coerce_allow_list(self._select_dm_allowlist(extra, ("WHATSAPP_ALLOWED_USERS",), _wenv))
         self._group_policy = str(_extra_or_secret(extra, "group_policy", "WHATSAPP_GROUP_POLICY", "pairing")).strip().lower()
-        self._group_allow_from = self._coerce_allow_list(extra.get("group_allow_from") or extra.get("groupAllowFrom"))
+        # Group allowlist: config keys win, then the profile-scoped env CSV — mirroring the DM
+        # path (_select_dm_allowlist) so a group_allow_from set only via WHATSAPP_GROUP_ALLOWED_USERS
+        # reaches the adapter (#72529: the env carrier was bridged to the Node bridge but never read here,
+        # so env-only installs silently ran group gating with an empty allowlist).
+        self._group_allow_from = self._coerce_allow_list(
+            extra.get("group_allow_from") if "group_allow_from" in extra
+            else (extra.get("groupAllowFrom") if "groupAllowFrom" in extra
+                  else (_wenv("WHATSAPP_GROUP_ALLOW_FROM") or _wenv("WHATSAPP_GROUP_ALLOWED_USERS") or None))
+        )
         rr = extra.get("send_read_receipts", False)
         self._send_read_receipts = rr if isinstance(rr, bool) else str(rr or "").strip().lower() in {"1", "true", "yes", "on"}
         self._mention_patterns = self._compile_mention_patterns()
diff --git a/tests/gateway/test_whatsapp_group_allowlist_env.py b/tests/gateway/test_whatsapp_group_allowlist_env.py
new file mode 100644
index 0000000000..6f27e9f373
--- /dev/null
+++ b/tests/gateway/test_whatsapp_group_allowlist_env.py
@@ -0,0 +1,99 @@
+"""Regression test for #72529 — the WhatsApp adapter never read WHATSAPP_GROUP_ALLOWED_USERS.
+
+The Node bridge receives WHATSAPP_GROUP_ALLOWED_USERS via _BRIDGE_PASSTHROUGH_ENV, and the
+YAML bridge maps config.yaml ``whatsapp.group_allow_from`` onto the same env carrier — but
+``WhatsAppAdapter.__init__`` seeded ``_group_allow_from`` from ``extra`` alone. An install
+that configured the group allowlist only through the documented env var (or relied on the
+YAML bridge to populate it) silently ran group gating with an empty allowlist: with
+``group_policy: allowlist`` every group message was rejected, and with ``group_policy: open``
+nothing changed — the triage on #72529 flagged exactly this half as "no PR yet".
+
+The DM path already had the right shape (``_select_dm_allowlist`` reads config by key
+*presence*, then the scoped env). This test pins the group path to the same precedence:
+
+1. ``extra["group_allow_from"]`` (explicit list or CSV) wins, even when empty-ish forms differ;
+2. the legacy ``groupAllowFrom`` key follows;
+3. with neither config key present, WHATSAPP_GROUP_ALLOW_FROM / WHATSAPP_GROUP_ALLOWED_USERS
+   (profile-scoped, multiplex-safe) seed the allowlist;
+4. config wins over env — an env value must never broaden a config-seeded list.
+"""
+from unittest.mock import patch
+
+import pytest
+
+from gateway.config import Platform, PlatformConfig
+
+
+def _adapter_with_extra(extra):
+    from plugins.platforms.whatsapp.adapter import WhatsAppAdapter
+    return WhatsAppAdapter(PlatformConfig(enabled=True, extra=extra))
+
+
+class TestGroupAllowlistEnvFallback:
+    """Env-only group allowlists must reach ``_group_allow_from``."""
+
+    def test_env_only_group_allowlist_is_read(self, monkeypatch):
+        monkeypatch.setenv("WHATSAPP_GROUP_ALLOWED_USERS", "120363001234567890@g.us, 86316009876@s.whatsapp.net")
+        monkeypatch.delenv("WHATSAPP_GROUP_ALLOW_FROM", raising=False)
+        adapter = _adapter_with_extra({})
+        assert adapter._group_allow_from == {"120363001234567890@g.us", "86316009876@s.whatsapp.net"}
+
+    def test_group_allow_from_env_alias(self, monkeypatch):
+        """WHATSAPP_GROUP_ALLOW_FROM (the allow_from-style spelling) is honoured too."""
+        monkeypatch.setenv("WHATSAPP_GROUP_ALLOW_FROM", "86316009876@s.whatsapp.net")
+        monkeypatch.delenv("WHATSAPP_GROUP_ALLOWED_USERS", raising=False)
+        adapter = _adapter_with_extra({})
+        assert adapter._group_allow_from == {"86316009876@s.whatsapp.net"}
+
+    def test_config_group_allow_from_still_wins(self, monkeypatch):
+        """An explicit config list stays authoritative — the env value must not broaden it."""
+        monkeypatch.setenv("WHATSAPP_GROUP_ALLOWED_USERS", "1111111111@g.us")
+        adapter = _adapter_with_extra({"group_allow_from": ["120363001234567890@g.us"]})
+        assert adapter._group_allow_from == {"120363001234567890@g.us"}
+
+    def test_legacy_group_allow_from_key_wins_over_env(self, monkeypatch):
+        monkeypatch.setenv("WHATSAPP_GROUP_ALLOWED_USERS", "1111111111@g.us")
+        adapter = _adapter_with_extra({"groupAllowFrom": ["86316009876@s.whatsapp.net"]})
+        assert adapter._group_allow_from == {"86316009876@s.whatsapp.net"}
+
+    def test_empty_env_and_no_config_means_empty_allowlist(self, monkeypatch):
+        monkeypatch.delenv("WHATSAPP_GROUP_ALLOWED_USERS", raising=False)
+        monkeypatch.delenv("WHATSAPP_GROUP_ALLOW_FROM", raising=False)
+        adapter = _adapter_with_extra({})
+        assert adapter._group_allow_from == set()
+
+    def test_scoped_env_read_through_secret_scope(self, tmp_path, monkeypatch):
+        """The env read is profile-scoped (multiplex-safe) like every other WHATSAPP_* read."""
+        from agent import secret_scope as ss
+
+        (tmp_path / ".env").write_text("WHATSAPP_GROUP_ALLOWED_USERS=86316009876@s.whatsapp.net\n")
+        monkeypatch.delenv("WHATSAPP_GROUP_ALLOWED_USERS", raising=False)
+        monkeypatch.delenv("WHATSAPP_GROUP_ALLOW_FROM", raising=False)
+
+        ss.set_multiplex_active(True)
+        tok = ss.set_secret_scope(ss.build_profile_secret_scope(tmp_path))
+        try:
+            adapter = _adapter_with_extra({})
+            assert adapter._group_allow_from == {"86316009876@s.whatsapp.net"}
+        finally:
+            ss.reset_secret_scope(tok)
+            ss.set_multiplex_active(False)
+
+
+class TestGroupGatingUsesEnvSeededAllowlist:
+    """#72529's symptom: authorized group senders rejected because the allowlist was empty."""
+
+    def test_allowlisted_group_chat_passes_intake(self, monkeypatch):
+        """group_policy=allowlist + env-only allowlist → the group chat is admitted."""
+        monkeypatch.setenv("WHATSAPP_GROUP_ALLOWED_USERS", "120363001234567890@g.us")
+        monkeypatch.setenv("WHATSAPP_GROUP_POLICY", "allowlist")
+        adapter = _adapter_with_extra({})
+        assert adapter._group_policy == "allowlist"
+        assert adapter._is_group_allowed("120363001234567890@g.us") is True
+        assert adapter._is_group_allowed("99999999999@g.us") is False
+
+    def test_open_group_policy_unaffected(self, monkeypatch):
+        monkeypatch.setenv("WHATSAPP_GROUP_POLICY", "open")
+        monkeypatch.delenv("WHATSAPP_GROUP_ALLOWED_USERS", raising=False)
+        adapter = _adapter_with_extra({})
+        assert adapter._is_group_allowed("120363001234567890@g.us") is True

From 35b38f1f4ed5516782212c3940a7c6a407f3fa75 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 02:56:28 +0530
Subject: [PATCH 166/190] fix(whatsapp): bridge gets the adapter's resolved
 group policy and group allowlist; one allowlist reader
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The bridge now gates groups by WHATSAPP_GROUP_POLICY / WHATSAPP_GROUP_ALLOWED_USERS
(#73465), but only the DM policy and DM allowlist were exported from the adapter's
resolved config — a YAML group_allow_from never reached the bridge and, under a
multiplexed gateway, the launch process's WHATSAPP_GROUP_* values did. _bridge_env
exports both like it already did for the DM pair, so unlisted-group traffic is cut
before media download instead of after the POST to Python.

whatsapp_common._select_allowlist generalises the DM precedence reader (config key
presence wins, an explicit empty list stays authoritative, then the first truthy env
carrier); the adapter's group list and the Cloud sibling's group list use it instead
of hand-rolled `or` chains, so `group_allow_from: []` means the same everywhere.

Tests: bridge env carries group policy + group allowlist from the secondary profile's
YAML (scoped precedence file); env fallback test trimmed to the two invariants (red on
the merge base); bare test adapters seed _group_policy/_group_allow_from, which
_bridge_env now reads.
---
 gateway/platforms/whatsapp_cloud.py           |  6 +-
 gateway/platforms/whatsapp_common.py          | 30 +++---
 plugins/platforms/whatsapp/adapter.py         | 25 +++--
 ...test_adapter_settings_scoped_precedence.py | 24 +++--
 tests/gateway/test_whatsapp_connect.py        |  8 +-
 .../test_whatsapp_group_allowlist_env.py      | 92 ++++---------------
 tests/gateway/test_whatsapp_stale_bridge.py   | 12 +--
 7 files changed, 73 insertions(+), 124 deletions(-)

diff --git a/gateway/platforms/whatsapp_cloud.py b/gateway/platforms/whatsapp_cloud.py
index a409f009bf..96e3871efe 100644
--- a/gateway/platforms/whatsapp_cloud.py
+++ b/gateway/platforms/whatsapp_cloud.py
@@ -197,9 +197,9 @@ class WhatsAppCloudAdapter(WhatsAppBehaviorMixin, BasePlatformAdapter):
             extra.get("group_policy") or _get_wsecret("WHATSAPP_CLOUD_GROUP_POLICY")
             or _get_wsecret("WHATSAPP_GROUP_POLICY", default="open") or "open"
         ).strip().lower()
-        self._group_allow_from: set[str] = self._normalize_allow_ids(self._coerce_allow_list(
-            extra.get("group_allow_from") or extra.get("groupAllowFrom") or _get_wsecret("WHATSAPP_CLOUD_GROUP_ALLOW_FROM")
-        ))
+        _, raw_groups = self._select_allowlist(
+            extra, ("group_allow_from", "groupAllowFrom"), ("WHATSAPP_CLOUD_GROUP_ALLOW_FROM",), _get_wsecret)
+        self._group_allow_from: set[str] = self._normalize_allow_ids(self._coerce_allow_list(raw_groups))
         self._mention_patterns = self._compile_mention_patterns()
         # Webhook dedup state (in-memory, FIFO-evicted) and counters.
         self._seen_wamids: "OrderedDict[str, bool]" = OrderedDict()
diff --git a/gateway/platforms/whatsapp_common.py b/gateway/platforms/whatsapp_common.py
index 5e5645f20d..228cb530f8 100644
--- a/gateway/platforms/whatsapp_common.py
+++ b/gateway/platforms/whatsapp_common.py
@@ -5,7 +5,7 @@ to-bot detection, broadcast filtering, WhatsApp markdown conversion, chunk budge
 
 Mixin contract — the host adapter sets these on ``self`` before calling any mixin
 method: ``config`` (PlatformConfig), ``name``, ``_dm_policy`` / ``_group_policy``
-("open" | "allowlist" | "disabled"), ``_allow_from`` / ``_group_allow_from`` (set[str]),
+("open" | "allowlist" | "disabled" | "pairing"), ``_allow_from`` / ``_group_allow_from`` (set[str]),
 ``_mention_patterns`` (list[re.Pattern]), ``_reply_prefix`` (Optional[str]).
 """
 
@@ -105,20 +105,24 @@ class WhatsAppBehaviorMixin(OwnAccessPolicyMixin):
         parts = raw if isinstance(raw, list) else str(raw).split(",")
         return {str(part).strip() for part in parts if str(part).strip()}
 
-    def _select_dm_allowlist(self, extra: Dict[str, Any], env_keys, read_env) -> Any:
-        """Pick the raw DM allowlist by key *presence*: ``allow_from``/``allowFrom`` in config (an
-        explicit empty list stays authoritative), then the first truthy env carrier. Records the
-        winning source in ``_dm_allowlist_source`` so live DM checks keep the same precedence."""
-        for key in ("allow_from", "allowFrom"):
+    @staticmethod
+    def _select_allowlist(extra: Dict[str, Any], config_keys, env_keys, read_env) -> tuple[Optional[str], Any]:
+        """``(source, raw)`` by key *presence*: a config key wins (an explicit empty list stays authoritative),
+        then the first truthy env carrier; ``(None, None)`` when neither is set."""
+        for key in config_keys:
             if key in extra:
-                self._dm_allowlist_source = "config"
-                return extra.get(key)
+                return "config", extra.get(key)
         for env in env_keys:
-            if read_env(env):
-                self._dm_allowlist_source = env
-                return read_env(env)
-        self._dm_allowlist_source = None
-        return None
+            raw = read_env(env)
+            if raw:
+                return env, raw
+        return None, None
+
+    def _select_dm_allowlist(self, extra: Dict[str, Any], env_keys, read_env) -> Any:
+        """Raw DM allowlist; records the winning source in ``_dm_allowlist_source`` so live DM checks keep
+        the same precedence."""
+        self._dm_allowlist_source, raw = self._select_allowlist(extra, ("allow_from", "allowFrom"), env_keys, read_env)
+        return raw
 
     def _live_dm_allow_from(self) -> set[str]:
         """Allowlist currently enforced for DM intake / strict DM auth. Env-seeded adapters re-read
diff --git a/plugins/platforms/whatsapp/adapter.py b/plugins/platforms/whatsapp/adapter.py
index eec8836de4..2e729fd29b 100644
--- a/plugins/platforms/whatsapp/adapter.py
+++ b/plugins/platforms/whatsapp/adapter.py
@@ -275,15 +275,11 @@ class WhatsAppAdapter(WhatsAppBehaviorMixin, BasePlatformAdapter):
         self._dm_policy = str(_extra_or_secret(extra, "dm_policy", "WHATSAPP_DM_POLICY", "pairing")).strip().lower()
         self._allow_from = self._coerce_allow_list(self._select_dm_allowlist(extra, ("WHATSAPP_ALLOWED_USERS",), _wenv))
         self._group_policy = str(_extra_or_secret(extra, "group_policy", "WHATSAPP_GROUP_POLICY", "pairing")).strip().lower()
-        # Group allowlist: config keys win, then the profile-scoped env CSV — mirroring the DM
-        # path (_select_dm_allowlist) so a group_allow_from set only via WHATSAPP_GROUP_ALLOWED_USERS
-        # reaches the adapter (#72529: the env carrier was bridged to the Node bridge but never read here,
-        # so env-only installs silently ran group gating with an empty allowlist).
-        self._group_allow_from = self._coerce_allow_list(
-            extra.get("group_allow_from") if "group_allow_from" in extra
-            else (extra.get("groupAllowFrom") if "groupAllowFrom" in extra
-                  else (_wenv("WHATSAPP_GROUP_ALLOW_FROM") or _wenv("WHATSAPP_GROUP_ALLOWED_USERS") or None))
-        )
+        # Same precedence as the DM list. Until #72529 the env carrier only reached the Node bridge, so
+        # env-only installs gated groups on an empty allowlist.
+        _, raw_groups = self._select_allowlist(
+            extra, ("group_allow_from", "groupAllowFrom"), ("WHATSAPP_GROUP_ALLOW_FROM", "WHATSAPP_GROUP_ALLOWED_USERS"), _wenv)
+        self._group_allow_from = self._coerce_allow_list(raw_groups)
         rr = extra.get("send_read_receipts", False)
         self._send_read_receipts = rr if isinstance(rr, bool) else str(rr or "").strip().lower() in {"1", "true", "yes", "on"}
         self._mention_patterns = self._compile_mention_patterns()
@@ -400,11 +396,12 @@ class WhatsAppAdapter(WhatsAppBehaviorMixin, BasePlatformAdapter):
         # adapter resolved (scoped env → this profile's YAML → default), or a secondary's YAML
         # ``dm_policy: pairing`` runs under the default profile's allowlist and drops valid pairing DMs.
         bridge_env["WHATSAPP_DM_POLICY"] = self._dm_policy
-        allowed = ",".join(sorted(self._allow_from))
-        if allowed:
-            bridge_env["WHATSAPP_ALLOWED_USERS"] = allowed
-        else:
-            bridge_env.pop("WHATSAPP_ALLOWED_USERS", None)
+        bridge_env["WHATSAPP_GROUP_POLICY"] = self._group_policy
+        for env_key, ids in (("WHATSAPP_ALLOWED_USERS", self._allow_from), ("WHATSAPP_GROUP_ALLOWED_USERS", self._group_allow_from)):
+            if ids:
+                bridge_env[env_key] = ",".join(sorted(ids))
+            else:
+                bridge_env.pop(env_key, None)
         # Without these the bridge hardcodes ~/.hermes/{image,audio,document}_cache (wrong under HERMES_HOME/profiles/cache layout).
         img_dir, audio_dir, _video_dir, doc_dir = _cache_dirs()
         bridge_env.update(HERMES_IMAGE_CACHE_DIR=str(img_dir), HERMES_AUDIO_CACHE_DIR=str(audio_dir), HERMES_DOCUMENT_CACHE_DIR=str(doc_dir))
diff --git a/tests/gateway/test_adapter_settings_scoped_precedence.py b/tests/gateway/test_adapter_settings_scoped_precedence.py
index 791735e13c..f4bd0d454f 100644
--- a/tests/gateway/test_adapter_settings_scoped_precedence.py
+++ b/tests/gateway/test_adapter_settings_scoped_precedence.py
@@ -69,13 +69,13 @@ def test_secondary_reads_own_yaml_and_never_the_launch_env(homes, monkeypatch):
         "matrix:\n  process_notices: true\n  session_scope: room\n"
         "discord:\n  reactions: false\n  allow_mentions:\n    everyone: true\n"
         "slack:\n  reactions: false\n  ignored_channels: [C_LAUNCH]\n"
-        "telegram:\n  reactions: true\n")
+        "telegram:\n  reactions: true\n", encoding="utf-8")
     load_gateway_config()  # launch profile bridges its YAML into os.environ (single-profile contract)
     (secondary / "config.yaml").write_text(
         "matrix:\n  enabled: true\n  user_id: '@bot:example.org'\n"
         "  allowed_users: ['@owner:example.org']\n  ignore_user_patterns: ['^@ignored:']\n"
         "discord:\n  enabled: true\nslack:\n  enabled: true\n"
-        "telegram:\n  enabled: true\n  proxy_url: http://127.0.0.1:18080\n")
+        "telegram:\n  enabled: true\n  proxy_url: http://127.0.0.1:18080\n", encoding="utf-8")
     from plugins.platforms.discord.adapter import DiscordAdapter
     from plugins.platforms.matrix.adapter import MatrixAdapter
     from plugins.platforms.slack.adapter import SlackAdapter
@@ -107,7 +107,7 @@ def test_explicit_env_beats_yaml_for_the_owning_profile(homes, monkeypatch):
     ``everyone: true`` and TELEGRAM_REACTIONS=true beats the stock ``reactions: false`` (#109032)."""
     launch, _ = homes
     (launch / "config.yaml").write_text(
-        "discord:\n  allow_mentions:\n    everyone: true\ntelegram:\n  reactions: false\n")
+        "discord:\n  allow_mentions:\n    everyone: true\ntelegram:\n  reactions: false\n", encoding="utf-8")
     monkeypatch.setenv("DISCORD_ALLOW_MENTION_EVERYONE", "false")
     monkeypatch.setenv("TELEGRAM_REACTIONS", "true")
     from plugins.platforms.telegram.adapter import TelegramAdapter
@@ -123,7 +123,7 @@ def test_central_allow_bots_gate_honours_a_secondary_yaml_policy(homes):
     from plugins.platforms.slack.adapter import SlackAdapter
     _, secondary = homes
     (secondary / "config.yaml").write_text(
-        "discord:\n  enabled: true\n  allow_bots: all\nslack:\n  enabled: true\n  allow_bots: all\n")
+        "discord:\n  enabled: true\n  allow_bots: all\nslack:\n  enabled: true\n  allow_bots: all\n", encoding="utf-8")
     with _secondary_scope(secondary):
         cfg = load_gateway_config()
         d, s = DiscordAdapter(cfg.platforms[Platform.DISCORD]), SlackAdapter(cfg.platforms[Platform.SLACK])
@@ -141,7 +141,7 @@ def test_matrix_yaml_lists_gate_intake_and_approval(homes):
     _, secondary = homes
     (secondary / "config.yaml").write_text(
         "matrix:\n  enabled: true\n  user_id: '@bot:example.org'\n"
-        "  allowed_users: ['@owner:example.org']\n  ignore_user_patterns: ['^@ignored:']\n")
+        "  allowed_users: ['@owner:example.org']\n  ignore_user_patterns: ['^@ignored:']\n", encoding="utf-8")
     with _secondary_scope(secondary):
         a = MatrixAdapter(load_gateway_config().platforms[Platform.MATRIX])
         a._user_id = "@bot:example.org"
@@ -164,7 +164,7 @@ def test_yuanbao_secondary_home_channel_is_live_and_reloadable(homes):
     from gateway.platforms.yuanbao import AutoSetHomeMiddleware
     _, secondary = homes
     (secondary / "config.yaml").write_text(
-        "platforms:\n  yuanbao:\n    enabled: true\n    extra:\n      app_id: a\n      app_secret: b\n")
+        "platforms:\n  yuanbao:\n    enabled: true\n    extra:\n      app_id: a\n      app_secret: b\n", encoding="utf-8")
     adapter = types.SimpleNamespace(name="yuanbao-b2")
     ctx = types.SimpleNamespace(chat_id="dm:tenant-b2", chat_name="b2")
     with _secondary_scope(secondary):
@@ -177,15 +177,21 @@ def test_yuanbao_secondary_home_channel_is_live_and_reloadable(homes):
 
 
 def test_whatsapp_bridge_env_carries_the_secondary_effective_policy(homes, monkeypatch):
-    """bridge.js gates DMs before Python: it must receive the adapter's resolved dm_policy/allow_from, not the
-    launch process's WHATSAPP_* values."""
+    """bridge.js gates DMs and group intake before Python: it must receive the adapter's resolved
+    dm_policy/allow_from/group_policy, not the launch process's WHATSAPP_* values."""
     from plugins.platforms.whatsapp.adapter import WhatsAppAdapter
     _, secondary = homes
     monkeypatch.setenv("WHATSAPP_DM_POLICY", "allowlist")
+    monkeypatch.setenv("WHATSAPP_GROUP_POLICY", "disabled")
     monkeypatch.setenv("WHATSAPP_ALLOWED_USERS", "15550001111")
-    (secondary / "config.yaml").write_text("whatsapp:\n  enabled: true\n  dm_policy: pairing\n")
+    monkeypatch.setenv("WHATSAPP_GROUP_ALLOWED_USERS", "120363000000000000@g.us")
+    (secondary / "config.yaml").write_text(
+        "whatsapp:\n  enabled: true\n  dm_policy: pairing\n  group_policy: allowlist\n"
+        "  group_allow_from: [120363001234567890@g.us]\n", encoding="utf-8")
     with _secondary_scope(secondary):
         a = WhatsAppAdapter(load_gateway_config().platforms[Platform.WHATSAPP])
         env = a._bridge_env()
     assert a._dm_policy == "pairing" == env["WHATSAPP_DM_POLICY"]
+    assert a._group_policy == "allowlist" == env["WHATSAPP_GROUP_POLICY"]
+    assert env["WHATSAPP_GROUP_ALLOWED_USERS"] == "120363001234567890@g.us"
     assert "WHATSAPP_ALLOWED_USERS" not in env
diff --git a/tests/gateway/test_whatsapp_connect.py b/tests/gateway/test_whatsapp_connect.py
index 0e3bfe28e0..0e577bfd19 100644
--- a/tests/gateway/test_whatsapp_connect.py
+++ b/tests/gateway/test_whatsapp_connect.py
@@ -54,8 +54,8 @@ def _make_adapter():
     adapter._bridge_process = None
     adapter._reply_prefix = None
     adapter._send_read_receipts = False
-    adapter._dm_policy = "pairing"
-    adapter._allow_from = set()
+    adapter._dm_policy = adapter._group_policy = "pairing"
+    adapter._allow_from = adapter._group_allow_from = set()
     adapter._running = False
     adapter._message_handler = None
     adapter._fatal_error_code = None
@@ -514,11 +514,11 @@ class TestNoCredsPreflight:
         adapter.config = MagicMock()
         adapter._bridge_port = 19877
         bridge = tmp_path / "bridge.js"
-        bridge.write_text("// stub")
+        bridge.write_text("// stub", encoding="utf-8")
         adapter._bridge_script = str(bridge)
         session_dir = tmp_path / "session"
         session_dir.mkdir()
-        (session_dir / "creds.json").write_text("{}")
+        (session_dir / "creds.json").write_text("{}", encoding="utf-8")
         adapter._session_path = session_dir
         adapter._bridge_log_fh = None
         adapter._fatal_error_code = None
diff --git a/tests/gateway/test_whatsapp_group_allowlist_env.py b/tests/gateway/test_whatsapp_group_allowlist_env.py
index 6f27e9f373..33c54a9981 100644
--- a/tests/gateway/test_whatsapp_group_allowlist_env.py
+++ b/tests/gateway/test_whatsapp_group_allowlist_env.py
@@ -1,27 +1,12 @@
-"""Regression test for #72529 — the WhatsApp adapter never read WHATSAPP_GROUP_ALLOWED_USERS.
+"""Regression for #72529 — the WhatsApp adapter never read WHATSAPP_GROUP_ALLOWED_USERS.
 
-The Node bridge receives WHATSAPP_GROUP_ALLOWED_USERS via _BRIDGE_PASSTHROUGH_ENV, and the
-YAML bridge maps config.yaml ``whatsapp.group_allow_from`` onto the same env carrier — but
-``WhatsAppAdapter.__init__`` seeded ``_group_allow_from`` from ``extra`` alone. An install
-that configured the group allowlist only through the documented env var (or relied on the
-YAML bridge to populate it) silently ran group gating with an empty allowlist: with
-``group_policy: allowlist`` every group message was rejected, and with ``group_policy: open``
-nothing changed — the triage on #72529 flagged exactly this half as "no PR yet".
-
-The DM path already had the right shape (``_select_dm_allowlist`` reads config by key
-*presence*, then the scoped env). This test pins the group path to the same precedence:
-
-1. ``extra["group_allow_from"]`` (explicit list or CSV) wins, even when empty-ish forms differ;
-2. the legacy ``groupAllowFrom`` key follows;
-3. with neither config key present, WHATSAPP_GROUP_ALLOW_FROM / WHATSAPP_GROUP_ALLOWED_USERS
-   (profile-scoped, multiplex-safe) seed the allowlist;
-4. config wins over env — an env value must never broaden a config-seeded list.
+The Node bridge received the env carrier via _BRIDGE_PASSTHROUGH_ENV, but ``WhatsAppAdapter.__init__``
+seeded ``_group_allow_from`` from ``extra`` alone, so an env-only install ran ``group_policy: allowlist``
+against an empty allowlist and rejected every group. Precedence mirrors the DM path: config key presence
+wins, then the profile-scoped env.
 """
-from unittest.mock import patch
 
-import pytest
-
-from gateway.config import Platform, PlatformConfig
+from gateway.config import PlatformConfig
 
 
 def _adapter_with_extra(extra):
@@ -29,71 +14,28 @@ def _adapter_with_extra(extra):
     return WhatsAppAdapter(PlatformConfig(enabled=True, extra=extra))
 
 
-class TestGroupAllowlistEnvFallback:
-    """Env-only group allowlists must reach ``_group_allow_from``."""
-
-    def test_env_only_group_allowlist_is_read(self, monkeypatch):
-        monkeypatch.setenv("WHATSAPP_GROUP_ALLOWED_USERS", "120363001234567890@g.us, 86316009876@s.whatsapp.net")
-        monkeypatch.delenv("WHATSAPP_GROUP_ALLOW_FROM", raising=False)
-        adapter = _adapter_with_extra({})
-        assert adapter._group_allow_from == {"120363001234567890@g.us", "86316009876@s.whatsapp.net"}
-
-    def test_group_allow_from_env_alias(self, monkeypatch):
-        """WHATSAPP_GROUP_ALLOW_FROM (the allow_from-style spelling) is honoured too."""
-        monkeypatch.setenv("WHATSAPP_GROUP_ALLOW_FROM", "86316009876@s.whatsapp.net")
-        monkeypatch.delenv("WHATSAPP_GROUP_ALLOWED_USERS", raising=False)
-        adapter = _adapter_with_extra({})
-        assert adapter._group_allow_from == {"86316009876@s.whatsapp.net"}
-
-    def test_config_group_allow_from_still_wins(self, monkeypatch):
-        """An explicit config list stays authoritative — the env value must not broaden it."""
-        monkeypatch.setenv("WHATSAPP_GROUP_ALLOWED_USERS", "1111111111@g.us")
-        adapter = _adapter_with_extra({"group_allow_from": ["120363001234567890@g.us"]})
-        assert adapter._group_allow_from == {"120363001234567890@g.us"}
-
-    def test_legacy_group_allow_from_key_wins_over_env(self, monkeypatch):
-        monkeypatch.setenv("WHATSAPP_GROUP_ALLOWED_USERS", "1111111111@g.us")
-        adapter = _adapter_with_extra({"groupAllowFrom": ["86316009876@s.whatsapp.net"]})
-        assert adapter._group_allow_from == {"86316009876@s.whatsapp.net"}
-
-    def test_empty_env_and_no_config_means_empty_allowlist(self, monkeypatch):
-        monkeypatch.delenv("WHATSAPP_GROUP_ALLOWED_USERS", raising=False)
-        monkeypatch.delenv("WHATSAPP_GROUP_ALLOW_FROM", raising=False)
-        adapter = _adapter_with_extra({})
-        assert adapter._group_allow_from == set()
-
-    def test_scoped_env_read_through_secret_scope(self, tmp_path, monkeypatch):
-        """The env read is profile-scoped (multiplex-safe) like every other WHATSAPP_* read."""
+class TestGroupAllowlistEnv:
+    def test_env_only_group_allowlist_gates_intake_through_the_secret_scope(self, tmp_path, monkeypatch):
+        """No config key: the profile-scoped WHATSAPP_GROUP_ALLOWED_USERS seeds the allowlist ``_is_group_allowed``
+        reads (multiplex-safe like every other WHATSAPP_* read)."""
         from agent import secret_scope as ss
 
-        (tmp_path / ".env").write_text("WHATSAPP_GROUP_ALLOWED_USERS=86316009876@s.whatsapp.net\n")
+        (tmp_path / ".env").write_text("WHATSAPP_GROUP_ALLOWED_USERS=120363001234567890@g.us\nWHATSAPP_GROUP_POLICY=allowlist\n", encoding="utf-8")
         monkeypatch.delenv("WHATSAPP_GROUP_ALLOWED_USERS", raising=False)
         monkeypatch.delenv("WHATSAPP_GROUP_ALLOW_FROM", raising=False)
-
         ss.set_multiplex_active(True)
         tok = ss.set_secret_scope(ss.build_profile_secret_scope(tmp_path))
         try:
             adapter = _adapter_with_extra({})
-            assert adapter._group_allow_from == {"86316009876@s.whatsapp.net"}
         finally:
             ss.reset_secret_scope(tok)
             ss.set_multiplex_active(False)
-
-
-class TestGroupGatingUsesEnvSeededAllowlist:
-    """#72529's symptom: authorized group senders rejected because the allowlist was empty."""
-
-    def test_allowlisted_group_chat_passes_intake(self, monkeypatch):
-        """group_policy=allowlist + env-only allowlist → the group chat is admitted."""
-        monkeypatch.setenv("WHATSAPP_GROUP_ALLOWED_USERS", "120363001234567890@g.us")
-        monkeypatch.setenv("WHATSAPP_GROUP_POLICY", "allowlist")
-        adapter = _adapter_with_extra({})
-        assert adapter._group_policy == "allowlist"
+        assert adapter._group_allow_from == {"120363001234567890@g.us"}
         assert adapter._is_group_allowed("120363001234567890@g.us") is True
         assert adapter._is_group_allowed("99999999999@g.us") is False
 
-    def test_open_group_policy_unaffected(self, monkeypatch):
-        monkeypatch.setenv("WHATSAPP_GROUP_POLICY", "open")
-        monkeypatch.delenv("WHATSAPP_GROUP_ALLOWED_USERS", raising=False)
-        adapter = _adapter_with_extra({})
-        assert adapter._is_group_allowed("120363001234567890@g.us") is True
+    def test_config_group_allow_from_wins_over_env(self, monkeypatch):
+        """An explicit config list (either spelling) stays authoritative — env must not broaden it."""
+        monkeypatch.setenv("WHATSAPP_GROUP_ALLOWED_USERS", "1111111111@g.us")
+        assert _adapter_with_extra({"group_allow_from": ["120363001234567890@g.us"]})._group_allow_from == {"120363001234567890@g.us"}
+        assert _adapter_with_extra({"groupAllowFrom": []})._group_allow_from == set()
diff --git a/tests/gateway/test_whatsapp_stale_bridge.py b/tests/gateway/test_whatsapp_stale_bridge.py
index a35d0d71fb..db8b197e82 100644
--- a/tests/gateway/test_whatsapp_stale_bridge.py
+++ b/tests/gateway/test_whatsapp_stale_bridge.py
@@ -54,8 +54,8 @@ def _make_adapter(bridge_script: str = "/tmp/test-bridge.js",
     adapter._bridge_process = None
     adapter._reply_prefix = None
     adapter._send_read_receipts = False
-    adapter._dm_policy = "pairing"
-    adapter._allow_from = set()
+    adapter._dm_policy = adapter._group_policy = "pairing"
+    adapter._allow_from = adapter._group_allow_from = set()
     adapter._running = False
     adapter._message_handler = None
     adapter._fatal_error_code = None
@@ -86,11 +86,11 @@ def _setup_bridge_dir(tmp_path: Path) -> Path:
     """Create a real bridge dir with bridge.js + package.json + creds."""
     bridge_dir = tmp_path / "whatsapp-bridge"
     bridge_dir.mkdir()
-    (bridge_dir / "bridge.js").write_text("// current bridge code\n")
-    (bridge_dir / "package.json").write_text('{"name": "bridge"}\n')
+    (bridge_dir / "bridge.js").write_text("// current bridge code\n", encoding="utf-8")
+    (bridge_dir / "package.json").write_text('{"name": "bridge"}\n', encoding="utf-8")
     session_path = tmp_path / "session"
     session_path.mkdir()
-    (session_path / "creds.json").write_text("{}")
+    (session_path / "creds.json").write_text("{}", encoding="utf-8")
     return bridge_dir
 
 
@@ -110,7 +110,7 @@ class TestFileContentHash:
         from plugins.platforms.whatsapp.adapter import _file_content_hash
 
         f = tmp_path / "x.js"
-        f.write_text("abc")
+        f.write_text("abc", encoding="utf-8")
         h = _file_content_hash(f)
         assert len(h) == 16
         assert h == _file_content_hash(f)  # deterministic

From 8925c70a1c84dc5fe66f002d74d750577c121efa Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 02:56:28 +0530
Subject: [PATCH 167/190] docs(whatsapp): group access section says what the
 gateway admits; env reference rows; trim bridge tests

Groups: policy, group-JID allowlist, and that participants are still authorised by
the gateway sender allowlist or pairing (`open` alone admits nobody without one);
`require_mention` defaults to false; WHATSAPP_GROUP_POLICY / WHATSAPP_GROUP_ALLOWED_USERS
rows in the environment reference. The alt-id node tests collapse to one (the
participantAlt case duplicated the first-contact case; the "still resolves via mapping
files" case only re-asserted matchesAllowedUser).
---
 scripts/whatsapp-bridge/allowlist.test.mjs    | 50 +------------------
 .../docs/reference/environment-variables.md   |  2 +
 website/docs/user-guide/messaging/whatsapp.md | 14 ++++++
 3 files changed, 18 insertions(+), 48 deletions(-)

diff --git a/scripts/whatsapp-bridge/allowlist.test.mjs b/scripts/whatsapp-bridge/allowlist.test.mjs
index daa85cb740..10da9e3369 100644
--- a/scripts/whatsapp-bridge/allowlist.test.mjs
+++ b/scripts/whatsapp-bridge/allowlist.test.mjs
@@ -48,14 +48,14 @@ test('matchesAllowedUser accepts mapped lid sender when allowlist only contains
   }
 });
 
-test('matchesAllowedSender accepts Baileys senderPn when a first-contact LID has no mapping yet', () => {
+test('matchesAllowedSender accepts the Baileys alt phone JID when a first-contact LID has no mapping yet (#63415, #72529)', () => {
   const sessionDir = mkdtempSync(path.join(os.tmpdir(), 'hermes-wa-allowlist-'));
 
   try {
     const allowedUsers = parseAllowedUsers('+19175395595');
     // On a first message from a WhatsApp Multi-Device contact, Baileys can
     // emit a LID as senderId before it has written LID mapping files, while
-    // senderPn carries WhatsApp's authenticated phone JID.
+    // key.remoteJidAlt / key.participantAlt carries the phone JID.
     assert.equal(
       matchesAllowedSender('267383306489914@lid', '19175395595@s.whatsapp.net', allowedUsers, sessionDir),
       true,
@@ -122,49 +122,3 @@ test('matchesAllowedUser rejects everyone when allowlist is empty (#8389)', () =
     rmSync(sessionDir, { recursive: true, force: true });
   }
 });
-
-test('matchesAllowedSender falls back to participantAlt when no lid mapping exists (#72529)', () => {
-  // Baileys v7 group messages arrive with key.participant in LID form and
-  // the phone number only in key.participantAlt. A fresh bot session has no
-  // lid-mapping-*.json files, so the LID alone can never match a phone
-  // allowlist — the alt identifier must be consulted as a fallback.
-  const sessionDir = mkdtempSync(path.join(os.tmpdir(), 'hermes-wa-allowlist-'));
-
-  try {
-    const allowedUsers = parseAllowedUsers('+19175395595');
-
-    // No mapping file: LID by itself is rejected today (the #72529 drop)…
-    assert.equal(matchesAllowedUser('267383306489914@lid', allowedUsers, sessionDir), false);
-    // …but the alt phone identifier rescues the match.
-    assert.equal(
-      matchesAllowedSender('267383306489914@lid', '19175395595@s.whatsapp.net', allowedUsers, sessionDir),
-      true
-    );
-
-    // A stranger's LID with a non-allowlisted alt stays rejected.
-    assert.equal(
-      matchesAllowedSender('188012763865257@lid', '15550001111@s.whatsapp.net', allowedUsers, sessionDir),
-      false
-    );
-
-    // Missing / empty alt keeps the existing behaviour.
-    assert.equal(matchesAllowedSender('267383306489914@lid', '', allowedUsers, sessionDir), false);
-    assert.equal(matchesAllowedSender('267383306489914@lid', undefined, allowedUsers, sessionDir), false);
-  } finally {
-    rmSync(sessionDir, { recursive: true, force: true });
-  }
-});
-
-test('matchesAllowedSender still resolves via lid-mapping files without an alt', () => {
-  const sessionDir = mkdtempSync(path.join(os.tmpdir(), 'hermes-wa-allowlist-'));
-
-  try {
-    writeFileSync(path.join(sessionDir, 'lid-mapping-19175395595.json'), JSON.stringify('267383306489914'));
-    writeFileSync(path.join(sessionDir, 'lid-mapping-267383306489914_reverse.json'), JSON.stringify('19175395595'));
-
-    const allowedUsers = parseAllowedUsers('+19175395595');
-    assert.equal(matchesAllowedSender('267383306489914@lid', '', allowedUsers, sessionDir), true);
-  } finally {
-    rmSync(sessionDir, { recursive: true, force: true });
-  }
-});
diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/environment-variables.md
index 7eb8b0398a..af7b87610e 100644
--- a/website/docs/reference/environment-variables.md
+++ b/website/docs/reference/environment-variables.md
@@ -388,6 +388,8 @@ These are set automatically by the Docker terminal backend when `proxy.enabled:
 | `WHATSAPP_MODE` | `bot` (separate number) or `self-chat` (message yourself) |
 | `WHATSAPP_ALLOWED_USERS` | Comma-separated phone numbers (with country code, no `+`), or `*` to allow all senders |
 | `WHATSAPP_ALLOW_ALL_USERS` | Allow all WhatsApp senders without an allowlist (`true`/`false`) |
+| `WHATSAPP_GROUP_POLICY` | Group intake: `pairing` (default, forwards nothing from groups), `allowlist` (group JIDs below), `open` (every group; participants still need `WHATSAPP_ALLOWED_USERS`, pairing, or `WHATSAPP_ALLOW_ALL_USERS`), or `disabled` |
+| `WHATSAPP_GROUP_ALLOWED_USERS` | Comma-separated group JIDs (e.g. `120363001234567890@g.us`) admitted under `WHATSAPP_GROUP_POLICY=allowlist` |
 | `WHATSAPP_HOME_CHANNEL` | Default chat ID for cron / notification delivery. |
 | `WHATSAPP_HOME_CHANNEL_NAME` | Display name for the WhatsApp home channel. |
 | `WHATSAPP_DEBUG` | Log raw message events in the bridge for troubleshooting (`true`/`false`) |
diff --git a/website/docs/user-guide/messaging/whatsapp.md b/website/docs/user-guide/messaging/whatsapp.md
index e4d9699bd2..60f4020e37 100644
--- a/website/docs/user-guide/messaging/whatsapp.md
+++ b/website/docs/user-guide/messaging/whatsapp.md
@@ -130,6 +130,20 @@ whatsapp:
 - `unauthorized_dm_behavior: pair` is the global default. Unknown DM senders get a pairing code.
 - `whatsapp.unauthorized_dm_behavior: ignore` makes WhatsApp stay silent for unauthorized DMs, which is usually the better choice for a private number.
 
+### Group chats (bot mode)
+
+Groups are gated by **group policy**, not by the DM allowlist. `WHATSAPP_GROUP_POLICY` / `whatsapp.group_policy`
+defaults to `pairing`, which forwards nothing from groups. `allowlist` plus `WHATSAPP_GROUP_ALLOWED_USERS` /
+`whatsapp.group_allow_from` (comma-separated **group JIDs**, e.g. `120363001234567890@g.us`) admits the listed
+groups; `open` admits every group the bot is a member of. The sender is then checked like any other gateway
+principal: with `WHATSAPP_ALLOWED_USERS` set, a participant must be on it (or paired) — a sender WhatsApp
+addresses by LID matches through the phone number Baileys supplies alongside it, so a first contact with no
+`lid-mapping` file yet is not dropped; with no sender allowlist,
+`allowlist` trusts the group-JID list alone and admits every participant of a listed group, while `open` still
+needs the participant paired or `WHATSAPP_ALLOW_ALL_USERS=true`. By default the bot answers every admitted group
+message; set `require_mention: true` / `WHATSAPP_REQUIRE_MENTION=true` to answer only @mentions, replies to the
+bot, or `/commands` (groups in `free_response_chats` are exempt).
+
 Then start the gateway:
 
 ```bash

From bd39167c565679bec6430d4a4d003d34c21e2630 Mon Sep 17 00:00:00 2001
From: x7peeps <xtpeeps@qq.com>
Date: Sat, 19 Sep 2026 02:30:03 +0530
Subject: [PATCH 168/190] fix(weixin): ret=-2 "prepare failed" that survives
 recovery is a session error, not a rate limit (#80125)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

iLink answers a bot-initiated send with ret=-2 errmsg="prepare failed" when the
peer's session is not ready (no inbound message yet, or the context token is
gone). That is deterministic: treating it as a frequency limit spent the retry
budget on an error that never clears and opened the 30 s rate-limit breaker for
the whole account, blocking every later send (#80125, #112709).

After the tokenless re-send (46ab37ce35) has been tried — or when there is no
token to drop — a stale-session -2 now fails fast with a descriptive
"session not ready" error and never reaches the rate-limit path. The text
avoids the "rate limit" substring classify_send_error keys on.

Salvage of #80152 (fail fast + keep the breaker closed); #80156 arrived five
minutes later with the same change.

Co-authored-by: RelaxJonh <92573950+RelaxJonh@users.noreply.github.com>
---
 gateway/platforms/weixin.py | 24 ++++++++++++++++++++----
 1 file changed, 20 insertions(+), 4 deletions(-)

diff --git a/gateway/platforms/weixin.py b/gateway/platforms/weixin.py
index eedb8abe0f..1f1df222f2 100644
--- a/gateway/platforms/weixin.py
+++ b/gateway/platforms/weixin.py
@@ -77,6 +77,16 @@ def _is_session_expired(resp: Dict[str, Any], ret: Any, errcode: Any) -> bool:
     return SESSION_EXPIRED_ERRCODE in (ret, errcode) or _is_stale_session_ret(ret, errcode, resp.get("errmsg"))
 
 
+def _session_not_ready_error(ret: Any, errcode: Any, errmsg: Any) -> RuntimeError:
+    """The stale-session ``-2`` after the tokenless re-send is exhausted (or with no token to drop): iLink will not
+    prepare a bot-initiated send until this peer messages the bot again. Deterministic, so it is neither retried nor
+    fed to the rate-limit breaker (#80125). The text must not contain "rate limit" — ``classify_send_error`` would
+    route it back into the rate-limited redelivery lane."""
+    return RuntimeError(
+        f"iLink sendmessage session not ready: ret={ret} errcode={errcode} errmsg={errmsg or 'unknown error'}"
+        " — the user must send the bot a message first (or re-pair)")
+
+
 def _make_ssl_connector() -> Optional["aiohttp.TCPConnector"]:
     """TCPConnector with certifi's CA bundle (``ilinkai.weixin.qq.com`` fails some system stores, e.g. Homebrew
     OpenSSL); None without certifi so aiohttp's default (honors ``SSL_CERT_FILE`` under trust_env) applies.
@@ -968,9 +978,11 @@ class WeixinAdapter(OwnAccessPolicyMixin, BasePlatformAdapter):
         return self._rate_limit_cooldown_remaining() > 0
 
     async def _send_text_chunk(self, *, chat_id: str, chunk: str, context_token: Optional[str], client_id: str) -> None:
-        """Send one text chunk with retry/backoff under the adapter-wide text gate. On session-expired (errcode -14)
-        retry once *without* ``context_token`` — iLink accepts tokenless sends as a degraded fallback, which keeps cron
-        pushes working when no user message refreshed the session."""
+        """Send one text chunk with retry/backoff under the adapter-wide text gate. A stale-session response (``-14``,
+        or ``-2`` with ``prepare failed``/``unknown error``) is re-sent once *without* ``context_token`` — iLink accepts
+        tokenless sends as a degraded fallback, which keeps cron pushes working when no user message refreshed the
+        session. A ``-2`` stale-session answer that survives that (or arrives with no token to drop) fails fast with
+        ``_session_not_ready_error`` instead of entering the retry ladder or the rate-limit breaker (#80125)."""
         async with self._send_text_gate:
             last_error: Optional[Exception] = None
             retried_without_token = False
@@ -984,12 +996,16 @@ class WeixinAdapter(OwnAccessPolicyMixin, BasePlatformAdapter):
                         context_token=context_token, client_id=client_id)
                     ret, errcode = (resp.get("ret"), resp.get("errcode")) if resp and isinstance(resp, dict) else (None, None)
                     if (ret is not None and ret != 0) or (errcode is not None and errcode != 0):
+                        errmsg = resp.get("errmsg") or resp.get("msg")
                         if _is_session_expired(resp, ret, errcode) and not retried_without_token and context_token:
                             retried_without_token, context_token = True, None
                             self._token_store._cache.pop(self._token_store._key(self._account_id, chat_id), None)
                             logger.warning("[%s] session expired for %s; retrying without context_token", self.name, _safe_id(chat_id))
                             continue
-                        errmsg = resp.get("errmsg") or resp.get("msg")
+                        if _is_stale_session_ret(ret, errcode, errmsg):
+                            # break, not raise: a raise here is caught below and re-enters the retry ladder.
+                            last_error = _session_not_ready_error(ret, errcode, errmsg)
+                            break
                         if ret != RATE_LIMIT_ERRCODE and errcode != RATE_LIMIT_ERRCODE:
                             raise RuntimeError(f"iLink sendmessage error: ret={ret} errcode={errcode} errmsg={errmsg or 'unknown error'}")
                         # Keep a descriptive error for when the loop exhausts while still limited.

From 5db9f02372c3f9ae8f6cd26de720516b386b8651 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 02:30:03 +0530
Subject: [PATCH 169/190] fix(weixin): same session-not-ready error on the
 media leg; cooldown message keeps the raw fields; test + docs

_send_file hit the identical stale -2 after its own tokenless re-send and still
raised the generic "sendmessage error"; it now raises the shared
_session_not_ready_error. The genuine rate-limit cooldown message carries
ret/errcode/errmsg so operators can tell a real -2 frequency limit from the
session case. One parametrised test (stored token / no token) asserts the send
fails once, classify_send_error does not call it rate_limited, and the breaker
stays closed; troubleshooting row in the Weixin docs.
---
 gateway/platforms/weixin.py                 | 10 +++++---
 tests/gateway/test_weixin.py                | 27 ++++++++++++++++++---
 website/docs/user-guide/messaging/weixin.md |  2 +-
 3 files changed, 31 insertions(+), 8 deletions(-)

diff --git a/gateway/platforms/weixin.py b/gateway/platforms/weixin.py
index 1f1df222f2..d8c3e835d3 100644
--- a/gateway/platforms/weixin.py
+++ b/gateway/platforms/weixin.py
@@ -74,7 +74,7 @@ def _is_stale_session_ret(ret: "Optional[int]", errcode: "Optional[int]", errmsg
 
 
 def _is_session_expired(resp: Dict[str, Any], ret: Any, errcode: Any) -> bool:
-    return SESSION_EXPIRED_ERRCODE in (ret, errcode) or _is_stale_session_ret(ret, errcode, resp.get("errmsg"))
+    return SESSION_EXPIRED_ERRCODE in (ret, errcode) or _is_stale_session_ret(ret, errcode, resp.get("errmsg") or resp.get("msg"))
 
 
 def _session_not_ready_error(ret: Any, errcode: Any, errmsg: Any) -> RuntimeError:
@@ -981,8 +981,7 @@ class WeixinAdapter(OwnAccessPolicyMixin, BasePlatformAdapter):
         """Send one text chunk with retry/backoff under the adapter-wide text gate. A stale-session response (``-14``,
         or ``-2`` with ``prepare failed``/``unknown error``) is re-sent once *without* ``context_token`` — iLink accepts
         tokenless sends as a degraded fallback, which keeps cron pushes working when no user message refreshed the
-        session. A ``-2`` stale-session answer that survives that (or arrives with no token to drop) fails fast with
-        ``_session_not_ready_error`` instead of entering the retry ladder or the rate-limit breaker (#80125)."""
+        session. A ``-2`` that survives that fails fast via ``_session_not_ready_error``."""
         async with self._send_text_gate:
             last_error: Optional[Exception] = None
             retried_without_token = False
@@ -1012,7 +1011,8 @@ class WeixinAdapter(OwnAccessPolicyMixin, BasePlatformAdapter):
                         last_error = RuntimeError(f"iLink sendmessage rate limited: ret={ret} errcode={errcode} errmsg={errmsg or 'rate limited'}")
                         if self._record_rate_limit_event():
                             last_error = RuntimeError(
-                                f"iLink sendmessage rate limited; cooldown active for {self._rate_limit_cooldown_remaining():.1f}s")
+                                f"iLink sendmessage rate limited (ret={ret} errcode={errcode} errmsg={errmsg or 'rate limited'}); "
+                                f"cooldown active for {self._rate_limit_cooldown_remaining():.1f}s")
                             break
                         if attempt >= self._send_chunk_retries:
                             break
@@ -1187,6 +1187,8 @@ class WeixinAdapter(OwnAccessPolicyMixin, BasePlatformAdapter):
                     logger.warning("[%s] session expired for %s; re-sending media without context_token", self.name, _safe_id(chat_id))
                     continue
                 errmsg = resp.get("errmsg") or resp.get("msg")
+                if _is_stale_session_ret(ret, errcode, errmsg):
+                    raise _session_not_ready_error(ret, errcode, errmsg)
                 raise RuntimeError(f"iLink sendmessage error: ret={ret} errcode={errcode} errmsg={errmsg or 'unknown error'}")
         return last_message_id
 
diff --git a/tests/gateway/test_weixin.py b/tests/gateway/test_weixin.py
index 9e539decd2..9a5575b9aa 100644
--- a/tests/gateway/test_weixin.py
+++ b/tests/gateway/test_weixin.py
@@ -257,13 +257,13 @@ class TestWeixinSendMessageIntegration:
 
 
 class TestWeixinChunkDelivery:
-    def _connected_adapter(self) -> WeixinAdapter:
+    def _connected_adapter(self, context_token="ctx-token") -> WeixinAdapter:
         adapter = _make_adapter()
         adapter._session = object()
         adapter._send_session = adapter._session
         adapter._token = "test-token"
         adapter._base_url = "https://weixin.example.com"
-        adapter._token_store.get = lambda account_id, chat_id: "ctx-token"
+        adapter._token_store.get = lambda account_id, chat_id: context_token
         return adapter
 
 
@@ -337,6 +337,27 @@ class TestWeixinChunkDelivery:
         assert [call.kwargs["context_token"] for call in send_message_mock.await_args_list] == ["ctx-token", None]
         assert adapter._rate_limit_circuit_until == 0.0
 
+    @pytest.mark.parametrize("stored_token", [None, "ctx-token"])
+    @patch("gateway.platforms.weixin._send_message", new_callable=AsyncMock)
+    def test_prepare_failed_without_recovery_is_not_a_rate_limit(self, send_message_mock, stored_token):
+        """No token to drop (fresh pairing, #80125) or a tokenless re-send that still fails: the error names the
+        real cause and the rate-limit breaker stays closed, instead of "rate limited; cooldown active" for 30s."""
+        from gateway.platforms.base import classify_send_error
+
+        adapter = self._connected_adapter(context_token=stored_token)
+        adapter._rate_limit_circuit_threshold = 1
+        send_message_mock.return_value = {"ret": weixin.RATE_LIMIT_ERRCODE, "errmsg": "prepare failed"}
+
+        result = asyncio.run(adapter.send("wxid_test123", "hello"))
+
+        assert result.success is False
+        assert "prepare failed" in (result.error or "") and "cooldown" not in (result.error or "")
+        # The platform-neutral classifier must not route it back into the rate-limited redelivery lane either.
+        assert classify_send_error(None, result.error or "") != "rate_limited"
+        assert adapter._rate_limit_cooldown_remaining() == 0.0
+        assert [call.kwargs["context_token"] for call in send_message_mock.await_args_list] == (
+            [None] if stored_token is None else ["ctx-token", None])
+
     @patch("gateway.platforms.weixin._send_message", new_callable=AsyncMock)
     def test_tokenless_resend_does_not_consume_retry_budget(self, send_message_mock):
         """With ``send_chunk_retries=0`` the stale-session re-send must still happen: it is a different payload,
@@ -364,7 +385,7 @@ class TestWeixinChunkDelivery:
         result = asyncio.run(adapter.send_document("wxid_test123", str(doc)))
 
         assert result.success is False
-        assert "prepare failed" in (result.error or "")
+        assert "session not ready" in (result.error or "") and "prepare failed" in (result.error or "")
         assert [call.kwargs["context_token"] for call in send_items_mock.await_args_list] == ["ctx-token", None]
 
 
diff --git a/website/docs/user-guide/messaging/weixin.md b/website/docs/user-guide/messaging/weixin.md
index 3b7600d73e..eb23c08426 100644
--- a/website/docs/user-guide/messaging/weixin.md
+++ b/website/docs/user-guide/messaging/weixin.md
@@ -322,7 +322,7 @@ Only one Weixin gateway instance can use a given token at a time. The adapter ac
 | `Weixin startup failed: WEIXIN_ACCOUNT_ID is required` | Set `WEIXIN_ACCOUNT_ID` in your `.env` or run `hermes gateway setup` |
 | `Another local Hermes gateway is already using this Weixin token` | Stop the other gateway instance first — only one poller per token is allowed |
 | Session expired (`errcode=-14`) | Your login session has expired. Re-run `hermes gateway setup` to scan a new QR code |
-| Proactive send (cron / notification) fails with `ret=-2 errmsg=prepare failed` or `unknown error` | The peer's `context_token` went stale (no recent inbound message from them). The adapter treats this as a stale session — not a rate limit — and re-sends once without the token, so the message still arrives. Only other `-2` responses trigger the rate-limit backoff/cooldown |
+| Proactive send (cron / notification) fails with `ret=-2 errmsg=prepare failed` or `unknown error` | The peer's `context_token` went stale (no recent inbound message from them). The adapter treats this as a stale session — not a rate limit — and re-sends once without the token, so the message still arrives. If iLink still answers `prepare failed` (or there was no token to drop — a freshly paired bot), the send (text or media) fails with `iLink sendmessage session not ready … the user must send the bot a message first (or re-pair)`; the rate-limit cooldown never opens for it. Only other `-2` responses trigger the rate-limit backoff/cooldown, and that cooldown error carries the raw `ret`/`errcode`/`errmsg` |
 | QR code expired during setup | The QR auto-refreshes up to 3 times. If it keeps expiring, check your network connection |
 | Bot doesn't respond to DMs | Check `WEIXIN_DM_POLICY` — if set to `allowlist`, the sender must be in `WEIXIN_ALLOWED_USERS` |
 | Bot ignores group messages | Group policy defaults to `disabled`. Set `WEIXIN_GROUP_POLICY=open` or `allowlist` — but note that QR-login iLink bot identities (`...@im.bot`) typically cannot receive ordinary WeChat group messages at all. If the gateway logs show no raw inbound events for group messages, the limitation is on the iLink side, not in Hermes. |

From c0f3d1fedf268eee31265eb0d19f6592e1d167fb Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 03:11:46 +0530
Subject: [PATCH 170/190] chore: map contributor email for @TheBlueHouse75
 (#108239 salvage)

---
 .../emails/132676556+TheBlueHouse75@users.noreply.github.com    | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 contributors/emails/132676556+TheBlueHouse75@users.noreply.github.com

diff --git a/contributors/emails/132676556+TheBlueHouse75@users.noreply.github.com b/contributors/emails/132676556+TheBlueHouse75@users.noreply.github.com
new file mode 100644
index 0000000000..1855b0831a
--- /dev/null
+++ b/contributors/emails/132676556+TheBlueHouse75@users.noreply.github.com
@@ -0,0 +1,2 @@
+TheBlueHouse75
+# PR #108239 salvage

From 2d99b7cf5d1903465df4f3e21505159bc180f835 Mon Sep 17 00:00:00 2001
From: TheBlueHouse75 <132676556+TheBlueHouse75@users.noreply.github.com>
Date: Sat, 19 Sep 2026 03:19:30 +0530
Subject: [PATCH 171/190] fix(gateway): rebind webhook and api_server over
 TIME_WAIT after a restart on macOS
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

On macOS, an exclusive bind (SO_REUSEADDR disabled) refuses a port that is
still held only by a server-side TIME_WAIT socket for 2*MSL (~30s) after a
previous connection close — the gateway's own shutdown, or any
``Connection: close`` request. A ``/restart`` issued within that window
failed to bind, even though nobody was actually listening.

For an explicit host, a refused connect probe proves nobody is listening:
the kernel still rejects an exact duplicate bind even with SO_REUSEADDR, and
a foreign wildcard listener would answer the probe. So one retry with
SO_REUSEADDR is safe in that case. A wildcard host keeps the strict
exclusive path, since a foreign listener on a non-loopback interface can't
be probed this way. A live listener still wins either way.

The bind, probe, and retry logic is shared by webhook.py and api_server.py
through the new gateway/platforms/tcp_site.py, since both adapters had the
same exposure — api_server additionally marked a spurious TIME_WAIT bind
failure as a non-retryable port conflict.

(cherry picked from commit 289fd06148c447829f1e38b66ff78b9e4bebdeb4)
---
 gateway/platforms/api_server.py             | 15 ++---
 gateway/platforms/tcp_site.py               | 65 +++++++++++++++++++++
 gateway/platforms/webhook.py                |  9 +--
 tests/gateway/test_api_server_bind_guard.py | 21 +++++++
 tests/gateway/test_webhook_adapter.py       | 54 +++++++++++++++++
 5 files changed, 146 insertions(+), 18 deletions(-)
 create mode 100644 gateway/platforms/tcp_site.py

diff --git a/gateway/platforms/api_server.py b/gateway/platforms/api_server.py
index 2798bf1037..899cb9589e 100644
--- a/gateway/platforms/api_server.py
+++ b/gateway/platforms/api_server.py
@@ -137,6 +137,7 @@ from gateway.browser_control_broker import (
 
 from gateway.platforms._shared import coerce_port as _coerce_port
 from gateway.platforms._shared import get_scoped_secret as _get_scoped_secret
+from gateway.platforms.tcp_site import start_tcp_site
 
 
 logger = logging.getLogger(__name__)
@@ -4019,24 +4020,16 @@ class APIServerAdapter(OpenAICompatRoutesMixin, BasePlatformAdapter):
             self._wire_plugin_handlers(self._app)
             self._runner = web.AppRunner(self._app)
             await self._runner.setup()
-            # Bind directly (a pre-probe raced the bind, misreporting TIME_WAIT as "in use").
-            # SO_REUSEADDR off on macOS (BSD can split traffic between two listeners).
             # Bind directly instead of probing 127.0.0.1 first — the old single-family pre-probe raced the
             # real bind and reported a TIME_WAIT socket as "in use" (#10297), failing gateway restarts for
-            # up to ~60s. SO_REUSEADDR is platform-dependent (same rationale as the webhook adapter,
-            # #65482): - macOS (BSD semantics): two sockets with SO_REUSEADDR can silently split traffic
-            # while both report success — disable. - Linux: SO_REUSEADDR only permits rebinding past
-            # TIME_WAIT (a second live listener needs SO_REUSEPORT, never set), so keep the default
-            # (enabled) for instant restart rebinds.
+            # up to ~60s. Platform-dependent SO_REUSEADDR and the macOS TIME_WAIT rebind live in
+            # start_tcp_site; the loop below covers a predecessor still holding the port for a moment.
             try:
-                # A restart's predecessor may still hold the port for a moment after its PID is gone.
                 # aiohttp registers a site with its runner before binding, so a failed start leaves the
                 # site registered: rebuild the runner per attempt rather than reach into its internals.
                 for attempt in range(_BIND_ATTEMPTS):
-                    self._site = web.TCPSite(
-                        self._runner, self._host, self._port, reuse_address=False if sys.platform == "darwin" else None)
                     try:
-                        await self._site.start()
+                        self._site = await start_tcp_site(self._runner, self._host, self._port, log_tag=self.name)
                         break
                     except OSError as exc:
                         if exc.errno != errno.EADDRINUSE or attempt == _BIND_ATTEMPTS - 1:
diff --git a/gateway/platforms/tcp_site.py b/gateway/platforms/tcp_site.py
new file mode 100644
index 0000000000..6160075a5a
--- /dev/null
+++ b/gateway/platforms/tcp_site.py
@@ -0,0 +1,65 @@
+"""Bind an aiohttp ``TCPSite`` for the HTTP-serving adapters (webhook, api_server): exclusive on macOS,
+yet able to rebind over a lingering TIME_WAIT socket right after a gateway restart."""
+
+import asyncio
+import errno
+import logging
+import socket
+import sys
+from typing import Optional
+
+from aiohttp import web
+
+logger = logging.getLogger(__name__)
+
+_WILDCARD_HOSTS = frozenset({"0.0.0.0", "::"})
+
+
+def is_wildcard_host(host: Optional[str]) -> bool:
+    """True for the dual-stack default (None/"") and the per-family wildcards."""
+    return not host or host.strip() in _WILDCARD_HOSTS
+
+
+def has_live_listener(host: str, port: int) -> bool:
+    """Blocking probe: True when something accepts connections on ``host:port``. Refused = nobody listens;
+    any other failure (timeout, unroutable) is treated as live so the caller stays exclusive."""
+    try:
+        with socket.create_connection((host, port), timeout=1.0):
+            return True
+    except ConnectionRefusedError:
+        return False
+    except OSError:
+        return True
+
+
+async def start_tcp_site(runner: web.BaseRunner, host: Optional[str], port: int, *, log_tag: str) -> web.TCPSite:
+    """Bind ``host:port`` on ``runner`` and return the started site; raises OSError when unavailable.
+
+    SO_REUSEADDR: on macOS (BSD) two wildcard/specific sockets can silently split traffic while
+    both report success → disable. On Linux it only permits rebinding past TIME_WAIT (a quick
+    restart would otherwise fail to bind for ~60s) → keep the default.
+
+    The macOS exclusive bind also refuses the port while a server-side TIME_WAIT socket lingers
+    (2*MSL = 30s after the previous gateway closed a connection first — its shutdown, or any
+    ``Connection: close`` request), so a ``/restart`` re-binding within seconds failed with
+    EADDRINUSE although nobody was listening. Preventing the TIME_WAIT at close time (SO_LINGER 0)
+    would reset in-flight senders and misses the per-request case, hence the bind-side retry: for an
+    explicit host, ``has_live_listener`` refused proves the address is free (the kernel still
+    rejects an exact duplicate even with SO_REUSEADDR, and a foreign wildcard listener answers the
+    probe), so one retry with reuse_address=True is safe. A wildcard host keeps the strict path: a
+    foreign listener on a non-loopback interface could not be probed, so it must keep winning."""
+    exclusive = sys.platform == "darwin"
+    site = web.TCPSite(runner, host, port, reuse_address=False if exclusive else None)
+    try:
+        await site.start()
+    except OSError as exc:
+        if not exclusive or exc.errno != errno.EADDRINUSE or is_wildcard_host(host):
+            raise
+        if await asyncio.to_thread(has_live_listener, host, port):
+            raise
+        await site.stop()  # aiohttp registers a site before binding: drop the dead one from the runner
+        logger.info("[%s] %s:%d busy without a live listener (TIME_WAIT from the previous gateway); "
+                    "rebinding with SO_REUSEADDR", log_tag, host, port)
+        site = web.TCPSite(runner, host, port, reuse_address=True)
+        await site.start()
+    return site
diff --git a/gateway/platforms/webhook.py b/gateway/platforms/webhook.py
index c5332331b4..8f361e725f 100644
--- a/gateway/platforms/webhook.py
+++ b/gateway/platforms/webhook.py
@@ -17,7 +17,6 @@ import logging
 import os
 import re
 import subprocess
-import sys
 import time
 from collections import deque
 from contextlib import nullcontext, suppress
@@ -34,6 +33,7 @@ except ImportError:
 from gateway.config import Platform, PlatformConfig
 from gateway.platforms.base import BasePlatformAdapter, SendResult
 from gateway.platforms.event import MessageEvent, MessageType
+from gateway.platforms.tcp_site import start_tcp_site
 from gateway.platforms.webhook_coalesce import WebhookCoalescer, validate_coalesce_config
 from gateway.platforms.webhook_filters import DEFAULT_SCRIPT_TIMEOUT_SECONDS, WebhookRouteProcessor
 from gateway.response_filters import is_autonomous_silence_response
@@ -231,13 +231,8 @@ class WebhookAdapter(BasePlatformAdapter):
         app.router.add_route("*", "/p/{profile}/{tail:.*}", self._handle_profile_ingress)
         self._runner = web.AppRunner(app)
         await self._runner.setup()
-        # SO_REUSEADDR: on macOS (BSD) two wildcard/specific sockets can silently split traffic while
-        # both report success → disable. On Linux it only permits rebinding past TIME_WAIT (a quick
-        # restart would otherwise fail to bind for ~60s) → keep the default.
-        site = web.TCPSite(self._runner, self._host, self._port,
-                           reuse_address=False if sys.platform == "darwin" else None)
         try:
-            await site.start()
+            await start_tcp_site(self._runner, self._host, self._port, log_tag="webhook")
         except OSError as exc:
             await self._runner.cleanup()
             self._runner = None
diff --git a/tests/gateway/test_api_server_bind_guard.py b/tests/gateway/test_api_server_bind_guard.py
index 4a7788ebb7..967d46e5d4 100644
--- a/tests/gateway/test_api_server_bind_guard.py
+++ b/tests/gateway/test_api_server_bind_guard.py
@@ -145,6 +145,27 @@ class TestBindMechanics:
             await second.disconnect()
 
 
+    @pytest.mark.macos_only  # the exclusive bind (reuse_address=False) is a Darwin-only path
+    @pytest.mark.asyncio
+    async def test_rebind_over_time_wait(self):
+        """A port held only by a server-side TIME_WAIT socket (the previous gateway closed a
+        connection first) must not fail the bind on macOS, where address reuse is disabled."""
+        listener = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        listener.bind(("127.0.0.1", 0))
+        listener.listen(1)
+        port = listener.getsockname()[1]
+        client = socket.create_connection(("127.0.0.1", port))
+        accepted, _ = listener.accept()
+        accepted.close()  # the side closing first enters TIME_WAIT
+        client.close()
+        listener.close()
+        adapter = self._make_adapter(port)
+        try:
+            assert await adapter.connect() is True
+            assert adapter.has_fatal_error is False
+        finally:
+            await adapter.disconnect()
+
     @pytest.mark.asyncio
     async def test_port_conflict_sets_non_retryable_fatal_error(self):
         """A real port conflict (EADDRINUSE) must set a non-retryable fatal
diff --git a/tests/gateway/test_webhook_adapter.py b/tests/gateway/test_webhook_adapter.py
index 22cd20a7b6..1ced2268af 100644
--- a/tests/gateway/test_webhook_adapter.py
+++ b/tests/gateway/test_webhook_adapter.py
@@ -965,6 +965,60 @@ class TestDualStackBind:
             await adapter.disconnect()
 
 
+class TestExclusiveBindTimeWait:
+    """macOS binds the listener with ``reuse_address=False`` (exclusive dual-stack bind). On BSD that
+    also refuses the port while a TIME_WAIT connection from the previous gateway lingers (2*MSL = 30s):
+    a ``/restart`` re-binds within seconds and used to fail with EADDRINUSE although nobody was
+    listening (observed on 127.0.0.1:8644; the reconnect watcher only recovered ~50s later)."""
+
+    @staticmethod
+    def _adapter_on(port: int) -> WebhookAdapter:
+        return _make_adapter(
+            routes={"r1": {"secret": "real-secret-abc123", "prompt": "x"}},
+            host="127.0.0.1",
+            port=port,
+        )
+
+    @pytest.mark.macos_only  # the exclusive bind (reuse_address=False) is a Darwin-only path
+    @pytest.mark.asyncio
+    async def test_explicit_host_rebinds_over_time_wait(self):
+        """A port held only by a server-side TIME_WAIT socket must not block the bind."""
+        listener = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        listener.bind(("127.0.0.1", 0))
+        listener.listen(1)
+        port = listener.getsockname()[1]
+        client = socket.create_connection(("127.0.0.1", port))
+        accepted, _ = listener.accept()
+        accepted.close()  # the side closing first enters TIME_WAIT: the server side, as on gateway shutdown
+        client.close()
+        listener.close()
+        adapter = self._adapter_on(port)
+        try:
+            with patch.object(adapter, "_reload_dynamic_routes"):
+                assert await adapter.connect() is True
+            assert adapter.is_connected is True
+        finally:
+            await adapter.disconnect()
+
+    @pytest.mark.asyncio
+    async def test_explicit_host_still_rejects_live_listener(self):
+        """The TIME_WAIT retry must not weaken exclusivity: a live listener on the same address wins."""
+        blocker = await asyncio.start_server(
+            lambda _reader, _writer: None, host="127.0.0.1", port=0, reuse_address=False
+        )
+        port = blocker.sockets[0].getsockname()[1]
+        adapter = self._adapter_on(port)
+        try:
+            with patch.object(adapter, "_reload_dynamic_routes"):
+                assert await adapter.connect() is False
+            assert adapter._runner is None
+            assert adapter.is_connected is False
+        finally:
+            await adapter.disconnect()
+            blocker.close()
+            await blocker.wait_closed()
+
+
 # Regression coverage for #72041: profile-bound webhook authentication
 class TestMultiplexProfileWebhookAuthentication:
     @staticmethod

From 741d8db2dab320b709797c8847ef8cb7a120ced6 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 03:11:21 +0530
Subject: [PATCH 172/190] test(gateway): trim the TIME_WAIT rebind tests to the
 two invariants

The positive case (bind over a lingering server-side TIME_WAIT socket) lives
once, on the api_server adapter, since both adapters share start_tcp_site; the
webhook file keeps the negative case (a live listener still wins). That test
hung: the blocker never closed the probe connection server-side, so
`wait_closed()` waited forever.
---
 tests/gateway/test_webhook_adapter.py | 30 ++++-----------------------
 1 file changed, 4 insertions(+), 26 deletions(-)

diff --git a/tests/gateway/test_webhook_adapter.py b/tests/gateway/test_webhook_adapter.py
index 1ced2268af..01f81bb03f 100644
--- a/tests/gateway/test_webhook_adapter.py
+++ b/tests/gateway/test_webhook_adapter.py
@@ -966,10 +966,8 @@ class TestDualStackBind:
 
 
 class TestExclusiveBindTimeWait:
-    """macOS binds the listener with ``reuse_address=False`` (exclusive dual-stack bind). On BSD that
-    also refuses the port while a TIME_WAIT connection from the previous gateway lingers (2*MSL = 30s):
-    a ``/restart`` re-binds within seconds and used to fail with EADDRINUSE although nobody was
-    listening (observed on 127.0.0.1:8644; the reconnect watcher only recovered ~50s later)."""
+    """The TIME_WAIT rebind (positive case: tests/gateway/test_api_server_bind_guard.py, shared
+    ``start_tcp_site``) must not weaken the exclusive bind: a live listener still wins."""
 
     @staticmethod
     def _adapter_on(port: int) -> WebhookAdapter:
@@ -979,32 +977,12 @@ class TestExclusiveBindTimeWait:
             port=port,
         )
 
-    @pytest.mark.macos_only  # the exclusive bind (reuse_address=False) is a Darwin-only path
-    @pytest.mark.asyncio
-    async def test_explicit_host_rebinds_over_time_wait(self):
-        """A port held only by a server-side TIME_WAIT socket must not block the bind."""
-        listener = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-        listener.bind(("127.0.0.1", 0))
-        listener.listen(1)
-        port = listener.getsockname()[1]
-        client = socket.create_connection(("127.0.0.1", port))
-        accepted, _ = listener.accept()
-        accepted.close()  # the side closing first enters TIME_WAIT: the server side, as on gateway shutdown
-        client.close()
-        listener.close()
-        adapter = self._adapter_on(port)
-        try:
-            with patch.object(adapter, "_reload_dynamic_routes"):
-                assert await adapter.connect() is True
-            assert adapter.is_connected is True
-        finally:
-            await adapter.disconnect()
-
     @pytest.mark.asyncio
     async def test_explicit_host_still_rejects_live_listener(self):
         """The TIME_WAIT retry must not weaken exclusivity: a live listener on the same address wins."""
+        # The probe's connection must be closed server-side too, or ``wait_closed()`` never returns.
         blocker = await asyncio.start_server(
-            lambda _reader, _writer: None, host="127.0.0.1", port=0, reuse_address=False
+            lambda _reader, writer: writer.close(), host="127.0.0.1", port=0, reuse_address=False
         )
         port = blocker.sockets[0].getsockname()[1]
         adapter = self._adapter_on(port)

From aaaca43c842766d91ba53cfe063fc4f727332ebe Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 03:18:10 +0530
Subject: [PATCH 173/190] refactor(gateway): one wildcard-host predicate for
 the HTTP listeners

Gate review: tcp_site.py grew its own `_WILDCARD_HOSTS` that already diverged
from shared_ingress.py (dropped "*" and ""). One `is_wildcard_host` in
shared_ingress, used by both the TIME_WAIT rebind guard and
`listener_base_url`.
---
 gateway/platforms/shared_ingress.py |  7 ++++++-
 gateway/platforms/tcp_site.py       | 10 ++--------
 2 files changed, 8 insertions(+), 9 deletions(-)

diff --git a/gateway/platforms/shared_ingress.py b/gateway/platforms/shared_ingress.py
index ae3db657e6..8018ce1290 100644
--- a/gateway/platforms/shared_ingress.py
+++ b/gateway/platforms/shared_ingress.py
@@ -24,6 +24,11 @@ logger = logging.getLogger(__name__)
 _WILDCARD_HOSTS = frozenset({"", "0.0.0.0", "::", "*"})
 
 
+def is_wildcard_host(host: Any) -> bool:
+    """True for the dual-stack default (None/"") and the per-family wildcards."""
+    return host is None or str(host).strip() in _WILDCARD_HOSTS
+
+
 def shared_ingress_profile(adapter: Any) -> Optional[str]:
     """Profile name when *adapter* was constructed in shared-listener mode, else None."""
     return getattr(adapter, "_shared_listener_profile", None) or None
@@ -31,7 +36,7 @@ def shared_ingress_profile(adapter: Any) -> Optional[str]:
 
 def listener_base_url(host: Any, port: Any) -> str:
     """``http://host:port`` clients use to reach a listener bound on ``host`` (wildcards → loopback)."""
-    host = "127.0.0.1" if host is None or str(host).strip() in _WILDCARD_HOSTS else str(host)
+    host = "127.0.0.1" if is_wildcard_host(host) else str(host)
     if ":" in host and not host.startswith("["):
         host = f"[{host}]"
     return f"http://{host}:{port or 0}"
diff --git a/gateway/platforms/tcp_site.py b/gateway/platforms/tcp_site.py
index 6160075a5a..6be1aa63b2 100644
--- a/gateway/platforms/tcp_site.py
+++ b/gateway/platforms/tcp_site.py
@@ -10,16 +10,10 @@ from typing import Optional
 
 from aiohttp import web
 
+from gateway.platforms.shared_ingress import is_wildcard_host
+
 logger = logging.getLogger(__name__)
 
-_WILDCARD_HOSTS = frozenset({"0.0.0.0", "::"})
-
-
-def is_wildcard_host(host: Optional[str]) -> bool:
-    """True for the dual-stack default (None/"") and the per-family wildcards."""
-    return not host or host.strip() in _WILDCARD_HOSTS
-
-
 def has_live_listener(host: str, port: int) -> bool:
     """Blocking probe: True when something accepts connections on ``host:port``. Refused = nobody listens;
     any other failure (timeout, unroutable) is treated as live so the caller stays exclusive."""

From f59c451f818de9498ac655a06ade114cb081f4e2 Mon Sep 17 00:00:00 2001
From: LeonSGP43 <cine.dreamer.one@gmail.com>
Date: Wed, 6 May 2026 12:40:48 +0800
Subject: [PATCH 174/190] fix(feishu): avoid threading regular replies

---
 plugins/platforms/feishu/adapter.py |  5 ++-
 tests/gateway/test_feishu.py        | 57 +++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+), 1 deletion(-)

diff --git a/plugins/platforms/feishu/adapter.py b/plugins/platforms/feishu/adapter.py
index aa6ec796de..05e8d541c7 100644
--- a/plugins/platforms/feishu/adapter.py
+++ b/plugins/platforms/feishu/adapter.py
@@ -2588,7 +2588,10 @@ class FeishuAdapter(BasePlatformAdapter):
             if hint:
                 text = f"{hint}\n\n{text}" if text else hint
 
-        thread_id = getattr(message, "thread_id", None) or getattr(message, "root_id", None) or None
+        # Only a native ``thread_id`` marks a topic. ``root_id`` is present on every quoted reply
+        # too, so using it as a fallback (#19711) turned ordinary quote replies into topic
+        # sessions and pushed the bot's answer into a fresh thread (#20548).
+        thread_id = getattr(message, "thread_id", None) or None
         reply_to_message_id = (
             getattr(message, "parent_id", None) or getattr(message, "upper_message_id", None)
             or getattr(message, "root_id", None) or None
diff --git a/tests/gateway/test_feishu.py b/tests/gateway/test_feishu.py
index 490e9fff00..062e192c69 100644
--- a/tests/gateway/test_feishu.py
+++ b/tests/gateway/test_feishu.py
@@ -2528,6 +2528,63 @@ class TestFeishuProcessInboundMessage(unittest.TestCase):
         self.assertNotIn("[Mentioned:", event.text)
         self.assertTrue(event.text.startswith("/model"))
 
+    def test_regular_reply_root_id_does_not_become_thread_id(self):
+        adapter = self._build_adapter()
+        adapter._fetch_message_text = AsyncMock(return_value="parent text")
+        message = SimpleNamespace(
+            content=json.dumps({"text": "regular reply"}),
+            message_type="text",
+            message_id="m6",
+            mentions=[],
+            chat_id="oc_chat",
+            parent_id=None,
+            upper_message_id=None,
+            root_id="om_root",
+            thread_id=None,
+        )
+
+        asyncio.run(
+            adapter._process_inbound_message(
+                data=message,
+                message=message,
+                sender_id=None,
+                chat_type="group",
+                message_id="m6",
+            )
+        )
+
+        adapter.build_source.assert_called_once()
+        self.assertIsNone(adapter.build_source.call_args.kwargs["thread_id"])
+        event = adapter._dispatch_inbound_event.call_args.args[0]
+        self.assertEqual(event.reply_to_message_id, "om_root")
+        self.assertEqual(event.reply_to_text, "parent text")
+
+    def test_explicit_thread_id_is_preserved(self):
+        adapter = self._build_adapter()
+        message = SimpleNamespace(
+            content=json.dumps({"text": "thread reply"}),
+            message_type="text",
+            message_id="m7",
+            mentions=[],
+            chat_id="oc_chat",
+            parent_id=None,
+            upper_message_id=None,
+            root_id="om_root",
+            thread_id="omt_thread",
+        )
+
+        asyncio.run(
+            adapter._process_inbound_message(
+                data=message,
+                message=message,
+                sender_id=None,
+                chat_type="group",
+                message_id="m7",
+            )
+        )
+
+        adapter.build_source.assert_called_once()
+        self.assertEqual(adapter.build_source.call_args.kwargs["thread_id"], "omt_thread")
 
 class TestFeishuFetchMessageText(unittest.TestCase):
     def _build_adapter(self):

From 3ed40556cea130611b73ba9dce996ca898f50745 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 15:02:19 -0700
Subject: [PATCH 175/190] fix(profiles): a child spawned for another profile no
 longer inherits the spawner's authorization gates
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A `hermes -p B` child built from a process that loaded profile A's env (a gateway, the
dashboard, the post-update fleet restart) started with A's `DISCORD_ALLOWED_CHANNELS`,
`TELEGRAM_GROUP_ALLOWED_CHATS`, `GATEWAY_ALLOW_ALL_USERS`... and enforced them as its
own: gates are not credentials (no secret scrub sees them), a unit-file `Environment=`
or operator export is in no dotenv (no name-list strip sees them), and B's own `.env`
rarely defines the key (its dotenv load never overwrites the inherited value). Observed
as profile B's gateway rejecting every message in B's own channel after a per-profile
restart issued from A (#113270).

- `local_env_policy.is_profile_gate_env` / `strip_profile_gate_env`: gates matched by
  shape (`_ALLOWED_`, `_ALLOW_ALL_`, `_ALLOW_FROM`, `_ALLOW_BOTS`, `_IGNORED_CHANNELS`,
  ...), never `HERMES_*`, so a gate added to any adapter is covered without a second edit.
- `strip_launch_profile_env` drops them on its existing routed-home branch: the seam
  `served_profile_child_env`, the kanban dispatcher, cron workers and the dashboard
  action env already funnel through (the dashboard site now calls it for its target).
  Same-home children keep an operator export.
- `update_restart_recovery._child_environment(profile)`: the one site that bypassed
  every helper (bare `os.environ.copy()` relaunching EVERY profile) strips gates when
  the profile is not the one the updater runs as; the module stays stdlib-only at
  import time.

Live: fresh-process `hermes_cli.update_restart_recovery --stdin` with three gates in
the updater env — base hands all three to profile b's relaunch, fixed hands none and
keeps them for the launch profile.

Refs #113270; supersedes #113308 (@yashraj4, static key list + always-strip; this keeps
same-profile children intact and covers the per-adapter gate set).
---
 hermes_cli/update_restart_recovery.py         | 27 +++++++-
 hermes_cli/web_server_gateway.py              |  6 +-
 .../tools/test_profile_gate_env_isolation.py  | 69 +++++++++++++++++++
 tools/environments/local.py                   |  7 +-
 tools/environments/local_env_policy.py        | 31 +++++++++
 .../docs/user-guide/multi-profile-gateways.md |  1 +
 6 files changed, 135 insertions(+), 6 deletions(-)
 create mode 100644 tests/tools/test_profile_gate_env_isolation.py

diff --git a/hermes_cli/update_restart_recovery.py b/hermes_cli/update_restart_recovery.py
index 547b7bb06e..7add7fe0f0 100644
--- a/hermes_cli/update_restart_recovery.py
+++ b/hermes_cli/update_restart_recovery.py
@@ -89,18 +89,39 @@ def _succeeded(result: Any) -> bool:
     return result is not None and getattr(result, "returncode", 1) == 0
 
 
-def _child_environment() -> dict[str, str]:
-    """Return an environment that cannot self-identify as the gateway owner."""
+def _launch_profile() -> str:
+    """Profile this recovery process was launched as: ``<root>/profiles/<name>`` in ``HERMES_HOME`` names it,
+    anything else is the default profile. Mirrors ``hermes_cli.profiles.profile_root_for_env_home`` without
+    importing it — this module stays stdlib-only at import time."""
+    home = os.environ.get("HERMES_HOME", "").strip()
+    if home:
+        path = os.path.normpath(home)
+        if os.path.basename(os.path.dirname(path)) == "profiles":
+            return os.path.basename(path)
+    return "default"
+
+
+def _child_environment(profile: str | None = None) -> dict[str, str]:
+    """Return an environment that cannot self-identify as the gateway owner.
+
+    One updater environment relaunches EVERY profile, so a child for another profile would inherit
+    this process's authorization gates (``DISCORD_ALLOWED_CHANNELS``, ``GATEWAY_ALLOW_ALL_USERS`` ...)
+    and enforce them as its own — its ``.env`` only overwrites the keys it defines (#113270). Gates are
+    dropped when *profile* is not the launch profile; a same-profile child keeps an operator export.
+    """
     env = os.environ.copy()
     for marker in _GATEWAY_MARKERS:
         env.pop(marker, None)
     env[_RECOVERY_ENV] = "1"
+    if profile is not None and profile != _launch_profile():
+        from tools.environments.local_env_policy import strip_profile_gate_env
+        strip_profile_gate_env(env)
     return env
 
 
 def _run_profile_restart(profile: str, *, run: Callable[..., Any]) -> bool:
     """Run one profile restart without inheriting the updater's process state."""
-    kwargs: dict[str, Any] = {"stdin": subprocess.DEVNULL, "env": _child_environment()}
+    kwargs: dict[str, Any] = {"stdin": subprocess.DEVNULL, "env": _child_environment(profile)}
     if os.name == "nt":
         kwargs["creationflags"] = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0) | getattr(subprocess, "DETACHED_PROCESS", 0)
     else:
diff --git a/hermes_cli/web_server_gateway.py b/hermes_cli/web_server_gateway.py
index cc9c94ab5a..41c5c14354 100644
--- a/hermes_cli/web_server_gateway.py
+++ b/hermes_cli/web_server_gateway.py
@@ -362,7 +362,7 @@ def _profile_action_environment(
         )
         from hermes_cli.web_server_profiles import _resolve_profile_dir
         from hermes_constants import apply_subprocess_home_env, get_default_hermes_root
-        from tools.environments.local import build_subprocess_env
+        from tools.environments.local import build_subprocess_env, strip_launch_profile_env
 
         target_home = _resolve_profile_dir(profile)
         action_env = build_subprocess_env(base=os.environ, scrub_secrets=True)
@@ -379,6 +379,10 @@ def _profile_action_environment(
             profile_keys.update(get_secret_source_values(source_home).keys())
         for key in profile_keys:
             action_env.pop(key, None)
+        # Authorization gates that reached this process outside any dotenv (unit-file
+        # ``Environment=``, an operator export) are not in ``profile_keys``; the target
+        # profile's ``.env`` rarely defines them, so they would survive into the child (#113270).
+        strip_launch_profile_env(action_env, target_home)
 
         # Pin the child before import-time startup runs; the explicit -p flag stays authoritative
         # and resolves to the same validated directory.
diff --git a/tests/tools/test_profile_gate_env_isolation.py b/tests/tools/test_profile_gate_env_isolation.py
new file mode 100644
index 0000000000..e0d5b23f5a
--- /dev/null
+++ b/tests/tools/test_profile_gate_env_isolation.py
@@ -0,0 +1,69 @@
+"""A child spawned FOR another profile never inherits this process's authorization gates (#113270).
+
+``DISCORD_ALLOWED_CHANNELS`` / ``TELEGRAM_GROUP_ALLOWED_CHATS`` / ``GATEWAY_ALLOW_ALL_USERS``-class names
+decide WHO may talk to the agent. They are not credentials (no secret scrub sees them), a unit-file
+``Environment=`` or operator export never appears in the launch ``.env`` (no name list sees them), and
+the target profile's own ``.env`` rarely defines them (its dotenv load never overwrites them) — so a
+``hermes -p B`` child built from profile A's process enforced A's channel list as its own.
+"""
+
+import json
+import os
+import subprocess
+import sys
+
+import pytest
+
+from tools.environments.local import served_profile_child_env
+
+# Gates injected outside any dotenv — the shape a name-list scrub cannot see. Mix of allowlist,
+# deny list, allow-all opt-in, bot policy, channel scoping and a plugin adapter's gate.
+_GATES = {
+    "DISCORD_ALLOWED_CHANNELS": "111", "DISCORD_ALLOWED_ROLES": "r1", "DISCORD_IGNORED_CHANNELS": "222",
+    "DISCORD_ALLOW_BOTS": "all", "TELEGRAM_GROUP_ALLOWED_CHATS": "-100", "SLACK_ALLOWED_CHANNELS": "C1",
+    "WHATSAPP_GROUP_ALLOW_FROM": "+1555", "GATEWAY_ALLOW_ALL_USERS": "true",
+}
+_PROBE = "import json,os;print(json.dumps({k:os.environ.get(k) for k in %r}))" % sorted(_GATES)
+
+
+def _seen_by_child(env: dict) -> set[str]:
+    out = subprocess.run([sys.executable, "-c", _PROBE], env=env, capture_output=True,
+                         text=True, encoding="utf-8", errors="replace", timeout=60)
+    return {k for k, v in json.loads(out.stdout.strip().splitlines()[-1]).items() if v is not None}
+
+
+@pytest.fixture
+def homes(tmp_path, monkeypatch):
+    """Launch home A (the process's HERMES_HOME) and routed home B; gates in the process env only."""
+    a = tmp_path / ".hermes"
+    b = a / "profiles" / "b"
+    b.mkdir(parents=True)
+    (a / ".env").write_text("A_MARKER=a\n", encoding="utf-8")
+    (b / ".env").write_text("B_MARKER=b\n", encoding="utf-8")
+    monkeypatch.setenv("HERMES_HOME", str(a))
+    for key, value in _GATES.items():
+        monkeypatch.setenv(key, value)
+    return a, b
+
+
+def test_routed_child_drops_gates_and_same_home_child_keeps_them(homes):
+    """The seam every served-profile spawn funnels through: routed target → no gate reaches the child
+    (observed from INSIDE a real child); same-home target → an operator export is preserved."""
+    a, b = homes
+    assert _seen_by_child(served_profile_child_env(base=os.environ, target_home=b)) == set()
+    assert _seen_by_child(served_profile_child_env(base=os.environ, target_home=a)) == set(_GATES)
+
+
+def test_update_recovery_child_env_drops_gates_only_for_other_profiles(homes):
+    """The updater relaunches EVERY profile from one environment; the per-profile child env must
+    strip gates for a foreign profile and keep them for the profile the updater itself runs as."""
+    from hermes_cli import update_restart_recovery as recovery
+
+    routed = recovery._child_environment("b")
+    same = recovery._child_environment("default")
+    assert not any(key in routed for key in _GATES)
+    assert all(same[key] == value for key, value in _GATES.items())
+    # The recovery marker and the gateway-owner scrub are unchanged on both.
+    for env in (routed, same):
+        assert env[recovery._RECOVERY_ENV] == "1"
+        assert not any(marker in env for marker in recovery._GATEWAY_MARKERS)
diff --git a/tools/environments/local.py b/tools/environments/local.py
index 5cede7739a..d165ce6107 100644
--- a/tools/environments/local.py
+++ b/tools/environments/local.py
@@ -23,7 +23,7 @@ from hermes_cli._subprocess_compat import windows_hide_flags
 from tools.environments.local_env_policy import (
     _ALWAYS_STRIP_KEYS, _HERMES_PROVIDER_ENV_BLOCKLIST, _HERMES_PROVIDER_ENV_FORCE_PREFIX,
     _is_hermes_internal_secret, _is_terminal_first_party_env,
-    _matches_terminal_first_party_prefix, _plugin_terminal_env_strip_keys)
+    _matches_terminal_first_party_prefix, _plugin_terminal_env_strip_keys, strip_profile_gate_env)
 from tools.environments.local_gitbash_probe import (
     _bash_probe_details_cache, _bash_starts, _git_bash_aslr_help,
     _looks_like_msys_spawn_failure, _mandatory_aslr_enabled)
@@ -426,7 +426,10 @@ def strip_launch_profile_env(env: dict, target_home: "str | Path | None" = None)
     for key in set(load_env_file(launch_home / ".env")) | set(TERMINAL_CONFIG_ENV_MAP.values()):
         if not _is_global_env(key) or key.startswith("TERMINAL_"):
             env.pop(key, None)
-    return env
+    # Authorization gates are the one residue a name list cannot see: a unit-file ``Environment=``
+    # or an operator export never appears in the launch ``.env``, the secret scrub ignores
+    # non-credentials, and the target's own ``.env`` rarely defines the key to overwrite it (#113270).
+    return strip_profile_gate_env(env)
 
 
 # --- Shell discovery ---
diff --git a/tools/environments/local_env_policy.py b/tools/environments/local_env_policy.py
index d11d2f45d4..f392a8c538 100644
--- a/tools/environments/local_env_policy.py
+++ b/tools/environments/local_env_policy.py
@@ -181,6 +181,37 @@ def _is_hermes_internal_secret(key: str) -> bool:
     return upper.startswith("GATEWAY_RELAY_") and upper.endswith(("_SECRET", "_KEY", "_TOKEN"))
 
 
+# Authorization gates: the env names platform adapters read to decide WHO may talk to the
+# agent (allow/deny lists, allow-all opt-ins, bot policy, channel scoping). Not credentials, so
+# no secret scrub touches them, and most profiles' ``.env`` files do not define them, so the
+# child's own dotenv load never overwrites an inherited value: a child spawned FOR profile B
+# from a process that loaded profile A's gates (or a unit-file ``Environment=``) would enforce
+# A's channel/user/role list as its own (#113270). Matched by shape so a gate added to any
+# adapter is covered without a second edit; ``HERMES_*`` never counts (``HERMES_MEDIA_ALLOW_DIRS``,
+# ``HERMES_ALLOW_PRIVATE_URLS`` are process settings, not adapter gates).
+_PROFILE_GATE_ENV_MARKERS = (
+    "_ALLOWED_", "_ALLOW_ALL_", "_ALLOW_FROM", "_ALLOW_BOTS", "_ALLOW_PUBLIC_", "_IGNORED_CHANNELS",
+    "_NO_THREAD_CHANNELS", "_FREE_RESPONSE_CHANNELS", "_BACKFILL_CHANNELS", "_GROUP_ALLOWED",
+)
+
+
+def is_profile_gate_env(name: str) -> bool:
+    """True for a platform authorization gate (``DISCORD_ALLOWED_CHANNELS``, ``TELEGRAM_ALLOW_ALL_USERS``,
+    ``GATEWAY_ALLOWED_USERS``, ``WHATSAPP_GROUP_ALLOW_FROM`` ...) — profile-scoped policy a child acting
+    for ANOTHER profile must never inherit."""
+    upper = name.upper()
+    if upper.startswith("HERMES_") or upper.startswith("_"):
+        return False
+    return any(marker in upper for marker in _PROFILE_GATE_ENV_MARKERS)
+
+
+def strip_profile_gate_env(env: dict) -> dict:
+    """Drop every authorization gate from *env* in place (see :func:`is_profile_gate_env`)."""
+    for key in [k for k in env if is_profile_gate_env(k)]:
+        del env[key]
+    return env
+
+
 def _plugin_terminal_env_strip_keys() -> frozenset:
     """Credential env keys owned by plugin-registered terminal backends (Tier-1:
     stripped from every spawned subprocess). Computed at call time because plugins
diff --git a/website/docs/user-guide/multi-profile-gateways.md b/website/docs/user-guide/multi-profile-gateways.md
index 38d9345eb8..a872af3600 100644
--- a/website/docs/user-guide/multi-profile-gateways.md
+++ b/website/docs/user-guide/multi-profile-gateways.md
@@ -465,6 +465,7 @@ profile and never shares with the default or any sibling:
 | MCP connections in the Desktop/dashboard backend and the per-profile cron ticker | Keyed per served profile even with `gateway.multiplex_profiles` off — same rule as the multiplexer | A same-named `mcp_servers` entry with other credentials is its own connection; a served profile never calls a server as another profile |
 | Dashboard actions (`hermes -p <name> …` spawned by the Desktop/dashboard) | A scrubbed child env pinned to that profile's `HERMES_HOME` | The child loads its own `.env`; the dashboard profile's tokens and ports are not inherited |
 | Every child that acts for a served profile (slash worker, Bot Chat delivery, A2A forward, `key_cmd` helper, browser driver) | That profile's own `.env` + secret sources over a credential-scrubbed base — with or without `gateway.multiplex_profiles` (the Desktop/dashboard `?profile=` route counts) | Absent from the child — a key that reached the launch process only through systemd / Compose / the shell is never inherited by another profile's child |
+| Authorization gates in a child spawned for another profile (`*_ALLOWED_USERS` / `*_ALLOWED_CHANNELS` / `*_IGNORED_CHANNELS` / `*_ALLOW_ALL_USERS` / `*_ALLOW_BOTS`, `GATEWAY_ALLOW*`) — dashboard `hermes -p <name>` actions, kanban workers, Bot Chat delivery, the post-update per-profile `gateway restart` | The child's own `.env` / `config.yaml`, loaded by the child itself | Closed (the adapter's documented default) — a gate exported into the spawning process by a unit file or the shell is dropped before the child starts, so profile B never enforces profile A's channel or user list; a same-profile child keeps it |
 | The launch (default) profile's own credentials in a `hermes serve` / dashboard process that also serves another profile | Its `.env` + secret sources over the process env **frozen the moment the first other profile is served**; not re-read afterwards | A credential rotated only in the process env (`systemctl set-environment`, a refreshed `op run` wrapper that did not re-exec) is not picked up until the process restarts — put rotating keys in `.env` or a secret source, or restart after rotating |
 | Cron `.env` tuning (`HERMES_CRON_TIMEOUT`, `HERMES_MODEL` fallback, `HERMES_CRON_MAX_PARALLEL`, prefill file), worker / Bot Chat child env | The profile's own `.env`; children never inherit the default profile's `.env` settings or bridged `TERMINAL_*` policy | Cron defaults / model refusal, exactly as a standalone `hermes -p <name> gateway run` |
 | Kanban workers and notifications for a profile's tasks | The assignee's `.env` + `config.yaml` (toolset pin, terminal backend, media policy, display language) | — |

From fbe85963de20855214ffdfd3cc1ee76e81bcf2fb Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 14:22:43 -0700
Subject: [PATCH 176/190] fix(tui): session-bound config.set persists into the
 session profile, not the launch profile

Desktop app-global remote mode and the Ink TUI send `config.set` with `session_id` and no
`profile` param. `@_profile_scoped` only bound `params["profile"]`, so a write from a focused
worker session round-tripped `_load_cfg_raw()`/`_save_cfg()` against the LAUNCH profile's
config.yaml while the worker profile kept its old value (and reverted on restart).

The decorator now falls back to the named session's `profile_home` when `profile` is absent,
binding the full runtime scope (home + secrets + terminal) the same way an explicit profile
does. `config.set cwd` from a profile-bound session no longer publishes `TERMINAL_CWD` into
the shared process env (that variable belongs to the launch profile).

Closes #85669. Supersedes #85676 (its diff predates the methods_* split).

Co-authored-by: worlldz <cryptoworlldz@gmail.com>
---
 .../test_config_set_session_profile_scope.py  | 64 +++++++++++++++++++
 tui_gateway/methods_config_set.py             |  5 +-
 tui_gateway/server.py                         | 15 ++++-
 3 files changed, 81 insertions(+), 3 deletions(-)
 create mode 100644 tests/tui_gateway/test_config_set_session_profile_scope.py

diff --git a/tests/tui_gateway/test_config_set_session_profile_scope.py b/tests/tui_gateway/test_config_set_session_profile_scope.py
new file mode 100644
index 0000000000..67c7a213e4
--- /dev/null
+++ b/tests/tui_gateway/test_config_set_session_profile_scope.py
@@ -0,0 +1,64 @@
+"""``config.set`` bound by ``session_id`` alone persists into the session's profile (issue #85669).
+
+Desktop app-global remote mode and the Ink TUI send ``config.set`` with ``session_id`` and no
+``profile`` param. The session record carries ``profile_home``; a write that ignores it lands in
+the launch profile's config.yaml while the focused profile silently keeps its old value.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+import yaml
+
+import tui_gateway.server as server
+
+
+def _write_cfg(home: Path, busy: str, approvals: str) -> None:
+    home.mkdir(parents=True, exist_ok=True)
+    (home / "config.yaml").write_text(
+        yaml.safe_dump({"display": {"busy_input_mode": busy}, "approvals": {"mode": approvals}}),
+        encoding="utf-8",
+    )
+
+
+def _read(home: Path) -> dict:
+    return yaml.safe_load((home / "config.yaml").read_text(encoding="utf-8")) or {}
+
+
+@pytest.fixture
+def homes(tmp_path, monkeypatch):
+    launch, worker = tmp_path / "launch", tmp_path / "profiles" / "worker"
+    _write_cfg(launch, "queue", "manual")
+    _write_cfg(worker, "queue", "manual")
+    monkeypatch.setenv("HERMES_HOME", str(launch))
+    monkeypatch.setattr(server, "_hermes_home", launch)
+    monkeypatch.setattr(server, "_cfg_cache", None)
+    monkeypatch.setattr(server, "_cfg_sig", None)
+    monkeypatch.setattr(server, "_cfg_path", None)
+    monkeypatch.setattr(server, "_emit", lambda *a, **k: None)
+    return launch, worker
+
+
+@pytest.mark.parametrize(
+    ("key", "value", "section", "field"),
+    [("busy", "steer", "display", "busy_input_mode"), ("approval_mode", "off", "approvals", "mode")],
+)
+def test_session_bound_config_set_writes_the_session_profile(homes, key, value, section, field):
+    launch, worker = homes
+    session = {"agent": None, "profile_home": str(worker), "session_key": "worker-session"}
+    with patch.dict(server._sessions, {"s-worker": session}, clear=False):
+        resp = server._methods["config.set"]("rid", {"session_id": "s-worker", "key": key, "value": value})
+    assert resp["result"]["value"] == value
+    assert _read(worker)[section][field] == value
+    assert _read(launch)[section][field] != value
+
+
+def test_unbound_config_set_still_writes_the_launch_profile(homes):
+    launch, worker = homes
+    resp = server._methods["config.set"]("rid", {"key": "busy", "value": "steer"})
+    assert resp["result"]["value"] == "steer"
+    assert _read(launch)["display"]["busy_input_mode"] == "steer"
+    assert _read(worker)["display"]["busy_input_mode"] == "queue"
diff --git a/tui_gateway/methods_config_set.py b/tui_gateway/methods_config_set.py
index 583112df83..eeb83c24e8 100644
--- a/tui_gateway/methods_config_set.py
+++ b/tui_gateway/methods_config_set.py
@@ -414,7 +414,10 @@ def _set_cwd(rid, params, key, value, session):
     if not os.path.isdir(cwd):
         return _err(rid, 4002, f"working directory does not exist: {raw}")
     _write_config_key("terminal.cwd", cwd)
-    os.environ["TERMINAL_CWD"] = cwd
+    # ``TERMINAL_CWD`` is the LAUNCH process's; a profile-bound session persists its cwd through its
+    # own config.yaml (written above under the session scope) and must not leak it into other profiles.
+    if not (isinstance(session, dict) and session.get("profile_home")):
+        os.environ["TERMINAL_CWD"] = cwd
     return _kv(rid, "terminal.cwd", cwd, cwd=cwd, branch=git_probe.branch(cwd))
 
 
diff --git a/tui_gateway/server.py b/tui_gateway/server.py
index 47c7c21f90..40bf6bcb17 100644
--- a/tui_gateway/server.py
+++ b/tui_gateway/server.py
@@ -553,10 +553,21 @@ def _profile_scoped(handler):
     systemd / ``op run`` injection); once multiplexing is active it binds its own scope from the env
     frozen at activation (``_session_profile_runtime_scope``), never ambient state a secondary context
     might have poisoned (#107422).
+
+    No ``profile`` param but a ``session_id`` naming a live session: that session's ``profile_home``
+    is the scope. The TUI and the Desktop's ambient dispatcher send session-bound RPCs with the
+    session id alone, so a ``config.set`` from a focused worker session otherwise persisted into the
+    LAUNCH profile's config.yaml while the worker's stayed unchanged (#85669).
     """
     def wrapper(rid, params):
-        home = _profile_home(params.get("profile") if isinstance(params, dict) else None)
-        with _session_profile_runtime_scope({"profile_home": str(home) if home else None}):
+        p = params if isinstance(params, dict) else {}
+        if str(p.get("profile") or "").strip():
+            home = _profile_home(p.get("profile"))
+            profile_home = str(home) if home else None
+        else:
+            session = _sessions.get(str(p.get("session_id") or ""))
+            profile_home = session.get("profile_home") if isinstance(session, dict) else None
+        with _session_profile_runtime_scope({"profile_home": profile_home or None}):
             return handler(rid, params)
     return wrapper
 

From a8cccc22f2c20c2574cd7a7eea8f965acc42cf19 Mon Sep 17 00:00:00 2001
From: liguoyu <guoyu.li@lcfuturecenter.com>
Date: Fri, 18 Sep 2026 14:26:20 -0700
Subject: [PATCH 177/190] fix(dashboard): profile-less chat deep links inherit
 the launcher's preselected profile
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`hermes dashboard` from a named profile re-execs as `-p default dashboard --open-profile P`,
but `--open-profile` only reached the one URL `_maybe_open_browser()` opened. A `/chat?resume=<id>`
deep link without `?profile=` initialised `ProfileProvider` with the empty (launch) scope, so the
embedded chat ran in the default profile — no MCP servers, wrong model/skills — while the switcher
showed P. No error, no indication.

The server now records `initial_profile` on `app.state` and injects it into the SPA bootstrap as
`window.__HERMES_INITIAL_PROFILE__` (escaped for the script context); the Vite dev proxy forwards
it. `ProfileProvider` uses it only when the URL carries no `profile` param: an explicit
`?profile=` (including an explicit empty one) still wins, and the sticky-active-profile alignment
no longer replaces a launch-preselected scope.

Closes #73085. Salvage of #73260 (cherry-pick of 99e341cdef0 resolved onto the split
web_server_dashboard.py; start_server assertion dropped as a change-detector).
---
 hermes_cli/web_server.py                      |  3 ++
 hermes_cli/web_server_dashboard.py            |  4 ++
 ...est_dashboard_initial_profile_bootstrap.py | 47 +++++++++++++++++++
 web/src/contexts/ProfileProvider.tsx          | 29 ++++++++----
 web/src/lib/profile-bootstrap.test.ts         | 40 ++++++++++++++++
 web/src/lib/profile-bootstrap.ts              | 31 ++++++++++++
 web/vite.config.ts                            | 11 +++--
 7 files changed, 154 insertions(+), 11 deletions(-)
 create mode 100644 tests/hermes_cli/test_dashboard_initial_profile_bootstrap.py
 create mode 100644 web/src/lib/profile-bootstrap.test.ts
 create mode 100644 web/src/lib/profile-bootstrap.ts

diff --git a/hermes_cli/web_server.py b/hermes_cli/web_server.py
index fad9a5cfbb..2a57daa3d4 100644
--- a/hermes_cli/web_server.py
+++ b/hermes_cli/web_server.py
@@ -1418,6 +1418,9 @@ def start_server(
     # host_header_middleware validates Host against this (DNS rebinding,
     # GHSA-ppp5-vxwm-4cf7).
     app.state.bound_host = host
+    # The SPA bootstrap reads this so profile-less deep links (/chat?resume=<id>) inherit the
+    # launcher's preselected profile instead of silently running in the launch scope (#73085).
+    app.state.initial_profile = str(initial_profile or "")
 
     config, server = _build_uvicorn_server(host, port, ssh_isolated=bool(ssh_session_token))
 
diff --git a/hermes_cli/web_server_dashboard.py b/hermes_cli/web_server_dashboard.py
index 7e602279b0..dddfd13317 100644
--- a/hermes_cli/web_server_dashboard.py
+++ b/hermes_cli/web_server_dashboard.py
@@ -153,11 +153,15 @@ def mount_spa(application: FastAPI):
         chat_js = "true" if _DASHBOARD_EMBEDDED_CHAT_ENABLED else "false"
         gated = bool(getattr(app.state, "auth_required", False))
         token_js = "" if gated else f'window.__HERMES_SESSION_TOKEN__="{_server()._SESSION_TOKEN}";'
+        # Launcher-preselected profile (``--open-profile``): the SPA's fallback scope when the URL
+        # omits ``?profile=`` (#73085). ``</`` escaped so a hostile name cannot close the script tag.
+        initial_profile_js = json.dumps(str(getattr(application.state, "initial_profile", "") or "")).replace("</", "<\\/")
         bootstrap_script = (
             f"<script>{token_js}"
             f"window.__HERMES_DASHBOARD_EMBEDDED_CHAT__={chat_js};"
             f'window.__HERMES_BASE_PATH__="{prefix}";'
             f"window.__HERMES_AUTH_REQUIRED__={'true' if gated else 'false'};"
+            f"window.__HERMES_INITIAL_PROFILE__={initial_profile_js};"
             f"</script>"
         )
         if prefix:
diff --git a/tests/hermes_cli/test_dashboard_initial_profile_bootstrap.py b/tests/hermes_cli/test_dashboard_initial_profile_bootstrap.py
new file mode 100644
index 0000000000..711f182c81
--- /dev/null
+++ b/tests/hermes_cli/test_dashboard_initial_profile_bootstrap.py
@@ -0,0 +1,47 @@
+from fastapi import FastAPI
+from starlette.testclient import TestClient
+
+from hermes_cli import web_server
+
+
+def test_spa_bootstrap_includes_dashboard_initial_profile(tmp_path, monkeypatch):
+    dist = tmp_path / "web_dist"
+    (dist / "assets").mkdir(parents=True)
+    (dist / "index.html").write_text(
+        "<html><head></head><body>Dashboard</body></html>",
+        encoding="utf-8",
+    )
+    monkeypatch.setattr(web_server, "WEB_DIST", dist)
+    monkeypatch.delenv("HERMES_SERVE_HEADLESS", raising=False)
+
+    app = FastAPI()
+    app.state.initial_profile = "worker_x"
+    web_server.mount_spa(app)
+
+    response = TestClient(app).get("/chat?resume=session-1")
+
+    assert response.status_code == 200
+    assert 'window.__HERMES_INITIAL_PROFILE__="worker_x";' in response.text
+
+
+def test_spa_bootstrap_escapes_initial_profile_for_script_context(
+    tmp_path, monkeypatch
+):
+    dist = tmp_path / "web_dist"
+    (dist / "assets").mkdir(parents=True)
+    (dist / "index.html").write_text(
+        "<html><head></head><body>Dashboard</body></html>",
+        encoding="utf-8",
+    )
+    monkeypatch.setattr(web_server, "WEB_DIST", dist)
+    monkeypatch.delenv("HERMES_SERVE_HEADLESS", raising=False)
+
+    app = FastAPI()
+    app.state.initial_profile = "bad</script><script>alert(1)</script>"
+    web_server.mount_spa(app)
+
+    response = TestClient(app).get("/chat")
+
+    assert response.status_code == 200
+    assert "bad<\\/script><script>alert(1)<\\/script>" in response.text
+    assert "bad</script><script>alert(1)</script>" not in response.text
diff --git a/web/src/contexts/ProfileProvider.tsx b/web/src/contexts/ProfileProvider.tsx
index df2f02106c..8c1adaff2a 100644
--- a/web/src/contexts/ProfileProvider.tsx
+++ b/web/src/contexts/ProfileProvider.tsx
@@ -8,6 +8,11 @@ import {
 import { useLocation, useSearchParams } from "react-router";
 import { api, setManagementProfile } from "@/lib/api";
 import { ProfileContext } from "@/contexts/profile-context";
+import {
+  dashboardInitialProfile,
+  initialProfileScope,
+  shouldAdoptActiveProfile,
+} from "@/lib/profile-bootstrap";
 
 /**
  * Machine-level management-profile scope.
@@ -38,11 +43,13 @@ export function ProfileProvider({ children }: { children: ReactNode }) {
   const { pathname } = useLocation();
   const [profiles, setProfiles] = useState<string[]>([]);
   const [currentProfile, setCurrentProfile] = useState("default");
+  const bootstrapProfile = dashboardInitialProfile();
 
-  // Initial value comes from the URL (deep link / refresh / unified-launch
-  // preselect); afterwards state leads and the URL follows.
+  // An explicit URL wins; profile-less deep links inherit the unified-launch
+  // preselection injected by the server. Afterwards state leads and the URL
+  // follows.
   const [profile, setProfileState] = useState(
-    () => searchParams.get("profile") ?? "",
+    () => initialProfileScope(searchParams, bootstrapProfile),
   );
 
   // Mirror into the api module synchronously on every render where it
@@ -92,11 +99,17 @@ export function ProfileProvider({ children }: { children: ReactNode }) {
         const active = info.active || "default";
         setCurrentProfile(current);
 
-        // Deep links (?profile=) win. Otherwise align the switcher with the
-        // sticky active profile so Chat and management pages match what the
-        // Profiles page shows as "active" (machine dashboard runs as
-        // `current`, usually default).
-        if (urlProfile === null && active !== current) {
+        // Explicit URL and unified-launch bootstrap scopes win. Without
+        // either, align the switcher with the sticky active profile so Chat
+        // and management pages match what Profiles shows as "active".
+        if (
+          shouldAdoptActiveProfile(
+            urlProfile,
+            bootstrapProfile,
+            current,
+            active,
+          )
+        ) {
           setManagementProfile(active);
           setProfileState(active);
         }
diff --git a/web/src/lib/profile-bootstrap.test.ts b/web/src/lib/profile-bootstrap.test.ts
new file mode 100644
index 0000000000..583af2e9f5
--- /dev/null
+++ b/web/src/lib/profile-bootstrap.test.ts
@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  initialProfileScope,
+  shouldAdoptActiveProfile,
+} from "./profile-bootstrap";
+
+describe("initialProfileScope", () => {
+  it("inherits the dashboard bootstrap profile when the URL omits profile", () => {
+    expect(initialProfileScope(new URLSearchParams("resume=session-1"), "worker_x"))
+      .toBe("worker_x");
+  });
+
+  it("keeps an explicit URL profile authoritative", () => {
+    expect(
+      initialProfileScope(
+        new URLSearchParams("resume=session-1&profile=review"),
+        "worker_x",
+      ),
+    ).toBe("review");
+  });
+
+  it("preserves an explicit empty profile", () => {
+    expect(
+      initialProfileScope(new URLSearchParams("profile="), "worker_x"),
+    ).toBe("");
+  });
+
+  it("does not replace a launch profile with the sticky active profile", () => {
+    expect(
+      shouldAdoptActiveProfile(null, "worker_x", "default", "review"),
+    ).toBe(false);
+  });
+
+  it("uses the sticky active profile without a URL or launch profile", () => {
+    expect(
+      shouldAdoptActiveProfile(null, "", "default", "review"),
+    ).toBe(true);
+  });
+});
diff --git a/web/src/lib/profile-bootstrap.ts b/web/src/lib/profile-bootstrap.ts
new file mode 100644
index 0000000000..8a0cb2204c
--- /dev/null
+++ b/web/src/lib/profile-bootstrap.ts
@@ -0,0 +1,31 @@
+declare global {
+  interface Window {
+    __HERMES_INITIAL_PROFILE__?: string;
+  }
+}
+
+export function dashboardInitialProfile(): string {
+  if (typeof window === "undefined") return "";
+  return window.__HERMES_INITIAL_PROFILE__ ?? "";
+}
+
+export function initialProfileScope(
+  searchParams: URLSearchParams,
+  bootstrapProfile = dashboardInitialProfile(),
+): string {
+  const urlProfile = searchParams.get("profile");
+  return urlProfile === null ? bootstrapProfile : urlProfile;
+}
+
+export function shouldAdoptActiveProfile(
+  urlProfile: string | null,
+  bootstrapProfile: string,
+  currentProfile: string,
+  activeProfile: string,
+): boolean {
+  return (
+    urlProfile === null &&
+    !bootstrapProfile &&
+    activeProfile !== currentProfile
+  );
+}
diff --git a/web/vite.config.ts b/web/vite.config.ts
index b23b716d06..b45ee36b83 100644
--- a/web/vite.config.ts
+++ b/web/vite.config.ts
@@ -23,13 +23,15 @@ const BACKEND = process.env.HERMES_DASHBOARD_URL ?? "http://127.0.0.1:9119";
  * token, every protected `/api/*` call 401s.
  *
  * This plugin fetches the running dashboard's `index.html` on each dev page
- * load, scrapes the `window.__HERMES_SESSION_TOKEN__` assignment, and
- * re-injects it into the dev HTML. No-op in production builds.
+ * load and forwards its runtime bootstrap values into the dev HTML. No-op in
+ * production builds.
  */
 function hermesDevToken(): Plugin {
   const TOKEN_RE = /window\.__HERMES_SESSION_TOKEN__\s*=\s*"([^"]+)"/;
   const EMBEDDED_RE =
     /window\.__HERMES_DASHBOARD_EMBEDDED_CHAT__\s*=\s*(true|false)/;
+  const INITIAL_PROFILE_RE =
+    /window\.__HERMES_INITIAL_PROFILE__\s*=\s*("(?:\\.|[^"\\])*")/;
 
   return {
     name: "hermes:dev-session-token",
@@ -48,13 +50,16 @@ function hermesDevToken(): Plugin {
         }
         const embeddedMatch = html.match(EMBEDDED_RE);
         const embeddedJs = embeddedMatch ? embeddedMatch[1] : "true";
+        const initialProfileMatch = html.match(INITIAL_PROFILE_RE);
+        const initialProfileJs = initialProfileMatch?.[1] ?? '""';
         return [
           {
             tag: "script",
             injectTo: "head",
             children:
               `window.__HERMES_SESSION_TOKEN__="${match[1]}";` +
-              `window.__HERMES_DASHBOARD_EMBEDDED_CHAT__=${embeddedJs};`,
+              `window.__HERMES_DASHBOARD_EMBEDDED_CHAT__=${embeddedJs};` +
+              `window.__HERMES_INITIAL_PROFILE__=${initialProfileJs};`,
           },
         ];
       } catch (err) {

From 0eb0a6d78bca6858460a5961154bc87bfd2e6c30 Mon Sep 17 00:00:00 2001
From: Sun Haoyuan <58774225+Shy7777@users.noreply.github.com>
Date: Fri, 18 Sep 2026 14:27:36 -0700
Subject: [PATCH 178/190] fix(desktop): drop stale custom endpoint saves

---
 .../custom-endpoints-settings.test.tsx        | 87 +++++++++++++++++++
 .../settings/custom-endpoints-settings.tsx    | 19 +++-
 2 files changed, 103 insertions(+), 3 deletions(-)
 create mode 100644 apps/desktop/src/app/settings/custom-endpoints-settings.test.tsx

diff --git a/apps/desktop/src/app/settings/custom-endpoints-settings.test.tsx b/apps/desktop/src/app/settings/custom-endpoints-settings.test.tsx
new file mode 100644
index 0000000000..a24aa43604
--- /dev/null
+++ b/apps/desktop/src/app/settings/custom-endpoints-settings.test.tsx
@@ -0,0 +1,87 @@
+// @vitest-environment jsdom
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import type { CustomEndpointsResponse } from '@/types/hermes'
+
+const getCustomEndpoints = vi.fn()
+const saveCustomEndpoint = vi.fn()
+const notify = vi.fn()
+const notifyError = vi.fn()
+const triggerHaptic = vi.fn()
+
+vi.mock('@/hermes', () => ({
+  activateCustomEndpoint: vi.fn(),
+  deleteCustomEndpoint: vi.fn(),
+  getCustomEndpoints: (...args: unknown[]) => getCustomEndpoints(...args),
+  saveCustomEndpoint: (...args: unknown[]) => saveCustomEndpoint(...args),
+  validateCustomEndpoint: vi.fn()
+}))
+vi.mock('@/lib/haptics', () => ({ triggerHaptic: (...args: unknown[]) => triggerHaptic(...args) }))
+vi.mock('@/store/notifications', () => ({
+  notify: (...args: unknown[]) => notify(...args),
+  notifyError: (...args: unknown[]) => notifyError(...args)
+}))
+
+const emptyResponse: CustomEndpointsResponse = {
+  current: { base_url: '', model: '', provider: '' },
+  endpoints: []
+}
+
+const savedResponse: CustomEndpointsResponse = {
+  current: { base_url: 'http://profile-a.test/v1', model: 'model-a', provider: 'profile-a-endpoint' },
+  endpoints: [
+    {
+      base_url: 'http://profile-a.test/v1',
+      discover_models: true,
+      has_api_key: false,
+      id: 'profile-a-endpoint',
+      is_current: true,
+      model: 'model-a',
+      models: ['model-a'],
+      name: 'Profile A'
+    }
+  ],
+  id: 'profile-a-endpoint',
+  ok: true
+}
+
+afterEach(() => {
+  cleanup()
+  vi.clearAllMocks()
+})
+
+describe('CustomEndpointsSettings', () => {
+  it('drops a pending save completion after its profile-scoped view unmounts', async () => {
+    let resolveSave!: (value: CustomEndpointsResponse) => void
+    saveCustomEndpoint.mockReturnValue(new Promise(resolve => (resolveSave = resolve)))
+    getCustomEndpoints.mockResolvedValue(emptyResponse)
+    const onConfigSaved = vi.fn()
+    const onMainModelChanged = vi.fn()
+    const { CustomEndpointsSettings } = await import('./custom-endpoints-settings')
+
+    const view = render(
+      <CustomEndpointsSettings onConfigSaved={onConfigSaved} onMainModelChanged={onMainModelChanged} />
+    )
+
+    await screen.findByText('No custom endpoints')
+    fireEvent.change(screen.getByPlaceholderText('Axet Proxy'), { target: { value: 'Profile A' } })
+    fireEvent.change(screen.getByPlaceholderText('http://127.0.0.1:8081/v1'), {
+      target: { value: 'http://profile-a.test/v1' }
+    })
+    fireEvent.change(screen.getByPlaceholderText('gpt-5.4'), { target: { value: 'model-a' } })
+    fireEvent.click(screen.getByRole('button', { name: 'Save' }))
+    expect(saveCustomEndpoint).toHaveBeenCalledTimes(1)
+
+    // SettingsView keys ProvidersSettings by the selected profile, so a profile
+    // switch unmounts this instance while its already-routed write is pending.
+    view.unmount()
+    await act(async () => resolveSave(savedResponse))
+
+    expect(onMainModelChanged).not.toHaveBeenCalled()
+    expect(onConfigSaved).not.toHaveBeenCalled()
+    expect(triggerHaptic).not.toHaveBeenCalled()
+    expect(notify).not.toHaveBeenCalled()
+    expect(notifyError).not.toHaveBeenCalled()
+  })
+})
diff --git a/apps/desktop/src/app/settings/custom-endpoints-settings.tsx b/apps/desktop/src/app/settings/custom-endpoints-settings.tsx
index 4c48e57953..0ce4123e4b 100644
--- a/apps/desktop/src/app/settings/custom-endpoints-settings.tsx
+++ b/apps/desktop/src/app/settings/custom-endpoints-settings.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
 
 import { Button } from '@/components/ui/button'
 import { Checkbox } from '@/components/ui/checkbox'
@@ -79,6 +79,7 @@ function toPayload(form: EndpointForm, models?: string[]): CustomEndpointUpdate
 
 export function CustomEndpointsSettings({ onConfigSaved, onMainModelChanged }: CustomEndpointsSettingsProps) {
   const { t } = useI18n()
+  const mounted = useRef(false)
   const [loading, setLoading] = useState(true)
   const [saving, setSaving] = useState(false)
   const [testing, setTesting] = useState(false)
@@ -93,8 +94,10 @@ export function CustomEndpointsSettings({ onConfigSaved, onMainModelChanged }: C
     setEndpoints(data.endpoints)
   }
 
+  // eslint-disable-next-line no-restricted-syntax -- lifecycle guard drops stale async completions; it does not mirror an atom
   useEffect(() => {
     let cancelled = false
+    mounted.current = true
 
     async function load() {
       try {
@@ -124,6 +127,7 @@ export function CustomEndpointsSettings({ onConfigSaved, onMainModelChanged }: C
 
     return () => {
       cancelled = true
+      mounted.current = false
     }
   }, [])
 
@@ -131,6 +135,11 @@ export function CustomEndpointsSettings({ onConfigSaved, onMainModelChanged }: C
     try {
       setSaving(true)
       const response = await saveCustomEndpoint(toPayload(form, discoveredModels))
+
+      if (!mounted.current) {
+        return
+      }
+
       setEndpoints(response.endpoints)
       const saved = response.endpoints.find(endpoint => endpoint.id === response.id)
 
@@ -147,9 +156,13 @@ export function CustomEndpointsSettings({ onConfigSaved, onMainModelChanged }: C
       onConfigSaved?.()
       notify({ kind: 'success', message: 'Custom endpoint saved.' })
     } catch (err) {
-      notifyError(err, 'Save failed')
+      if (mounted.current) {
+        notifyError(err, 'Save failed')
+      }
     } finally {
-      setSaving(false)
+      if (mounted.current) {
+        setSaving(false)
+      }
     }
   }
 

From 55c92fa32a468d9cb1c624e352eb7792626ced90 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 14:34:26 -0700
Subject: [PATCH 179/190] fix(desktop): every Custom Endpoints completion is
 dropped once its profile view unmounts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The salvaged guard covered only the save path. Validate, activate and delete completions
from a profile-A instance could still set state, fire onConfigSaved / onMainModelChanged
and toast after SettingsView remounted the panel under profile B — the identical stale-
completion race, three more doors. The same `mounted` ref now gates all four handlers
and `refresh()`.

Test: the salvaged vitest file now partially mocks `@/hermes` (the profile-scope note
subscribes to `setApiRequestProfile` at import time) and stubs `ActiveProfileNote`.

Closes #69451 (renderer `profileScoped()` forwarding, backend `_config_profile_scope`
and the profile-keyed remount landed on main earlier; this closes the last atom).
Salvage of #69452.
---
 .../custom-endpoints-settings.test.tsx        |  4 +-
 .../settings/custom-endpoints-settings.tsx    | 49 ++++++++++++++++---
 2 files changed, 45 insertions(+), 8 deletions(-)

diff --git a/apps/desktop/src/app/settings/custom-endpoints-settings.test.tsx b/apps/desktop/src/app/settings/custom-endpoints-settings.test.tsx
index a24aa43604..8aa6f4b577 100644
--- a/apps/desktop/src/app/settings/custom-endpoints-settings.test.tsx
+++ b/apps/desktop/src/app/settings/custom-endpoints-settings.test.tsx
@@ -10,13 +10,15 @@ const notify = vi.fn()
 const notifyError = vi.fn()
 const triggerHaptic = vi.fn()
 
-vi.mock('@/hermes', () => ({
+vi.mock('@/hermes', async importOriginal => ({
+  ...(await importOriginal<Record<string, unknown>>()),
   activateCustomEndpoint: vi.fn(),
   deleteCustomEndpoint: vi.fn(),
   getCustomEndpoints: (...args: unknown[]) => getCustomEndpoints(...args),
   saveCustomEndpoint: (...args: unknown[]) => saveCustomEndpoint(...args),
   validateCustomEndpoint: vi.fn()
 }))
+vi.mock('./profile-scope', () => ({ ActiveProfileNote: () => null }))
 vi.mock('@/lib/haptics', () => ({ triggerHaptic: (...args: unknown[]) => triggerHaptic(...args) }))
 vi.mock('@/store/notifications', () => ({
   notify: (...args: unknown[]) => notify(...args),
diff --git a/apps/desktop/src/app/settings/custom-endpoints-settings.tsx b/apps/desktop/src/app/settings/custom-endpoints-settings.tsx
index 0ce4123e4b..6259c73f42 100644
--- a/apps/desktop/src/app/settings/custom-endpoints-settings.tsx
+++ b/apps/desktop/src/app/settings/custom-endpoints-settings.tsx
@@ -91,7 +91,10 @@ export function CustomEndpointsSettings({ onConfigSaved, onMainModelChanged }: C
 
   async function refresh() {
     const data = await getCustomEndpoints()
-    setEndpoints(data.endpoints)
+
+    if (mounted.current) {
+      setEndpoints(data.endpoints)
+    }
   }
 
   // eslint-disable-next-line no-restricted-syntax -- lifecycle guard drops stale async completions; it does not mirror an atom
@@ -170,6 +173,11 @@ export function CustomEndpointsSettings({ onConfigSaved, onMainModelChanged }: C
     try {
       setTesting(true)
       const response = await validateCustomEndpoint(toPayload(form))
+
+      if (!mounted.current) {
+        return
+      }
+
       setDiscoveredModels(response.models)
 
       if (response.ok) {
@@ -190,9 +198,13 @@ export function CustomEndpointsSettings({ onConfigSaved, onMainModelChanged }: C
         })
       }
     } catch (err) {
-      notifyError(err, 'Validation failed')
+      if (mounted.current) {
+        notifyError(err, 'Validation failed')
+      }
     } finally {
-      setTesting(false)
+      if (mounted.current) {
+        setTesting(false)
+      }
     }
   }
 
@@ -200,14 +212,28 @@ export function CustomEndpointsSettings({ onConfigSaved, onMainModelChanged }: C
     try {
       setActivating(endpoint.id)
       const response = await activateCustomEndpoint(endpoint.id)
+
+      if (!mounted.current) {
+        return
+      }
+
       await refresh()
+
+      if (!mounted.current) {
+        return
+      }
+
       onConfigSaved?.()
       onMainModelChanged?.(response.provider, response.model)
       triggerHaptic('success')
     } catch (err) {
-      notifyError(err, 'Activation failed')
+      if (mounted.current) {
+        notifyError(err, 'Activation failed')
+      }
     } finally {
-      setActivating(null)
+      if (mounted.current) {
+        setActivating(null)
+      }
     }
   }
 
@@ -220,6 +246,11 @@ export function CustomEndpointsSettings({ onConfigSaved, onMainModelChanged }: C
     try {
       setDeleting(endpoint.id)
       const response = await deleteCustomEndpoint(endpoint.id)
+
+      if (!mounted.current) {
+        return
+      }
+
       setEndpoints(response.endpoints)
 
       if (form.id === endpoint.id) {
@@ -230,9 +261,13 @@ export function CustomEndpointsSettings({ onConfigSaved, onMainModelChanged }: C
       onConfigSaved?.()
       triggerHaptic('success')
     } catch (err) {
-      notifyError(err, 'Delete failed')
+      if (mounted.current) {
+        notifyError(err, 'Delete failed')
+      }
     } finally {
-      setDeleting(null)
+      if (mounted.current) {
+        setDeleting(null)
+      }
     }
   }
 

From 420feb63071717dede4d8af6714db19b30f69b72 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 14:36:48 -0700
Subject: [PATCH 180/190] docs: session-bound Desktop/TUI settings writes and
 dashboard launch-profile fallback are per profile

---
 website/docs/user-guide/features/web-dashboard.md | 6 ++++++
 website/docs/user-guide/multi-profile-gateways.md | 1 +
 2 files changed, 7 insertions(+)

diff --git a/website/docs/user-guide/features/web-dashboard.md b/website/docs/user-guide/features/web-dashboard.md
index ff211885b4..bd695ce1b6 100644
--- a/website/docs/user-guide/features/web-dashboard.md
+++ b/website/docs/user-guide/features/web-dashboard.md
@@ -64,6 +64,12 @@ worker dashboard
 # → not running:     starts the machine dashboard with "worker" preselected
 ```
 
+A dashboard started this way keeps `worker` as its fallback scope for the
+whole server lifetime: a deep link that omits `?profile=` (for example a
+`/chat?resume=<id>` link) still opens under `worker`, so the embedded chat
+sees that profile's MCP servers, model and skills. An explicit `?profile=`
+in the URL always wins.
+
 Pass `--isolated` to opt out and run a dedicated server scoped to that
 profile (the pre-unification behavior — useful if you deliberately expose
 different profiles' dashboards with different auth).
diff --git a/website/docs/user-guide/multi-profile-gateways.md b/website/docs/user-guide/multi-profile-gateways.md
index a872af3600..43902bbcb3 100644
--- a/website/docs/user-guide/multi-profile-gateways.md
+++ b/website/docs/user-guide/multi-profile-gateways.md
@@ -462,6 +462,7 @@ profile and never shares with the default or any sibling:
 | Session-search knobs (`sessions.cjk_fts`, `sessions.search_slow_ms`) | The profile's `config.yaml` | Documented default — never the default profile's bridged value |
 | Platform proxies (`TELEGRAM_PROXY`, `DISCORD_PROXY`, `HTTPS_PROXY`, …) | The profile's own `.env` | Direct connection — never the default profile's proxy |
 | MCP discovery in the Desktop/dashboard backend | Once per served profile home | A profile selected after another has already built an agent still discovers its own `mcp_servers` |
+| Settings changed from a Desktop / TUI session (`/busy`, `/verbose`, `/approval`, `/cwd`, theme and display toggles) | The `config.yaml` of the profile that owns the session, even when the RPC carries only the session id | The session's own profile is written; the launch profile's `config.yaml` and its `TERMINAL_CWD` are never touched |
 | MCP connections in the Desktop/dashboard backend and the per-profile cron ticker | Keyed per served profile even with `gateway.multiplex_profiles` off — same rule as the multiplexer | A same-named `mcp_servers` entry with other credentials is its own connection; a served profile never calls a server as another profile |
 | Dashboard actions (`hermes -p <name> …` spawned by the Desktop/dashboard) | A scrubbed child env pinned to that profile's `HERMES_HOME` | The child loads its own `.env`; the dashboard profile's tokens and ports are not inherited |
 | Every child that acts for a served profile (slash worker, Bot Chat delivery, A2A forward, `key_cmd` helper, browser driver) | That profile's own `.env` + secret sources over a credential-scrubbed base — with or without `gateway.multiplex_profiles` (the Desktop/dashboard `?profile=` route counts) | Absent from the child — a key that reached the launch process only through systemd / Compose / the shell is never inherited by another profile's child |

From ae2a8cd819066c86ecf473fb7531b2a0941b09af Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 02:31:23 +0530
Subject: [PATCH 181/190] fix(runtime): declared Anthropic transport applies
 only on the provider's own endpoint

33a2f29a6 made the runtime fallback honour the provider's declared transport
when URL detection has no opinion. For minimax/minimax-cn that is
anthropic_messages, which is right on api.minimax.io/anthropic but wrong for a
model.base_url override at an OpenAI-compatible relay (LiteLLM, token proxy,
corporate egress) or at the provider's own /v1 path: every request is built
Messages-shaped with x-api-key and 401s, or silently reroutes to a fallback
provider.

The fallback now keeps anthropic_messages only when base_url shares the
catalog default's host and is the bare host or a path under /anthropic;
everywhere else it lands on chat_completions. Other declared transports are
untouched (openai-api on a custom proxy still keeps codex_responses, as
33a2f29a6 intended), and URL detection still runs first.

Salvage of PR 76859 by webtecnica, rebuilt on the refactored module with the
path check teknium asked for in review.

Co-authored-by: webtecnica <webtecnica@gmail.com>
---
 hermes_cli/runtime_provider.py                | 27 +++++++++++++++++--
 .../test_runtime_transport_precedence.py      | 19 +++++++++++++
 2 files changed, 44 insertions(+), 2 deletions(-)

diff --git a/hermes_cli/runtime_provider.py b/hermes_cli/runtime_provider.py
index 9a39758e65..a81d92f03c 100644
--- a/hermes_cli/runtime_provider.py
+++ b/hermes_cli/runtime_provider.py
@@ -32,7 +32,7 @@ from hermes_cli.auth import (  # resolve_external_process_provider_credentials i
 from hermes_cli import config as _config_mod
 from hermes_cli import models as _models  # attribute access keeps ``hermes_cli.models.<name>`` patches effective
 from hermes_constants import OPENROUTER_BASE_URL
-from hermes_cli.providers import determine_api_mode, is_actual_route, is_official_openai_host, nous_api_mode
+from hermes_cli.providers import determine_api_mode, get_provider, is_actual_route, is_official_openai_host, nous_api_mode
 from utils import base_url_host_matches, base_url_hostname, env_int
 
 
@@ -143,7 +143,30 @@ def _fallback_api_mode(provider: str, base_url: str, model: str = "") -> str:
     ``chat_completions``."""
     if is_actual_route(provider, base_url):
         return "chat_completions"
-    return _detect_api_mode_for_url(base_url) or determine_api_mode(provider, base_url, model) or "chat_completions"
+    detected = _detect_api_mode_for_url(base_url)
+    if detected:
+        return detected
+    declared = determine_api_mode(provider, base_url, model) or "chat_completions"
+    if declared == "anthropic_messages" and not _on_declared_anthropic_endpoint(provider, base_url):
+        # The declared Anthropic transport describes the provider's own endpoint. A base_url
+        # override at a foreign host (OpenAI-compatible relay, LiteLLM, egress proxy) or at the
+        # provider's OpenAI-compatible path (api.minimax.io/v1) speaks chat/completions; sending
+        # Messages-shaped requests with x-api-key there is a 401 on every turn (#76836).
+        return "chat_completions"
+    return declared
+
+
+def _on_declared_anthropic_endpoint(provider: str, base_url: str) -> bool:
+    """True when ``base_url`` is the provider's own Anthropic-protocol endpoint: same host as the
+    catalog default and either the bare host or a path under ``/anthropic``. Unknown default ⇒ True
+    (nothing to compare against, keep the declared transport)."""
+    default = (getattr(get_provider(provider), "base_url", "") or "").strip()
+    if not default:
+        return True
+    if not base_url_host_matches(base_url, base_url_hostname(default)):
+        return False
+    path = urlparse((base_url or "").strip().lower()).path.rstrip("/")
+    return path == "" or path.startswith("/anthropic")
 
 
 def _resolve_plain_custom_api_mode(model_cfg: Dict[str, Any], base_url: str) -> str:
diff --git a/tests/hermes_cli/test_runtime_transport_precedence.py b/tests/hermes_cli/test_runtime_transport_precedence.py
index b54052e11f..653ea25100 100644
--- a/tests/hermes_cli/test_runtime_transport_precedence.py
+++ b/tests/hermes_cli/test_runtime_transport_precedence.py
@@ -43,6 +43,25 @@ class TestFallbackApiMode:
             == "codex_responses"
         )
 
+    @pytest.mark.parametrize("provider, base_url", [
+        ("minimax", "http://127.0.0.1:8787/v1"),        # OpenAI-compatible relay in front of MiniMax
+        ("minimax-cn", "https://egress.corp.test/v1"),  # corporate egress gateway
+        ("minimax", "https://api.minimax.io/v1"),       # provider's own OpenAI-compatible path
+    ])
+    def test_anthropic_transport_is_not_assumed_off_the_provider_endpoint(self, provider, base_url):
+        # #76836: the declared anthropic_messages transport is a statement about the provider's
+        # own /anthropic endpoint. Anywhere else the override speaks chat/completions; Messages-
+        # shaped requests with x-api-key there 401 on every turn (or silently reroute to a fallback).
+        assert _fallback_api_mode(provider, base_url, "MiniMax-M3") == "chat_completions"
+
+    @pytest.mark.parametrize("provider, base_url", [
+        ("minimax", "https://api.minimax.io"),             # bare host, no /anthropic hint (#53054 kept)
+        ("minimax", "https://api.minimax.io/anthropic"),   # URL-detected native path
+        ("minimax-cn", "https://api.minimaxi.com/anthropic/v1"),
+    ])
+    def test_anthropic_transport_holds_on_the_provider_endpoint(self, provider, base_url):
+        assert _fallback_api_mode(provider, base_url, "MiniMax-M3") == "anthropic_messages"
+
     def test_lookalike_host_is_not_treated_as_official(self):
         # The spoof host must not be detected AS OpenAI by the URL lane —
         # the provider-declared transport may still apply, but host-derived

From dbdcb83d7786c9877076f1f038167c1aecce75cd Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 02:49:30 +0530
Subject: [PATCH 182/190] fix(runtime): compare against the catalog default
 path, keep declared on empty input

Gate findings folded: the accepted path is derived from the provider's
catalog default (/anthropic for MiniMax, /plan/anthropic for Tencent) instead
of a hardcoded /anthropic prefix, so /anthropic-compat no longer passes and a
non-/anthropic default provider's own endpoint does; an empty base_url keeps
the declared transport like an unknown default; the catalog read is
allow_network=False (determine_api_mode just warmed it); _base_url_path is
shared with URL detection. Tests pin the catalog defaults they compare
against so the contract holds offline.
---
 hermes_cli/runtime_provider.py                | 27 +++++++++++-----
 .../test_runtime_transport_precedence.py      | 32 +++++++++++++++++--
 2 files changed, 49 insertions(+), 10 deletions(-)

diff --git a/hermes_cli/runtime_provider.py b/hermes_cli/runtime_provider.py
index a81d92f03c..8b2e43c89b 100644
--- a/hermes_cli/runtime_provider.py
+++ b/hermes_cli/runtime_provider.py
@@ -118,7 +118,7 @@ def _detect_api_mode_for_url(base_url: str) -> Optional[str]:
     mandated = _HOST_MANDATED_API_MODES.get(hostname) or ("codex_responses" if is_official_openai_host(base_url) else None)
     if mandated:
         return mandated
-    path = urlparse(normalized).path.rstrip("/")
+    path = _base_url_path(normalized)
     if path.endswith(("/anthropic", "/anthropic/v1")) or (hostname == "api.kimi.com" and "/coding" in normalized):
         # Direct native Anthropic host: realign with providers.determine_api_mode, which already maps this
         # host to anthropic_messages. The exact-hostname match rejects lookalike subdomains
@@ -140,7 +140,8 @@ def _fallback_api_mode(provider: str, base_url: str, model: str = "") -> str:
     """api_mode when no explicit/persisted mode applies: URL detection (host-mandated wire shapes)
     first, then the transport the provider overlay declares via ``providers.determine_api_mode``
     (``openai-api`` pointed at us.api.openai.com 400'd on every tool call without it), then
-    ``chat_completions``."""
+    ``chat_completions``. A declared ``anthropic_messages`` is kept only on the provider's own
+    endpoint (#76836)."""
     if is_actual_route(provider, base_url):
         return "chat_completions"
     detected = _detect_api_mode_for_url(base_url)
@@ -158,15 +159,25 @@ def _fallback_api_mode(provider: str, base_url: str, model: str = "") -> str:
 
 def _on_declared_anthropic_endpoint(provider: str, base_url: str) -> bool:
     """True when ``base_url`` is the provider's own Anthropic-protocol endpoint: same host as the
-    catalog default and either the bare host or a path under ``/anthropic``. Unknown default ⇒ True
-    (nothing to compare against, keep the declared transport)."""
-    default = (getattr(get_provider(provider), "base_url", "") or "").strip()
-    if not default:
+    catalog default and either the bare host or the default's path (``/anthropic`` for MiniMax,
+    ``/plan/anthropic`` for Tencent) with or without a ``/v1`` tail. With nothing to compare —
+    no URL, or an overlay-only provider whose models.dev default is not cached (offline) — keep
+    the declared transport: demoting the provider's own default endpoint would be the worse
+    failure."""
+    pdef = get_provider(provider, allow_network=False)
+    default = (pdef.base_url if pdef else "").strip()
+    if not default or not (base_url or "").strip():
         return True
     if not base_url_host_matches(base_url, base_url_hostname(default)):
         return False
-    path = urlparse((base_url or "").strip().lower()).path.rstrip("/")
-    return path == "" or path.startswith("/anthropic")
+    path = _base_url_path(base_url)
+    default_path = _base_url_path(default).removesuffix("/v1")
+    return path == "" or path == default_path or path.startswith(default_path + "/")
+
+
+def _base_url_path(base_url: str) -> str:
+    """Lower-cased URL path without the trailing slash (``""`` for a bare host)."""
+    return urlparse((base_url or "").strip().lower()).path.rstrip("/")
 
 
 def _resolve_plain_custom_api_mode(model_cfg: Dict[str, Any], base_url: str) -> str:
diff --git a/tests/hermes_cli/test_runtime_transport_precedence.py b/tests/hermes_cli/test_runtime_transport_precedence.py
index 653ea25100..c598d5e476 100644
--- a/tests/hermes_cli/test_runtime_transport_precedence.py
+++ b/tests/hermes_cli/test_runtime_transport_precedence.py
@@ -8,8 +8,9 @@ the provider overlay itself declares.
 
 Contract pinned here: when URL detection has no opinion, the runtime falls
 back to ``providers.determine_api_mode(provider, base_url, model)`` (the
-provider's declared transport), and only lands on ``chat_completions`` for
-genuinely unknown providers/endpoints. Covers the explicit-runtime path and
+provider's declared transport), and lands on ``chat_completions`` for
+genuinely unknown providers/endpoints and for a declared ``anthropic_messages``
+off the provider's own endpoint (#76836). Covers the explicit-runtime path and
 the API-key-provider path; the pool-entry path shares the same helper.
 """
 
@@ -43,10 +44,33 @@ class TestFallbackApiMode:
             == "codex_responses"
         )
 
+    @pytest.fixture
+    def catalog_defaults(self, monkeypatch):
+        """Pin the models.dev default endpoints the predicate compares against, so the contract
+        holds without the network (a cold cache leaves ``ProviderDef.base_url`` empty)."""
+        import dataclasses
+        from hermes_cli import runtime_provider
+        defaults = {
+            "minimax": "https://api.minimax.io/anthropic/v1",
+            "minimax-cn": "https://api.minimaxi.com/anthropic/v1",
+            "tencent-tokenplan": "https://api.lkeap.cloud.tencent.com/plan/anthropic",
+        }
+        real = runtime_provider.get_provider
+
+        def seeded(name, *, allow_network=True):
+            pdef = real(name, allow_network=False)
+            if pdef is not None and not pdef.base_url and name in defaults:
+                pdef = dataclasses.replace(pdef, base_url=defaults[name])
+            return pdef
+
+        monkeypatch.setattr(runtime_provider, "get_provider", seeded)
+
+    @pytest.mark.usefixtures("catalog_defaults")
     @pytest.mark.parametrize("provider, base_url", [
         ("minimax", "http://127.0.0.1:8787/v1"),        # OpenAI-compatible relay in front of MiniMax
         ("minimax-cn", "https://egress.corp.test/v1"),  # corporate egress gateway
         ("minimax", "https://api.minimax.io/v1"),       # provider's own OpenAI-compatible path
+        ("minimax", "https://api.minimax.io/anthropic-compat/v1"),  # lookalike path, not /anthropic/
     ])
     def test_anthropic_transport_is_not_assumed_off_the_provider_endpoint(self, provider, base_url):
         # #76836: the declared anthropic_messages transport is a statement about the provider's
@@ -54,10 +78,14 @@ class TestFallbackApiMode:
         # shaped requests with x-api-key there 401 on every turn (or silently reroute to a fallback).
         assert _fallback_api_mode(provider, base_url, "MiniMax-M3") == "chat_completions"
 
+    @pytest.mark.usefixtures("catalog_defaults")
     @pytest.mark.parametrize("provider, base_url", [
         ("minimax", "https://api.minimax.io"),             # bare host, no /anthropic hint (#53054 kept)
         ("minimax", "https://api.minimax.io/anthropic"),   # URL-detected native path
         ("minimax-cn", "https://api.minimaxi.com/anthropic/v1"),
+        ("minimax", "https://api.minimax.io/anthropic/v1/messages"),  # under the default path
+        ("tencent-tokenplan", "https://api.lkeap.cloud.tencent.com/plan/anthropic/v2"),  # non-/anthropic default
+        ("minimax", ""),  # nothing to compare: keep the declared transport
     ])
     def test_anthropic_transport_holds_on_the_provider_endpoint(self, provider, base_url):
         assert _fallback_api_mode(provider, base_url, "MiniMax-M3") == "anthropic_messages"

From da2b6a47b935c96cc46e68913e6189236e663627 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 03:20:07 +0530
Subject: [PATCH 183/190] fix(runtime): share URL path parsing with the host
 check; pin catalog defaults in tests

Round-2 gate folds: utils.base_url_path sits next to base_url_hostname on
the same scheme-tolerant parser, so a scheme-less override (api.minimax.io)
keeps host and path checks agreeing; a default with no path is an explicit
"nothing to compare" case; the dead `or "chat_completions"` after
determine_api_mode is gone; the test fixture seeds the catalog defaults
unconditionally so a warm models.dev cache cannot change what the contract
compares against, and the stale #53054 test comment states the new contract.
---
 hermes_cli/runtime_provider.py                | 30 ++++++++-----------
 .../test_runtime_transport_precedence.py      |  9 ++++--
 utils.py                                      |  7 +++++
 3 files changed, 27 insertions(+), 19 deletions(-)

diff --git a/hermes_cli/runtime_provider.py b/hermes_cli/runtime_provider.py
index 8b2e43c89b..2d67899281 100644
--- a/hermes_cli/runtime_provider.py
+++ b/hermes_cli/runtime_provider.py
@@ -33,7 +33,7 @@ from hermes_cli import config as _config_mod
 from hermes_cli import models as _models  # attribute access keeps ``hermes_cli.models.<name>`` patches effective
 from hermes_constants import OPENROUTER_BASE_URL
 from hermes_cli.providers import determine_api_mode, get_provider, is_actual_route, is_official_openai_host, nous_api_mode
-from utils import base_url_host_matches, base_url_hostname, env_int
+from utils import base_url_host_matches, base_url_hostname, base_url_path, env_int
 
 
 # Late-bound delegates, deliberately NOT module-level from-imports: this module is often imported
@@ -118,7 +118,7 @@ def _detect_api_mode_for_url(base_url: str) -> Optional[str]:
     mandated = _HOST_MANDATED_API_MODES.get(hostname) or ("codex_responses" if is_official_openai_host(base_url) else None)
     if mandated:
         return mandated
-    path = _base_url_path(normalized)
+    path = base_url_path(normalized)
     if path.endswith(("/anthropic", "/anthropic/v1")) or (hostname == "api.kimi.com" and "/coding" in normalized):
         # Direct native Anthropic host: realign with providers.determine_api_mode, which already maps this
         # host to anthropic_messages. The exact-hostname match rejects lookalike subdomains
@@ -147,7 +147,7 @@ def _fallback_api_mode(provider: str, base_url: str, model: str = "") -> str:
     detected = _detect_api_mode_for_url(base_url)
     if detected:
         return detected
-    declared = determine_api_mode(provider, base_url, model) or "chat_completions"
+    declared = determine_api_mode(provider, base_url, model)
     if declared == "anthropic_messages" and not _on_declared_anthropic_endpoint(provider, base_url):
         # The declared Anthropic transport describes the provider's own endpoint. A base_url
         # override at a foreign host (OpenAI-compatible relay, LiteLLM, egress proxy) or at the
@@ -158,28 +158,24 @@ def _fallback_api_mode(provider: str, base_url: str, model: str = "") -> str:
 
 
 def _on_declared_anthropic_endpoint(provider: str, base_url: str) -> bool:
-    """True when ``base_url`` is the provider's own Anthropic-protocol endpoint: same host as the
-    catalog default and either the bare host or the default's path (``/anthropic`` for MiniMax,
-    ``/plan/anthropic`` for Tencent) with or without a ``/v1`` tail. With nothing to compare —
-    no URL, or an overlay-only provider whose models.dev default is not cached (offline) — keep
-    the declared transport: demoting the provider's own default endpoint would be the worse
-    failure."""
+    """True when ``base_url`` is the provider's own Anthropic-protocol endpoint: the catalog
+    default's host (or a subdomain of it) and either the bare host — the provider's own host
+    with no path still means the native endpoint (#53054) — or the default's path
+    (``/anthropic`` for MiniMax, ``/plan/anthropic`` for Tencent) with or without a ``/v1``
+    tail. With nothing to compare — no URL, no path on the default, or an overlay-only
+    provider whose models.dev default is not cached (offline) — keep the declared transport:
+    demoting the provider's own default endpoint would be the worse failure."""
     pdef = get_provider(provider, allow_network=False)
     default = (pdef.base_url if pdef else "").strip()
-    if not default or not (base_url or "").strip():
+    default_path = base_url_path(default).removesuffix("/v1")
+    if not default_path or not (base_url or "").strip():
         return True
     if not base_url_host_matches(base_url, base_url_hostname(default)):
         return False
-    path = _base_url_path(base_url)
-    default_path = _base_url_path(default).removesuffix("/v1")
+    path = base_url_path(base_url)
     return path == "" or path == default_path or path.startswith(default_path + "/")
 
 
-def _base_url_path(base_url: str) -> str:
-    """Lower-cased URL path without the trailing slash (``""`` for a bare host)."""
-    return urlparse((base_url or "").strip().lower()).path.rstrip("/")
-
-
 def _resolve_plain_custom_api_mode(model_cfg: Dict[str, Any], base_url: str) -> str:
     """api_mode for legacy/plain ``provider: custom`` endpoints — conservative by default: only
     direct OpenAI/xAI/Meta URLs imply Responses; named custom providers opt in via ``api_mode``."""
diff --git a/tests/hermes_cli/test_runtime_transport_precedence.py b/tests/hermes_cli/test_runtime_transport_precedence.py
index c598d5e476..667d868947 100644
--- a/tests/hermes_cli/test_runtime_transport_precedence.py
+++ b/tests/hermes_cli/test_runtime_transport_precedence.py
@@ -58,8 +58,12 @@ class TestFallbackApiMode:
         real = runtime_provider.get_provider
 
         def seeded(name, *, allow_network=True):
+            # allow_network is dropped so the fixture can never reach models.dev; replace, not
+            # assign, because get_provider hands back the cached ProviderDef other tests share.
+            # Seed unconditionally: a warm disk cache must not swap in whatever models.dev
+            # publishes today.
             pdef = real(name, allow_network=False)
-            if pdef is not None and not pdef.base_url and name in defaults:
+            if pdef is not None and name in defaults:
                 pdef = dataclasses.replace(pdef, base_url=defaults[name])
             return pdef
 
@@ -104,7 +108,8 @@ class TestFallbackApiMode:
     def test_minimax_declared_anthropic_transport_honored(self):
         # Same latent bug class: minimax declares an Anthropic-compatible
         # transport but previously fell back to chat_completions when the
-        # URL carried no /anthropic hint.
+        # URL carried no /anthropic hint. The bare catalog host is still
+        # honored (#53054); non-default paths now are not (#76836).
         from hermes_cli.providers import determine_api_mode
 
         expected = determine_api_mode("minimax", "https://api.minimax.io")
diff --git a/utils.py b/utils.py
index 36d9651e79..3ca74d4b11 100644
--- a/utils.py
+++ b/utils.py
@@ -583,6 +583,13 @@ def base_url_hostname(base_url: str) -> str:
     return _hostname_of(_parse_base_url(base_url))
 
 
+def base_url_path(base_url: str) -> str:
+    """Lowercased URL path without the trailing slash (``""`` for a bare host); same scheme
+    tolerance as :func:`base_url_hostname` so host and path checks agree on one URL."""
+    parsed = _parse_base_url(base_url)
+    return (parsed.path if parsed else "").lower().rstrip("/")
+
+
 def model_forces_max_completion_tokens(model: str) -> bool:
     """True for OpenAI families that reject ``max_tokens`` (HTTP 400 ``unsupported_parameter``)."""
     m = (model or "").strip().lower().rsplit("/", 1)[-1]

From 07fccd3114f382e365e1436926d0cac9716c0b93 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 03:25:57 +0530
Subject: [PATCH 184/190] fix(runtime): drop the dead urlparse import; pin the
 bare-host-default fail-open

A provider whose catalog default has no path (api.anthropic.com) has no
sibling OpenAI-compatible path to infer an override's protocol from, so the
declared transport stays; the docstring says so and a test case pins it.
---
 hermes_cli/runtime_provider.py                        | 8 ++++----
 tests/hermes_cli/test_runtime_transport_precedence.py | 6 ++++--
 2 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/hermes_cli/runtime_provider.py b/hermes_cli/runtime_provider.py
index 2d67899281..68da8dec16 100644
--- a/hermes_cli/runtime_provider.py
+++ b/hermes_cli/runtime_provider.py
@@ -11,7 +11,6 @@ import logging
 import re
 from dataclasses import dataclass
 from typing import Any, Callable, Dict, Optional
-from urllib.parse import urlparse
 
 logger = logging.getLogger(__name__)
 
@@ -162,9 +161,10 @@ def _on_declared_anthropic_endpoint(provider: str, base_url: str) -> bool:
     default's host (or a subdomain of it) and either the bare host — the provider's own host
     with no path still means the native endpoint (#53054) — or the default's path
     (``/anthropic`` for MiniMax, ``/plan/anthropic`` for Tencent) with or without a ``/v1``
-    tail. With nothing to compare — no URL, no path on the default, or an overlay-only
-    provider whose models.dev default is not cached (offline) — keep the declared transport:
-    demoting the provider's own default endpoint would be the worse failure."""
+    tail. With nothing to compare — no URL, an overlay-only provider whose models.dev default
+    is not cached (offline), or a default with no path at all (``api.anthropic.com``: no sibling
+    OpenAI-compatible path exists to tell an override's protocol from) — keep the declared
+    transport: demoting the provider's own endpoint would be the worse failure."""
     pdef = get_provider(provider, allow_network=False)
     default = (pdef.base_url if pdef else "").strip()
     default_path = base_url_path(default).removesuffix("/v1")
diff --git a/tests/hermes_cli/test_runtime_transport_precedence.py b/tests/hermes_cli/test_runtime_transport_precedence.py
index 667d868947..2b8855d053 100644
--- a/tests/hermes_cli/test_runtime_transport_precedence.py
+++ b/tests/hermes_cli/test_runtime_transport_precedence.py
@@ -54,12 +54,13 @@ class TestFallbackApiMode:
             "minimax": "https://api.minimax.io/anthropic/v1",
             "minimax-cn": "https://api.minimaxi.com/anthropic/v1",
             "tencent-tokenplan": "https://api.lkeap.cloud.tencent.com/plan/anthropic",
+            "anthropic": "https://api.anthropic.com",
         }
         real = runtime_provider.get_provider
 
         def seeded(name, *, allow_network=True):
-            # allow_network is dropped so the fixture can never reach models.dev; replace, not
-            # assign, because get_provider hands back the cached ProviderDef other tests share.
+            # allow_network is dropped so the fixture can never reach models.dev; replace()
+            # rather than mutate so the fixture never depends on get_provider's object identity.
             # Seed unconditionally: a warm disk cache must not swap in whatever models.dev
             # publishes today.
             pdef = real(name, allow_network=False)
@@ -90,6 +91,7 @@ class TestFallbackApiMode:
         ("minimax", "https://api.minimax.io/anthropic/v1/messages"),  # under the default path
         ("tencent-tokenplan", "https://api.lkeap.cloud.tencent.com/plan/anthropic/v2"),  # non-/anthropic default
         ("minimax", ""),  # nothing to compare: keep the declared transport
+        ("anthropic", "http://127.0.0.1:4000/v1"),  # bare-host default: relays serve /v1/messages
     ])
     def test_anthropic_transport_holds_on_the_provider_endpoint(self, provider, base_url):
         assert _fallback_api_mode(provider, base_url, "MiniMax-M3") == "anthropic_messages"

From ccb3d968cedcedd4e9c97ef20a170da885b4a7f9 Mon Sep 17 00:00:00 2001
From: leomcamilo <leocamilo@me.com>
Date: Sat, 19 Sep 2026 03:29:45 +0530
Subject: [PATCH 185/190] fix(backup): exit non-zero when a full backup is
 incomplete

`hermes backup` recorded per-file failures, printed `Backup incomplete: <path>`
and still returned shell status 0, so a cron job or systemd timer would publish
"successful" archives missing state.db indefinitely.

`run_backup()` now returns whether the archive is complete and `cmd_backup()`
maps False to exit status 1. The zip is kept so the operator can still restore
the rest; hard failures keep their SystemExit(1)/(2). `--quick` is unchanged.

Slim redo of #101096 on current main (the branch predates the run_backup /
_run_backup_locked split and the backup lock); same policy, same exit codes.
Supersedes #68866 (@jbryce) which proposed the policy first.
---
 hermes_cli/backup.py                   | 20 ++++++++++++++------
 hermes_cli/main.py                     |  5 ++++-
 tests/hermes_cli/test_backup.py        | 26 ++++++++++++++++++++++++++
 website/docs/reference/cli-commands.md |  2 ++
 4 files changed, 46 insertions(+), 7 deletions(-)

diff --git a/hermes_cli/backup.py b/hermes_cli/backup.py
index 2b3fe56013..a5918f18a7 100644
--- a/hermes_cli/backup.py
+++ b/hermes_cli/backup.py
@@ -663,8 +663,14 @@ def _collect_external_entries() -> tuple[list[tuple[Path, str]], list[str]]:
     return external_to_add, skipped_external
 
 
-def run_backup(args) -> None:
-    """Create a zip backup of the Hermes home directory."""
+def run_backup(args) -> bool:
+    """Create a zip backup of the Hermes home directory.
+
+    True when every selected file landed in the archive (or there was nothing to back up); False
+    when the zip was written but is incomplete — it is kept so the rest can still be restored, and
+    the caller turns False into exit status 1 so a cron/systemd timer never publishes a "successful"
+    archive that is missing state.db. Hard failures keep raising ``SystemExit``.
+    """
     hermes_root = get_default_hermes_root()
 
     if not hermes_root.is_dir():
@@ -673,13 +679,13 @@ def run_backup(args) -> None:
 
     try:
         with _backup_operation_lock(hermes_root):
-            _run_backup_locked(args, hermes_root)
+            return _run_backup_locked(args, hermes_root)
     except BackupInProgressError as exc:
         print(f"Error: {exc}")
         raise SystemExit(2) from exc
 
 
-def _run_backup_locked(args, hermes_root: Path) -> None:
+def _run_backup_locked(args, hermes_root: Path) -> bool:
     """Write a full backup while the cross-process backup slot is held."""
     out_path = _resolve_backup_output_path(args.output)
     scan_started = time.monotonic()
@@ -691,7 +697,7 @@ def _run_backup_locked(args, hermes_root: Path) -> None:
     if not files_to_add and not external_to_add:
         logger.info("backup phase=scan status=empty duration_ms=%.1f", (time.monotonic() - scan_started) * 1000)
         print("No files to back up.")
-        return
+        return True
 
     file_count = len(files_to_add) + len(external_to_add)
     logger.info("backup phase=scan status=complete duration_ms=%.1f files=%d",
@@ -736,7 +742,8 @@ def _run_backup_locked(args, hermes_root: Path) -> None:
     if skipped_dirs:
         print("\n  Excluded directories:\n" + "\n".join(f"    {d}/" for d in sorted(skipped_dirs)))
     if errors:
-        _print_capped(f"\n  Warnings ({len(errors)} files skipped):", errors, "  ")
+        _print_capped(f"\n  Archive kept, but {len(errors)} file(s) could not be added (exit status 1):",
+                      errors, "  ")
     else:
         print(f"\nRestore with: hermes import {out_path.name}")
     keep = getattr(args, "keep", 0)  # 0 / absent: never prune (non-CLI callers)
@@ -744,6 +751,7 @@ def _run_backup_locked(args, hermes_root: Path) -> None:
         pruned = _prune_prefixed_zips(out_path.parent, _RUN_BACKUP_PREFIX, keep, "backup")
         if pruned:
             print(f"  Pruned {pruned} older {_RUN_BACKUP_PREFIX}*.zip (keeping {keep}).")
+    return not errors
 
 
 # --- Import ---
diff --git a/hermes_cli/main.py b/hermes_cli/main.py
index 36d83e206f..3eee4d8c5b 100644
--- a/hermes_cli/main.py
+++ b/hermes_cli/main.py
@@ -2224,7 +2224,10 @@ def cmd_backup(args):
     """Back up Hermes home directory to a zip file."""
     from hermes_cli import backup
 
-    (backup.run_quick_backup if getattr(args, "quick", False) else backup.run_backup)(args)
+    if getattr(args, "quick", False):
+        backup.run_quick_backup(args)
+    elif backup.run_backup(args) is False:
+        raise SystemExit(1)  # archive written but incomplete: never shell-success for a timer
 
 
 def _print_version_info(*, check_updates: bool = True) -> None:
diff --git a/tests/hermes_cli/test_backup.py b/tests/hermes_cli/test_backup.py
index 5b438e953f..b22f68a5f6 100644
--- a/tests/hermes_cli/test_backup.py
+++ b/tests/hermes_cli/test_backup.py
@@ -736,6 +736,32 @@ class TestValidation:
 
 class TestBackupEdgeCases:
 
+    def test_incomplete_archive_is_kept_but_reported_as_failure(self, tmp_path, monkeypatch, capsys):
+        """A file that cannot be read is skipped, the zip still lands, and the CLI exits 1: a
+        cron/systemd timer must never see a partial archive as success (#101096)."""
+        hermes_home = tmp_path / ".hermes"
+        hermes_home.mkdir()
+        _make_hermes_tree(hermes_home)
+        unreadable = hermes_home / "skills" / "locked.md"
+        unreadable.write_text("secret\n")
+        unreadable.chmod(0)
+        if os.access(unreadable, os.R_OK):
+            pytest.skip("running as root: chmod 0 does not make the file unreadable")
+        monkeypatch.setenv("HERMES_HOME", str(hermes_home))
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+        out_zip = tmp_path / "out.zip"
+
+        from hermes_cli.backup import run_backup
+        from hermes_cli.main import cmd_backup
+
+        assert run_backup(Namespace(output=str(out_zip))) is False
+        assert out_zip.exists()
+        assert "Backup incomplete" in capsys.readouterr().out
+        with pytest.raises(SystemExit) as exc:
+            cmd_backup(Namespace(output=str(tmp_path / "out2.zip"), quick=False))
+        assert exc.value.code == 1
+        unreadable.chmod(0o600)
+        assert run_backup(Namespace(output=str(tmp_path / "out4.zip"))) is True
 
     def test_empty_hermes_home(self, tmp_path, monkeypatch):
         """Backup handles empty hermes home (no files to back up)."""
diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.md
index 4aa9fb5ed3..992de4694c 100644
--- a/website/docs/reference/cli-commands.md
+++ b/website/docs/reference/cli-commands.md
@@ -1039,6 +1039,8 @@ Create a zip archive of your Hermes configuration, skills, sessions, and data. T
 
 The backup uses SQLite's `backup()` API for safe copying, so it works correctly even when Hermes is running (WAL-mode safe).
 
+**Exit status:** `0` only when every selected file landed in the archive. If some files could not be added (`Backup incomplete: …`), the zip is kept so the rest can still be restored, but the command exits `1` — a cron or systemd timer will not report a partial archive as success. `2` means another backup was already running.
+
 **What's excluded from the zip:**
 
 - `*.db-wal`, `*.db-shm`, `*.db-journal` — SQLite's WAL / shared-memory / journal sidecars. The `*.db` file already got a consistent snapshot via `sqlite3.backup()`; shipping the live sidecars alongside it would let a restore see a half-committed state.

From 1250a3e4eb6689b0b32594d2b077ca6a9b9aa109 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sat, 19 Sep 2026 03:35:27 +0530
Subject: [PATCH 186/190] fix(backup): an incomplete archive never prunes the
 last complete ones

Gate review: `--keep` pruning ran after the summary regardless of `errors`,
so a timer hitting the same unreadable file every run would exit 1 each time
and still rotate every complete `hermes-backup-*.zip` out after N runs,
leaving only incomplete archives. Prune only after a complete backup; the
test pins a pre-existing good archive surviving an incomplete run with
`--keep 1`. The summary no longer hard-codes the caller's exit code.
---
 hermes_cli/backup.py                   |  7 ++++---
 hermes_cli/main.py                     |  2 +-
 tests/hermes_cli/test_backup.py        | 13 +++++++++----
 website/docs/reference/cli-commands.md |  2 +-
 4 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/hermes_cli/backup.py b/hermes_cli/backup.py
index a5918f18a7..b948f57358 100644
--- a/hermes_cli/backup.py
+++ b/hermes_cli/backup.py
@@ -742,12 +742,13 @@ def _run_backup_locked(args, hermes_root: Path) -> bool:
     if skipped_dirs:
         print("\n  Excluded directories:\n" + "\n".join(f"    {d}/" for d in sorted(skipped_dirs)))
     if errors:
-        _print_capped(f"\n  Archive kept, but {len(errors)} file(s) could not be added (exit status 1):",
-                      errors, "  ")
+        _print_capped(f"\n  Archive kept, but {len(errors)} file(s) could not be added:", errors, "  ")
     else:
         print(f"\nRestore with: hermes import {out_path.name}")
+    # Prune only after a complete archive: a timer hitting the same unreadable file every run must
+    # not rotate the last good backups out in favour of incomplete ones.
     keep = getattr(args, "keep", 0)  # 0 / absent: never prune (non-CLI callers)
-    if keep and out_path.name.startswith(_RUN_BACKUP_PREFIX):
+    if keep and not errors and out_path.name.startswith(_RUN_BACKUP_PREFIX):
         pruned = _prune_prefixed_zips(out_path.parent, _RUN_BACKUP_PREFIX, keep, "backup")
         if pruned:
             print(f"  Pruned {pruned} older {_RUN_BACKUP_PREFIX}*.zip (keeping {keep}).")
diff --git a/hermes_cli/main.py b/hermes_cli/main.py
index 3eee4d8c5b..581491f0ed 100644
--- a/hermes_cli/main.py
+++ b/hermes_cli/main.py
@@ -2226,7 +2226,7 @@ def cmd_backup(args):
 
     if getattr(args, "quick", False):
         backup.run_quick_backup(args)
-    elif backup.run_backup(args) is False:
+    elif not backup.run_backup(args):
         raise SystemExit(1)  # archive written but incomplete: never shell-success for a timer
 
 
diff --git a/tests/hermes_cli/test_backup.py b/tests/hermes_cli/test_backup.py
index b22f68a5f6..fe31dfac7e 100644
--- a/tests/hermes_cli/test_backup.py
+++ b/tests/hermes_cli/test_backup.py
@@ -749,13 +749,18 @@ class TestBackupEdgeCases:
             pytest.skip("running as root: chmod 0 does not make the file unreadable")
         monkeypatch.setenv("HERMES_HOME", str(hermes_home))
         monkeypatch.setattr(Path, "home", lambda: tmp_path)
-        out_zip = tmp_path / "out.zip"
-
-        from hermes_cli.backup import run_backup
+        from hermes_cli.backup import _RUN_BACKUP_PREFIX, run_backup
         from hermes_cli.main import cmd_backup
 
-        assert run_backup(Namespace(output=str(out_zip))) is False
+        out_dir = tmp_path / "b"
+        out_dir.mkdir()
+        good_old = out_dir / f"{_RUN_BACKUP_PREFIX}old.zip"
+        good_old.write_bytes(b"PK")
+        out_zip = out_dir / f"{_RUN_BACKUP_PREFIX}new.zip"
+
+        assert run_backup(Namespace(output=str(out_zip), keep=1)) is False
         assert out_zip.exists()
+        assert good_old.exists(), "an incomplete run must not rotate the last complete backup out"
         assert "Backup incomplete" in capsys.readouterr().out
         with pytest.raises(SystemExit) as exc:
             cmd_backup(Namespace(output=str(tmp_path / "out2.zip"), quick=False))
diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.md
index 992de4694c..f9a9089cf8 100644
--- a/website/docs/reference/cli-commands.md
+++ b/website/docs/reference/cli-commands.md
@@ -1039,7 +1039,7 @@ Create a zip archive of your Hermes configuration, skills, sessions, and data. T
 
 The backup uses SQLite's `backup()` API for safe copying, so it works correctly even when Hermes is running (WAL-mode safe).
 
-**Exit status:** `0` only when every selected file landed in the archive. If some files could not be added (`Backup incomplete: …`), the zip is kept so the rest can still be restored, but the command exits `1` — a cron or systemd timer will not report a partial archive as success. `2` means another backup was already running.
+**Exit status:** `0` only when every selected file landed in the archive. If some files could not be added (`Backup incomplete: …`), the zip is kept so the rest can still be restored, but the command exits `1` — a cron or systemd timer will not report a partial archive as success, and `--keep` pruning is skipped so older complete archives survive. `2` means another backup was already running.
 
 **What's excluded from the zip:**
 

From 4c28be68c240a4092b541eca3351dd0ea6a05b4c Mon Sep 17 00:00:00 2001
From: liuhao1024 <sunsky.lau@gmail.com>
Date: Fri, 18 Sep 2026 07:11:31 +0800
Subject: [PATCH 187/190] fix(bedrock): size inference-profile ARNs from the
 wrapped foundation model

An application-inference-profile ARN names no model, so the context probe
error text and the static substring table both miss and the 128k default
silently applies: a profile wrapping a 1M-context Sonnet compacts at ~96k.
Resolve the wrapped foundation-model id via GetInferenceProfile (reusing
the control-plane client; an application profile's id IS its ARN, so the
call works on both API shapes), then let the existing probe/table paths
run on that id. Resolution failures (missing bedrock:GetInferenceProfile,
no creds) keep today's behaviour but now log a WARNING naming the
explicit model.context_length escape hatch instead of staying silent.

Fixes #114476
---
 agent/bedrock_adapter.py            | 53 ++++++++++++++++++++++-
 tests/agent/test_bedrock_adapter.py | 66 ++++++++++++++++++++++++++++-
 2 files changed, 116 insertions(+), 3 deletions(-)

diff --git a/agent/bedrock_adapter.py b/agent/bedrock_adapter.py
index a23b3ec164..ae76640bd8 100644
--- a/agent/bedrock_adapter.py
+++ b/agent/bedrock_adapter.py
@@ -1123,11 +1123,60 @@ def probe_bedrock_context_length(model_id: str, region: str) -> Optional[int]:
 
 def get_bedrock_context_length(model_id: str, region: str = "", probe: bool = True) -> int:
     """Context window: live probe (if ``probe`` and ``region``) → static table → default. The table is fallback
-    only: a stale substring match silently caps the window (a 1M Opus pinned to 200K via "opus-4")."""
+    only: a stale substring match silently caps the window (a 1M Opus pinned to 200K via "opus-4").
+    An inference-profile ARN is first resolved to the wrapped foundation model (#114476)."""
+    profile_arn = model_id if _INFERENCE_PROFILE_ARN_RE.search(model_id) else ""
+    if profile_arn and region:
+        model_id = _resolve_inference_profile_model_id(profile_arn, region)
     if probe and region and (probed := probe_bedrock_context_length(model_id, region)):
         return probed
     matches = [key for key in BEDROCK_CONTEXT_LENGTHS if key in model_id.lower()]
-    return BEDROCK_CONTEXT_LENGTHS[max(matches, key=len)] if matches else BEDROCK_DEFAULT_CONTEXT_LENGTH
+    if matches:
+        return BEDROCK_CONTEXT_LENGTHS[max(matches, key=len)]
+    if profile_arn:
+        logger.warning(
+            "Bedrock inference profile %s resolved no known model window; using the %s default. "
+            "Grant bedrock:GetInferenceProfile or set model.context_length explicitly if the "
+            "wrapped model has a larger window.",
+            profile_arn,
+            f"{BEDROCK_DEFAULT_CONTEXT_LENGTH:,}",
+        )
+    return BEDROCK_DEFAULT_CONTEXT_LENGTH
+
+
+# An application-inference-profile ARN names no model, so the probe error text and the static
+# substring table both miss and the 128k default silently applies (#114476). An application
+# profile's id IS its ARN, so GetInferenceProfile(inferenceProfileId=<ARN>) works on both the
+# original API shape and the later arn-parameterised one.
+_INFERENCE_PROFILE_ARN_RE = re.compile(r":(?:application-)?inference-profile/")
+_FOUNDATION_MODEL_ARN_RE = re.compile(r"foundation-model/(.+)$")
+_inference_profile_model_cache: Dict[str, str] = {}
+
+
+def _resolve_inference_profile_model_id(profile_arn: str, region: str, _depth: int = 0) -> str:
+    """Inference-profile ARN → the wrapped foundation-model id (a profile may wrap another profile);
+    the ARN itself when resolution is unavailable or ``bedrock:GetInferenceProfile`` is not granted,
+    so callers fall back to the existing default-window behaviour."""
+    cache_key = f"{profile_arn}@{region}"
+    if cache_key in _inference_profile_model_cache:
+        return _inference_profile_model_cache[cache_key]
+    resolved = profile_arn
+    try:
+        client = _get_bedrock_control_client(region)
+        profile = client.get_inference_profile(inferenceProfileId=profile_arn)
+        for wrapped in profile.get("models", []):
+            model_arn = (wrapped.get("modelArn") or "").strip()
+            if match := _FOUNDATION_MODEL_ARN_RE.search(model_arn):
+                resolved = match.group(1)
+                break
+            if _INFERENCE_PROFILE_ARN_RE.search(model_arn) and _depth < 2:
+                resolved = _resolve_inference_profile_model_id(model_arn, region, _depth + 1)
+                break
+    except Exception as exc:  # no boto3 / credentials / GetInferenceProfile not granted
+        logger.debug("Inference profile resolution skipped for %s: %s", profile_arn, exc)
+        return profile_arn
+    _inference_profile_model_cache[cache_key] = resolved
+    return resolved
 
 
 # ---- BEGIN PLUGIN-COMPAT (revert-scheduled; see COMPAT_MANIFEST.md) ----
diff --git a/tests/agent/test_bedrock_adapter.py b/tests/agent/test_bedrock_adapter.py
index 636f75a612..c1e83fbc9e 100644
--- a/tests/agent/test_bedrock_adapter.py
+++ b/tests/agent/test_bedrock_adapter.py
@@ -1067,7 +1067,71 @@ class TestBedrockContextLength:
             mock_probe.assert_not_called()
 
 
-class TestBedrockContextProbe:
+class TestInferenceProfileContextLength:
+    """Test context-window sizing for application-inference-profile ARNs (#114476): the ARN itself
+    names no model, so the window must come from the wrapped foundation model."""
+
+    ARN = "arn:aws:bedrock:us-west-2:123456789012:application-inference-profile/abcdef123456"
+
+    def setup_method(self):
+        from agent import bedrock_adapter
+        bedrock_adapter._inference_profile_model_cache.clear()
+
+    def _control_client(self, profile_response):
+        client = MagicMock()
+        client.get_inference_profile.return_value = profile_response
+        return client
+
+    def test_arn_resolves_wrapped_model_window(self):
+        # Sonnet 4.6 (1M) wrapped by the profile: the static table must match on the
+        # foundation-model id recovered from GetInferenceProfile, not on the ARN.
+        from agent.bedrock_adapter import get_bedrock_context_length
+        response = {"models": [
+            {"modelArn": "arn:aws:bedrock:::foundation-model/anthropic.claude-sonnet-4-6-v1:0"}]}
+        with patch("agent.bedrock_adapter._get_bedrock_control_client",
+                   return_value=self._control_client(response)):
+            assert get_bedrock_context_length(self.ARN, region="us-west-2", probe=False) == 1_000_000
+
+    def test_nested_profile_resolves_to_foundation_model(self):
+        # A profile wrapping another profile ARN must recurse to the foundation model.
+        from agent.bedrock_adapter import get_bedrock_context_length
+        inner_arn = "arn:aws:bedrock:us-west-2:123456789012:inference-profile/us.anthropic.claude-sonnet-4-6-v1:0"
+        responses = [
+            {"models": [{"modelArn": inner_arn}]},
+            {"models": [{"modelArn": "arn:aws:bedrock:::foundation-model/anthropic.claude-sonnet-4-6-v1:0"}]},
+        ]
+        with patch("agent.bedrock_adapter._get_bedrock_control_client",
+                   side_effect=[self._control_client(r) for r in responses]):
+            assert get_bedrock_context_length(self.ARN, region="us-west-2", probe=False) == 1_000_000
+
+    def test_resolution_denied_falls_back_to_default_with_warning(self):
+        # Without bedrock:GetInferenceProfile the call raises; the default window applies and the
+        # silence is broken with a WARNING naming the profile and the explicit-config escape hatch.
+        from agent.bedrock_adapter import get_bedrock_context_length, BEDROCK_DEFAULT_CONTEXT_LENGTH
+        client = MagicMock()
+        client.get_inference_profile.side_effect = Exception("AccessDeniedException")
+        with patch("agent.bedrock_adapter._get_bedrock_control_client", return_value=client), \
+                patch("agent.bedrock_adapter.logger") as mock_logger:
+            assert get_bedrock_context_length(
+                self.ARN, region="us-west-2", probe=False) == BEDROCK_DEFAULT_CONTEXT_LENGTH
+            assert mock_logger.warning.called
+
+    def test_resolved_arn_is_cached_per_process(self):
+        from agent.bedrock_adapter import get_bedrock_context_length
+        response = {"models": [
+            {"modelArn": "arn:aws:bedrock:::foundation-model/anthropic.claude-sonnet-4-6-v1:0"}]}
+        with patch("agent.bedrock_adapter._get_bedrock_control_client",
+                   return_value=self._control_client(response)) as mock_client_factory:
+            assert get_bedrock_context_length(self.ARN, region="us-west-2", probe=False) == 1_000_000
+            assert get_bedrock_context_length(self.ARN, region="us-west-2", probe=False) == 1_000_000
+            assert mock_client_factory.call_count == 1
+
+    def test_no_region_skips_profile_resolution(self):
+        # The no-region path must stay offline like the probe does (display/offline callers).
+        from agent.bedrock_adapter import get_bedrock_context_length, BEDROCK_DEFAULT_CONTEXT_LENGTH
+        with patch("agent.bedrock_adapter._resolve_inference_profile_model_id") as mock_resolve:
+            assert get_bedrock_context_length(self.ARN) == BEDROCK_DEFAULT_CONTEXT_LENGTH
+            mock_resolve.assert_not_called()
     """Test the live context-window probe that reads the real window from
     Bedrock's 'prompt is too long' validation error."""
 

From 11445cc54e9b9a992b417851e7d4da0779eaba8b Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 00:51:17 -0700
Subject: [PATCH 188/190] fix(bedrock): application inference profile ARNs size
 from the wrapped model on the real path

The cherry-picked #114482 never resolved a profile in production: the only
caller, agent/model_metadata.py::_resolve_bedrock_context_length, invokes
get_bedrock_context_length(model, probe=False) with no region, and the
resolver was gated on `region`; and it called
get_inference_profile(inferenceProfileId=...) where botocore requires
`inferenceProfileIdentifier`, so even with a region the call raised
ParamValidationError, was swallowed, and the 128k default applied with only
the new warning. Live against a botocore Stubber: 128000 before, 1000000 after.

- resolve in the ARN's own region (field 4), then the passed region, then
  the standard AWS chain; the runtime region / base_url may differ
- inferenceProfileIdentifier is the only request parameter GetInferenceProfile has
- match only `application-inference-profile/`: system-defined
  `inference-profile/us.anthropic...` ARNs embed the model id and need no call
- no nested-profile recursion: GetInferenceProfile lists foundation-model ARNs
  and the wrapped ARN itself satisfies the static-table substring match
- cache both outcomes per process (runs on every context-length resolution),
  cleared by reset_client_cache()
- tests trimmed to two invariants on the production call shape; restore the
  TestBedrockContextProbe class header the cherry-pick clobbered
- docs: bedrock:GetInferenceProfile IAM permission and the fallback WARNING

Co-authored-by: Yagna Vudathu <yagnavudathu@gmail.com>
---
 agent/bedrock_adapter.py            | 51 ++++++++++----------
 tests/agent/test_bedrock_adapter.py | 73 ++++++++++-------------------
 website/docs/guides/aws-bedrock.md  |  3 ++
 3 files changed, 51 insertions(+), 76 deletions(-)

diff --git a/agent/bedrock_adapter.py b/agent/bedrock_adapter.py
index ae76640bd8..279e74dac9 100644
--- a/agent/bedrock_adapter.py
+++ b/agent/bedrock_adapter.py
@@ -127,6 +127,7 @@ def reset_client_cache():
     _bedrock_runtime_client_cache.clear()
     _bedrock_control_client_cache.clear()
     _bedrock_clients_by_home.clear()
+    _inference_profile_model_cache.clear()
 
 
 def invalidate_runtime_client(region: str) -> bool:
@@ -1124,9 +1125,9 @@ def probe_bedrock_context_length(model_id: str, region: str) -> Optional[int]:
 def get_bedrock_context_length(model_id: str, region: str = "", probe: bool = True) -> int:
     """Context window: live probe (if ``probe`` and ``region``) → static table → default. The table is fallback
     only: a stale substring match silently caps the window (a 1M Opus pinned to 200K via "opus-4").
-    An inference-profile ARN is first resolved to the wrapped foundation model (#114476)."""
-    profile_arn = model_id if _INFERENCE_PROFILE_ARN_RE.search(model_id) else ""
-    if profile_arn and region:
+    An application-inference-profile ARN is first resolved to the model it wraps (#114476)."""
+    profile_arn = model_id if _APPLICATION_PROFILE_ARN_RE.search(model_id) else ""
+    if profile_arn:
         model_id = _resolve_inference_profile_model_id(profile_arn, region)
     if probe and region and (probed := probe_bedrock_context_length(model_id, region)):
         return probed
@@ -1144,38 +1145,34 @@ def get_bedrock_context_length(model_id: str, region: str = "", probe: bool = Tr
     return BEDROCK_DEFAULT_CONTEXT_LENGTH
 
 
-# An application-inference-profile ARN names no model, so the probe error text and the static
-# substring table both miss and the 128k default silently applies (#114476). An application
-# profile's id IS its ARN, so GetInferenceProfile(inferenceProfileId=<ARN>) works on both the
-# original API shape and the later arn-parameterised one.
-_INFERENCE_PROFILE_ARN_RE = re.compile(r":(?:application-)?inference-profile/")
-_FOUNDATION_MODEL_ARN_RE = re.compile(r"foundation-model/(.+)$")
+# An application-inference-profile ARN (cost-allocation wrapper) carries an opaque id, so the probe
+# error text and the static substring table both miss and the 128k default silently applies
+# (#114476). System-defined `inference-profile/us.anthropic...` ARNs embed the model id and need no
+# lookup. The ARN's own region (field 4) is authoritative for the control-plane call: the runtime
+# region / base_url may differ, and an empty region must not skip the lookup because the
+# production caller (agent/model_metadata.py::_resolve_bedrock_context_length) passes none.
+_APPLICATION_PROFILE_ARN_RE = re.compile(r":application-inference-profile/")
+_ARN_REGION_RE = re.compile(r"^arn:[^:]+:bedrock:([a-z0-9-]+):", re.IGNORECASE)
 _inference_profile_model_cache: Dict[str, str] = {}
 
 
-def _resolve_inference_profile_model_id(profile_arn: str, region: str, _depth: int = 0) -> str:
-    """Inference-profile ARN → the wrapped foundation-model id (a profile may wrap another profile);
-    the ARN itself when resolution is unavailable or ``bedrock:GetInferenceProfile`` is not granted,
-    so callers fall back to the existing default-window behaviour."""
-    cache_key = f"{profile_arn}@{region}"
-    if cache_key in _inference_profile_model_cache:
-        return _inference_profile_model_cache[cache_key]
+def _resolve_inference_profile_model_id(profile_arn: str, region: str = "") -> str:
+    """Application-profile ARN → the wrapped model's ARN (its ``foundation-model/<id>`` tail satisfies the
+    static-table substring match); the profile ARN itself when ``bedrock:GetInferenceProfile`` is not
+    granted or unavailable, so callers keep the default-window behaviour. Both outcomes are cached per
+    process: this runs on every context-length resolution, not once per model."""
+    if profile_arn in _inference_profile_model_cache:
+        return _inference_profile_model_cache[profile_arn]
+    arn_region = _ARN_REGION_RE.match(profile_arn)
+    region = (arn_region.group(1) if arn_region else "") or region or resolve_bedrock_region()
     resolved = profile_arn
     try:
         client = _get_bedrock_control_client(region)
-        profile = client.get_inference_profile(inferenceProfileId=profile_arn)
-        for wrapped in profile.get("models", []):
-            model_arn = (wrapped.get("modelArn") or "").strip()
-            if match := _FOUNDATION_MODEL_ARN_RE.search(model_arn):
-                resolved = match.group(1)
-                break
-            if _INFERENCE_PROFILE_ARN_RE.search(model_arn) and _depth < 2:
-                resolved = _resolve_inference_profile_model_id(model_arn, region, _depth + 1)
-                break
+        models = client.get_inference_profile(inferenceProfileIdentifier=profile_arn).get("models") or []
+        resolved = next((m["modelArn"] for m in models if m.get("modelArn")), profile_arn)
     except Exception as exc:  # no boto3 / credentials / GetInferenceProfile not granted
         logger.debug("Inference profile resolution skipped for %s: %s", profile_arn, exc)
-        return profile_arn
-    _inference_profile_model_cache[cache_key] = resolved
+    _inference_profile_model_cache[profile_arn] = resolved
     return resolved
 
 
diff --git a/tests/agent/test_bedrock_adapter.py b/tests/agent/test_bedrock_adapter.py
index c1e83fbc9e..51c817d48f 100644
--- a/tests/agent/test_bedrock_adapter.py
+++ b/tests/agent/test_bedrock_adapter.py
@@ -1068,8 +1068,8 @@ class TestBedrockContextLength:
 
 
 class TestInferenceProfileContextLength:
-    """Test context-window sizing for application-inference-profile ARNs (#114476): the ARN itself
-    names no model, so the window must come from the wrapped foundation model."""
+    """Application-inference-profile ARNs name no model, so the window must come from the model the
+    profile wraps via GetInferenceProfile — on the production call shape (no region, probe=False)."""
 
     ARN = "arn:aws:bedrock:us-west-2:123456789012:application-inference-profile/abcdef123456"
 
@@ -1077,61 +1077,36 @@ class TestInferenceProfileContextLength:
         from agent import bedrock_adapter
         bedrock_adapter._inference_profile_model_cache.clear()
 
-    def _control_client(self, profile_response):
+    def test_arn_resolves_wrapped_model_window_in_the_arn_region(self):
+        # No region passed (agent/model_metadata.py::_resolve_bedrock_context_length passes none) and
+        # AWS_REGION elsewhere: the lookup must still run, in the ARN's own region, with the
+        # parameter name botocore actually validates (inferenceProfileIdentifier).
+        from agent.bedrock_adapter import get_bedrock_context_length
         client = MagicMock()
-        client.get_inference_profile.return_value = profile_response
-        return client
+        client.get_inference_profile.return_value = {"models": [
+            {"modelArn": "arn:aws:bedrock:us-west-2::foundation-model/anthropic.claude-sonnet-4-6"}]}
+        with patch("agent.bedrock_adapter._get_bedrock_control_client", return_value=client) as factory, \
+                patch.dict("os.environ", {"AWS_REGION": "us-east-1"}):
+            assert get_bedrock_context_length(self.ARN, probe=False) == 1_000_000
+            assert get_bedrock_context_length(self.ARN, probe=False) == 1_000_000  # cached per process
+        factory.assert_called_once_with("us-west-2")
+        client.get_inference_profile.assert_called_once_with(inferenceProfileIdentifier=self.ARN)
 
-    def test_arn_resolves_wrapped_model_window(self):
-        # Sonnet 4.6 (1M) wrapped by the profile: the static table must match on the
-        # foundation-model id recovered from GetInferenceProfile, not on the ARN.
-        from agent.bedrock_adapter import get_bedrock_context_length
-        response = {"models": [
-            {"modelArn": "arn:aws:bedrock:::foundation-model/anthropic.claude-sonnet-4-6-v1:0"}]}
-        with patch("agent.bedrock_adapter._get_bedrock_control_client",
-                   return_value=self._control_client(response)):
-            assert get_bedrock_context_length(self.ARN, region="us-west-2", probe=False) == 1_000_000
-
-    def test_nested_profile_resolves_to_foundation_model(self):
-        # A profile wrapping another profile ARN must recurse to the foundation model.
-        from agent.bedrock_adapter import get_bedrock_context_length
-        inner_arn = "arn:aws:bedrock:us-west-2:123456789012:inference-profile/us.anthropic.claude-sonnet-4-6-v1:0"
-        responses = [
-            {"models": [{"modelArn": inner_arn}]},
-            {"models": [{"modelArn": "arn:aws:bedrock:::foundation-model/anthropic.claude-sonnet-4-6-v1:0"}]},
-        ]
-        with patch("agent.bedrock_adapter._get_bedrock_control_client",
-                   side_effect=[self._control_client(r) for r in responses]):
-            assert get_bedrock_context_length(self.ARN, region="us-west-2", probe=False) == 1_000_000
-
-    def test_resolution_denied_falls_back_to_default_with_warning(self):
-        # Without bedrock:GetInferenceProfile the call raises; the default window applies and the
-        # silence is broken with a WARNING naming the profile and the explicit-config escape hatch.
+    def test_resolution_denied_falls_back_to_default_with_warning(self, caplog):
+        # Without bedrock:GetInferenceProfile the default window applies and the silence is broken
+        # with a WARNING naming the profile and the explicit-config escape hatch.
         from agent.bedrock_adapter import get_bedrock_context_length, BEDROCK_DEFAULT_CONTEXT_LENGTH
         client = MagicMock()
         client.get_inference_profile.side_effect = Exception("AccessDeniedException")
         with patch("agent.bedrock_adapter._get_bedrock_control_client", return_value=client), \
-                patch("agent.bedrock_adapter.logger") as mock_logger:
-            assert get_bedrock_context_length(
-                self.ARN, region="us-west-2", probe=False) == BEDROCK_DEFAULT_CONTEXT_LENGTH
-            assert mock_logger.warning.called
+                caplog.at_level("WARNING", logger="agent.bedrock_adapter"):
+            assert get_bedrock_context_length(self.ARN, probe=False) == BEDROCK_DEFAULT_CONTEXT_LENGTH
+        warnings = [r for r in caplog.records if r.levelname == "WARNING"]
+        assert len(warnings) == 1 and self.ARN in warnings[0].getMessage()
+        assert "GetInferenceProfile" in warnings[0].getMessage()
 
-    def test_resolved_arn_is_cached_per_process(self):
-        from agent.bedrock_adapter import get_bedrock_context_length
-        response = {"models": [
-            {"modelArn": "arn:aws:bedrock:::foundation-model/anthropic.claude-sonnet-4-6-v1:0"}]}
-        with patch("agent.bedrock_adapter._get_bedrock_control_client",
-                   return_value=self._control_client(response)) as mock_client_factory:
-            assert get_bedrock_context_length(self.ARN, region="us-west-2", probe=False) == 1_000_000
-            assert get_bedrock_context_length(self.ARN, region="us-west-2", probe=False) == 1_000_000
-            assert mock_client_factory.call_count == 1
 
-    def test_no_region_skips_profile_resolution(self):
-        # The no-region path must stay offline like the probe does (display/offline callers).
-        from agent.bedrock_adapter import get_bedrock_context_length, BEDROCK_DEFAULT_CONTEXT_LENGTH
-        with patch("agent.bedrock_adapter._resolve_inference_profile_model_id") as mock_resolve:
-            assert get_bedrock_context_length(self.ARN) == BEDROCK_DEFAULT_CONTEXT_LENGTH
-            mock_resolve.assert_not_called()
+class TestBedrockContextProbe:
     """Test the live context-window probe that reads the real window from
     Bedrock's 'prompt is too long' validation error."""
 
diff --git a/website/docs/guides/aws-bedrock.md b/website/docs/guides/aws-bedrock.md
index 348dd17306..2c83542215 100644
--- a/website/docs/guides/aws-bedrock.md
+++ b/website/docs/guides/aws-bedrock.md
@@ -29,6 +29,7 @@ All three routes share the same AWS credential chain and region resolution — n
 - **IAM permissions** — at minimum:
   - `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream` (for inference)
   - `bedrock:ListFoundationModels` and `bedrock:ListInferenceProfiles` (for model discovery)
+  - `bedrock:GetInferenceProfile` (only if `model.default` is an application inference profile ARN — used to size the context window from the wrapped model)
 
 :::tip EC2 / ECS / Lambda
 On AWS compute, attach an IAM role with `AmazonBedrockFullAccess` and you're done. No API keys, no `.env` configuration — Hermes detects the instance role automatically.
@@ -110,6 +111,8 @@ Hermes automatically applies prompt caching on the Bedrock **Converse API** path
 
 For models whose context window isn't in Hermes' static table, Hermes can probe the real limit by sending oversized requests at fixed tiers (~1.3M and ~2.2M tokens) and parsing the `maximum` reported in Bedrock's length-validation error. Probed values feed the same metadata cache as the static table; stale cached entries that under-report a model's window (e.g. entries seeded before a model's 1M window went GA) are dropped automatically in favor of the larger known value.
 
+**Application inference profiles.** An ARN such as `arn:aws:bedrock:us-west-2:123456789012:application-inference-profile/abcdef123456` names no model, so neither the probe nor the static table can size it. Hermes calls `bedrock:GetInferenceProfile` in the ARN's region and sizes the window from the model the profile wraps (1M for a profile wrapping Claude Sonnet 4.6). Without that permission the 128,000-token default applies and a WARNING names the profile; set `model.context_length` explicitly to override either way.
+
 ## Available Models
 
 Bedrock models use **inference profile IDs** for on-demand invocation. The `hermes model` picker shows these automatically, with recommended models at the top:

From 418a19cfc74ac693d09cfd3ae7ca29d9777d39f8 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 00:51:37 -0700
Subject: [PATCH 189/190] chore(contributors): map yagnavudathu@gmail.com to
 @whyyagswhy

---
 contributors/emails/yagnavudathu@gmail.com | 1 +
 1 file changed, 1 insertion(+)

diff --git a/contributors/emails/yagnavudathu@gmail.com b/contributors/emails/yagnavudathu@gmail.com
index b335e442ad..45f7f8da59 100644
--- a/contributors/emails/yagnavudathu@gmail.com
+++ b/contributors/emails/yagnavudathu@gmail.com
@@ -1,2 +1,3 @@
 whyyagswhy
 # PR #113725 co-author
+# PR #114478 co-author

From a51143fbbe6ddbc0c7f403d0579c4d75504c6793 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Fri, 18 Sep 2026 02:28:38 -0700
Subject: [PATCH 190/190] fix(bedrock): resolve application-inference-profile
 ARNs before the prompt-cache allowlist match

build_converse_kwargs gated cachePoint markers on the raw model id, so a profile ARN wrapping
Claude matched nothing in _CACHE_POINT_PATTERNS and silently lost Bedrock prompt caching.
_model_supports_prompt_cache now resolves the profile through the per-process-cached
_resolve_inference_profile_model_id first; the request still targets the profile ARN.

Part of #114476
---
 agent/bedrock_adapter.py            |  3 +++
 tests/agent/test_bedrock_adapter.py | 13 +++++++++++++
 2 files changed, 16 insertions(+)

diff --git a/agent/bedrock_adapter.py b/agent/bedrock_adapter.py
index 279e74dac9..c58abe0c86 100644
--- a/agent/bedrock_adapter.py
+++ b/agent/bedrock_adapter.py
@@ -439,6 +439,9 @@ def _model_supports_tool_use(model_id: str) -> bool:
 
 
 def _model_supports_prompt_cache(model_id: str) -> bool:
+    # An application-inference-profile ARN names no model: match on the wrapped model (cached lookup).
+    if _APPLICATION_PROFILE_ARN_RE.search(model_id):
+        model_id = _resolve_inference_profile_model_id(model_id)
     return any(pattern in model_id.lower() for pattern in _CACHE_POINT_PATTERNS)
 
 
diff --git a/tests/agent/test_bedrock_adapter.py b/tests/agent/test_bedrock_adapter.py
index 51c817d48f..5d47079f4c 100644
--- a/tests/agent/test_bedrock_adapter.py
+++ b/tests/agent/test_bedrock_adapter.py
@@ -1105,6 +1105,19 @@ class TestInferenceProfileContextLength:
         assert len(warnings) == 1 and self.ARN in warnings[0].getMessage()
         assert "GetInferenceProfile" in warnings[0].getMessage()
 
+    def test_profile_wrapping_claude_keeps_prompt_cache_markers(self):
+        # build_converse_kwargs gates cachePoint on the model id; the opaque profile ARN must be
+        # resolved to the wrapped Claude (cached lookup) or the profile silently loses prompt caching.
+        from agent.bedrock_adapter import build_converse_kwargs
+        client = MagicMock()
+        client.get_inference_profile.return_value = {"models": [
+            {"modelArn": "arn:aws:bedrock:us-west-2::foundation-model/anthropic.claude-sonnet-4-6"}]}
+        messages = [{"role": "system", "content": "Be helpful."}, {"role": "user", "content": "Hi"}]
+        with patch("agent.bedrock_adapter._get_bedrock_control_client", return_value=client):
+            kwargs = build_converse_kwargs(model=self.ARN, messages=messages)
+        assert kwargs["modelId"] == self.ARN  # the request still targets the profile
+        assert kwargs["system"][-1] == {"cachePoint": {"type": "default"}}
+
 
 class TestBedrockContextProbe:
     """Test the live context-window probe that reads the real window from