From 0b40f5a790a4314fcb97e8dd3d27cf27d3a86424 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Sun, 13 Sep 2026 05:46:05 -0700
Subject: [PATCH] docs: fold the root docs/ tree into the Docusaurus site and
 delete it

docs/ was not the documentation site; it was a grab bag of long-form
design notes, wire contracts and observability guides that landed with
feature PRs because their authors needed somewhere to put them. Root
AGENTS.md already says long-form dev docs live in
website/docs/developer-guide/; this moves the 14 living documents there
(or to the matching user-guide section) so they are published, searchable
and linked from the sidebar instead of being found by grep only.

Developer guide: micro-compaction, gateway-session-lifecycle (was
session-lifecycle), state-db-recovery, multiplexing-gateway,
chronos-managed-cron-contract, relay-connector-contract, observer-hooks
(was observability/README), gateway-monitoring (observability/monitoring),
relay-shared-metrics, middleware, streaming-tts, billing-lifecycle.
User guide: egress/network-isolation (was security/network-egress-
isolation), features/kanban-multi-gateway (was kanban/multi-gateway).

Each page got title/description frontmatter and a sidebar entry; repo-
relative links became site links or GitHub blob URLs; two MDX brace
hazards escaped. Every in-tree pointer (module docstrings, config
comments, the relay conformance test's Path, the monitoring-doc test,
gateway-internals, cron-internals, kanban docs, .dockerignore, AGENTS.md)
now names the new location. `docusaurus build` passes with no unresolved
links on the moved pages.
---
 .dockerignore                                      |  3 +--
 AGENTS.md                                          |  2 +-
 agent/secret_scope.py                              |  4 ++--
 gateway/relay/__init__.py                          |  2 +-
 gateway/relay/descriptor.py                        |  2 +-
 gateway/relay/transport.py                         |  2 +-
 gateway/relay/ws_transport.py                      |  2 +-
 hermes_cli/config_defaults.py                      |  4 ++--
 hermes_cli/subcommands/gateway.py                  |  2 +-
 hermes_state_common.py                             |  2 +-
 plugins/cron_providers/chronos/__init__.py         |  2 +-
 plugins/cron_providers/chronos/_nas_client.py      |  2 +-
 .../gateway/relay/test_contract_doc_conformance.py |  4 ++--
 tests/gateway/relay/test_relay_follow_up.py        |  2 +-
 tests/gateway/relay/test_relay_sheds_crypto.py     |  2 +-
 tests/monitoring/test_cron_health_export.py        |  4 ++--
 .../docs/developer-guide}/billing-lifecycle.md     |  5 +++++
 .../chronos-managed-cron-contract.md               |  5 +++++
 website/docs/developer-guide/cron-internals.md     |  2 +-
 website/docs/developer-guide/gateway-internals.md  |  2 +-
 .../docs/developer-guide/gateway-monitoring.md     |  5 +++++
 .../developer-guide/gateway-session-lifecycle.md   |  9 +++++++--
 .../docs/developer-guide}/micro-compaction.md      |  5 +++++
 .../docs/developer-guide/middleware.md             |  7 ++++++-
 .../docs/developer-guide}/multiplexing-gateway.md  | 12 ++++++++----
 .../docs/developer-guide/observer-hooks.md         |  5 +++++
 .../developer-guide}/relay-connector-contract.md   | 10 +++++++---
 .../docs/developer-guide}/relay-shared-metrics.md  |  5 +++++
 .../docs/developer-guide}/state-db-recovery.md     |  5 +++++
 .../docs/developer-guide}/streaming-tts.md         |  5 +++++
 .../docs/user-guide/egress/network-isolation.md    | 14 ++++++++++----
 .../user-guide/features/kanban-multi-gateway.md    |  5 +++++
 website/docs/user-guide/features/kanban.md         |  2 +-
 .../current/user-guide/features/kanban.md          |  2 +-
 website/sidebars.ts                                | 14 ++++++++++++++
 35 files changed, 121 insertions(+), 39 deletions(-)
 rename {docs => website/docs/developer-guide}/billing-lifecycle.md (99%)
 rename {docs => website/docs/developer-guide}/chronos-managed-cron-contract.md (98%)
 rename docs/observability/monitoring.md => website/docs/developer-guide/gateway-monitoring.md (99%)
 rename docs/session-lifecycle.md => website/docs/developer-guide/gateway-session-lifecycle.md (98%)
 rename {docs => website/docs/developer-guide}/micro-compaction.md (99%)
 rename docs/middleware/README.md => website/docs/developer-guide/middleware.md (97%)
 rename {docs/design => website/docs/developer-guide}/multiplexing-gateway.md (95%)
 rename docs/observability/README.md => website/docs/developer-guide/observer-hooks.md (98%)
 rename {docs => website/docs/developer-guide}/relay-connector-contract.md (99%)
 rename {docs/observability => website/docs/developer-guide}/relay-shared-metrics.md (99%)
 rename {docs => website/docs/developer-guide}/state-db-recovery.md (97%)
 rename {docs => website/docs/developer-guide}/streaming-tts.md (96%)
 rename docs/security/network-egress-isolation.md => website/docs/user-guide/egress/network-isolation.md (90%)
 rename docs/kanban/multi-gateway.md => website/docs/user-guide/features/kanban-multi-gateway.md (92%)

diff --git a/.dockerignore b/.dockerignore
index ae00a18bb9..f773f54263 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -80,9 +80,8 @@ apps/
 # Test suite — not shipped in production images
 tests/
 
-# Documentation site (Docusaurus) and supplementary docs
+# Documentation site (Docusaurus)
 website/
-docs/
 
 # Assets only used by the GitHub README
 assets/
diff --git a/AGENTS.md b/AGENTS.md
index 930a2afc19..fca7cee1d9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -252,7 +252,7 @@ families: `hermes_state.py` (21), `gateway/run.py` (15), `tools/mcp_tool.py` (15
   (`_SLASH_DISPATCH` in `cli.py`, `_command_handler_table` in the gateway are the shape).
 - **No re-export shims for internal moves** ("keep the old name importable"). Internal paths
   are not API; external compat is handled ONCE by the compat layer, not per PR.
-- **Moving a symbol means fixing its docs in the same PR:** grep `website/docs`, `docs/`,
+- **Moving a symbol means fixing its docs in the same PR:** grep `website/docs`,
   `skills/`, and every `AGENTS.md` for the old `path.py` + symbol (23 doc files went stale
   after the refactor). `evals/codebase_navigability/static_metrics.py <tree> <label>` measures
   file/function/CC/elif distributions before/after a large PR in ~2 min.
diff --git a/agent/secret_scope.py b/agent/secret_scope.py
index da5d9b927f..e2dcd2d8a3 100644
--- a/agent/secret_scope.py
+++ b/agent/secret_scope.py
@@ -7,7 +7,7 @@ context-local secret scope: ``set_secret_scope(mapping)`` installs the active
 profile's secrets for the current task (a contextvar, so it propagates into the
 agent's worker thread via ``copy_context()``); ``get_secret(name)`` reads from
 it and, when multiplexing is active with no scope set, RAISES rather than
-falling back to ``os.environ``. Design: ``docs/design/multiplexing-gateway.md``.
+falling back to ``os.environ``. Design: ``website/docs/developer-guide/multiplexing-gateway.md``.
 """
 from __future__ import annotations
 
@@ -132,7 +132,7 @@ def get_secret(name: str, default: Optional[str] = None) -> Optional[str]:
             f"while multiplexing is on. This credential read must run inside a "
             f"set_secret_scope(...) block (the per-turn / per-adapter profile "
             f"scope). Reading os.environ here would risk leaking another "
-            f"profile's value. See docs/design/multiplexing-gateway.md "
+            f"profile's value. See website/docs/developer-guide/multiplexing-gateway.md "
             f"(Workstream A)."
         )
     return _environ_or(name, default)
diff --git a/gateway/relay/__init__.py b/gateway/relay/__init__.py
index 32a1d6b472..0ebefa9474 100644
--- a/gateway/relay/__init__.py
+++ b/gateway/relay/__init__.py
@@ -4,7 +4,7 @@ EXPERIMENTAL gateway side of the "Gateway Gateway" relay design: a generic
 ``RelayAdapter`` plus the wire-serializable ``CapabilityDescriptor`` the connector
 hands it at handshake, and the production ``WebSocketRelayTransport``. The public
 API MAY CHANGE without a deprecation cycle until >=2 real Class-1 platforms have
-shaken out the schema (``docs/relay-connector-contract.md``). Activation is
+shaken out the schema (``website/docs/developer-guide/relay-connector-contract.md``). Activation is
 config-driven: the relay platform is registered when a connector relay URL is set
 (``GATEWAY_RELAY_URL`` env or ``gateway.relay_url``), like ``gateway.proxy_url``,
 unless the effective relay platform configuration explicitly disables it.
diff --git a/gateway/relay/descriptor.py b/gateway/relay/descriptor.py
index 92e9afad34..5385576df3 100644
--- a/gateway/relay/descriptor.py
+++ b/gateway/relay/descriptor.py
@@ -4,7 +4,7 @@ The connector hands one to the gateway's ``RelayAdapter`` at handshake: which
 platform it fronts and which capabilities to advertise to the stream consumer
 (char limit, draft streaming, edit/threading, markdown dialect, length unit), so
 one adapter serves every platform without per-platform branching. Schema evolution
-is additive-only, gated by ``contract_version`` (docs/relay-connector-contract.md).
+is additive-only, gated by ``contract_version`` (website/docs/developer-guide/relay-connector-contract.md).
 """
 
 from __future__ import annotations
diff --git a/gateway/relay/transport.py b/gateway/relay/transport.py
index fb4fcb600a..993a2a4e17 100644
--- a/gateway/relay/transport.py
+++ b/gateway/relay/transport.py
@@ -4,7 +4,7 @@ The ``RelayAdapter`` delegates all wire I/O to a ``RelayTransport``. The gateway
 dials OUT to the connector, so production is a WebSocket client (``ws_transport.py``)
 and tests use an in-memory stub (``tests/gateway/relay/stub_connector.py``). This
 module defines the protocol surface only. May change without a deprecation cycle
-until >=2 Class-1 platforms validate it. See docs/relay-connector-contract.md.
+until >=2 Class-1 platforms validate it. See website/docs/developer-guide/relay-connector-contract.md.
 """
 
 from __future__ import annotations
diff --git a/gateway/relay/ws_transport.py b/gateway/relay/ws_transport.py
index f6bdaa97d5..2f492a4c0a 100644
--- a/gateway/relay/ws_transport.py
+++ b/gateway/relay/ws_transport.py
@@ -1,7 +1,7 @@
 """Production WebSocket RelayTransport — the gateway's live link to the connector.
 
 The gateway dials OUT to the connector's relay endpoint and speaks the
-newline-delimited JSON frame protocol of ``docs/relay-connector-contract.md``:
+newline-delimited JSON frame protocol of ``website/docs/developer-guide/relay-connector-contract.md``:
 gateway -> connector: hello, outbound, interrupt, going_idle, inbound_ack;
 connector -> gateway: descriptor, inbound, outbound_result, interrupt_inbound,
 going_idle_ack, passthrough_forward. Outbound calls block on a per-request future
diff --git a/hermes_cli/config_defaults.py b/hermes_cli/config_defaults.py
index 9c27bd40e5..85033a6c49 100644
--- a/hermes_cli/config_defaults.py
+++ b/hermes_cli/config_defaults.py
@@ -566,7 +566,7 @@ DEFAULT_CONFIG = {
         # micro_compact: opt-in — after each turn fold the oldest un-absorbed exchange into a
         # rolling summary, amortizing compression cost. Off by default because every pass rewrites
         # sent history and breaks the prompt-cache prefix EVERY turn; enable only if the amortized
-        # stall beats the cached-prefix discount. See docs/micro-compaction.md.
+        # stall beats the cached-prefix discount. See website/docs/developer-guide/micro-compaction.md.
         "micro_compact": False,
         # Cadence: run a pass every Nth completed turn (1 = one cache break per turn, 5 = a fifth of
         # the breaks). Clamped >= 1; ignored unless micro_compact is true.
@@ -2105,7 +2105,7 @@ DEFAULT_CONFIG = {
     },
     # Privacy-safe aggregate metrics in this profile's local telemetry dir. Collection (`enabled`)
     # and transmission to Nous (`send`) are SEPARATE opt-ins; see
-    # docs/observability/relay-shared-metrics.md Appendix A for consent/retention.
+    # website/docs/developer-guide/relay-shared-metrics.md Appendix A for consent/retention.
     "telemetry": {
         "shared_metrics": {
             "enabled": False,
diff --git a/hermes_cli/subcommands/gateway.py b/hermes_cli/subcommands/gateway.py
index 017b933b0c..dbd1c3fa0c 100644
--- a/hermes_cli/subcommands/gateway.py
+++ b/hermes_cli/subcommands/gateway.py
@@ -143,7 +143,7 @@ def build_gateway_parser(
     _flag(gateway_migrate, "-y", "--yes", dest="yes", help="Apply without confirmation")
 
     # enroll: redeem a single-use connector token for the per-gateway secret + per-tenant
-    # delivery key, written to .env. See docs/relay-connector-contract.md. EXPERIMENTAL.
+    # delivery key, written to .env. See website/docs/developer-guide/relay-connector-contract.md. EXPERIMENTAL.
     gateway_enroll = gateway_subparsers.add_parser("enroll",
         help="Enroll this gateway with a relay connector (writes relay auth creds to .env)",
         description="Redeem a single-use enrollment token with a relay connector. "
diff --git a/hermes_state_common.py b/hermes_state_common.py
index e49f521deb..453b2ecef4 100644
--- a/hermes_state_common.py
+++ b/hermes_state_common.py
@@ -157,7 +157,7 @@ _RESET_END_REASONS_SQL = ", ".join(f"'{reason}'" for reason in _RESET_END_REASON
 # never heal one of these (#106459); tools/session_search_tool.py derives its fresh-reset set from it.
 _BOUNDARY_END_REASONS = frozenset(_RESET_END_REASONS) | {"new_session"}
 
-# Accidental end reasons recovery treats as resumable (docs/session-lifecycle.md); single source of truth for
+# Accidental end reasons recovery treats as resumable (website/docs/developer-guide/gateway-session-lifecycle.md); single source of truth for
 # recovery SQL and SessionDB.RECOVERABLE_END_REASONS.  superseded_by_resume = sentinel-parked runtime replaced
 # by a fresh session.resume; startup_orphan_reap = dead-gateway sweep, same class as ws_orphan_reap but kept
 # distinct for forensics.
diff --git a/plugins/cron_providers/chronos/__init__.py b/plugins/cron_providers/chronos/__init__.py
index a485d76a6f..0af25f24bc 100644
--- a/plugins/cron_providers/chronos/__init__.py
+++ b/plugins/cron_providers/chronos/__init__.py
@@ -4,7 +4,7 @@ Instead of a 60s ticker, asks NAS to arm one external one-shot per job at its ne
 NAS calls back ``/api/cron/fire`` and the job re-arms after running. start() never blocks or
 spawns a periodic wake; reconcile runs only on a warm process (start / on_jobs_changed / fire).
 Holds no scheduler credentials — speaks only to NAS ``agent-cron`` endpoints with the Nous token.
-Inert unless ``cron.provider: chronos``. Wire contract: ``docs/chronos-managed-cron-contract.md``.
+Inert unless ``cron.provider: chronos``. Wire contract: ``website/docs/developer-guide/chronos-managed-cron-contract.md``.
 """
 
 from __future__ import annotations
diff --git a/plugins/cron_providers/chronos/_nas_client.py b/plugins/cron_providers/chronos/_nas_client.py
index 6dee94c1c6..6777a271d5 100644
--- a/plugins/cron_providers/chronos/_nas_client.py
+++ b/plugins/cron_providers/chronos/_nas_client.py
@@ -1,6 +1,6 @@
 """Thin HTTP client for the agent -> NAS ``agent-cron`` endpoints (Chronos): arm one-shot / cancel /
 list, authenticated with the existing Nous Portal token.
-Wire contract: ``docs/chronos-managed-cron-contract.md``."""
+Wire contract: ``website/docs/developer-guide/chronos-managed-cron-contract.md``."""
 
 from __future__ import annotations
 
diff --git a/tests/gateway/relay/test_contract_doc_conformance.py b/tests/gateway/relay/test_contract_doc_conformance.py
index de24b1d0b4..ccf4e89bf1 100644
--- a/tests/gateway/relay/test_contract_doc_conformance.py
+++ b/tests/gateway/relay/test_contract_doc_conformance.py
@@ -1,4 +1,4 @@
-"""Cross-repo contract conformance: docs/relay-connector-contract.md ⟷ Python.
+"""Cross-repo contract conformance: website/docs/developer-guide/relay-connector-contract.md ⟷ Python.
 
 The contract doc is the formal interface the connector repo
 (NousResearch/gateway-gateway) implements against. The connector's TypeScript
@@ -34,7 +34,7 @@ from gateway.session import SessionSource
 
 # Repo root: tests/gateway/relay/ -> repo root is parents[3]
 _CONTRACT_DOC = (
-    Path(__file__).resolve().parents[3] / "docs" / "relay-connector-contract.md"
+    Path(__file__).resolve().parents[3] / "website" / "docs" / "developer-guide" / "relay-connector-contract.md"
 )
 
 
diff --git a/tests/gateway/relay/test_relay_follow_up.py b/tests/gateway/relay/test_relay_follow_up.py
index 948292213b..e98b39b462 100644
--- a/tests/gateway/relay/test_relay_follow_up.py
+++ b/tests/gateway/relay/test_relay_follow_up.py
@@ -4,7 +4,7 @@ Proves the gateway can act on a shared-identity capability (e.g. a Discord
 interaction follow-up token) WITHOUT ever holding the credential: it names the
 session it is in plus the capability ``kind``, and the connector resolves the
 real value from its vault and egresses. See gateway/relay/transport.py
-(send_follow_up) and docs/relay-connector-contract.md §4.
+(send_follow_up) and website/docs/developer-guide/relay-connector-contract.md §4.
 
 The gateway side is what's exercised here (against the stub connector); the
 connector's resolve + tenant-match enforcement lives in the connector repo
diff --git a/tests/gateway/relay/test_relay_sheds_crypto.py b/tests/gateway/relay/test_relay_sheds_crypto.py
index a3dd96d313..0d84c7b8ae 100644
--- a/tests/gateway/relay/test_relay_sheds_crypto.py
+++ b/tests/gateway/relay/test_relay_sheds_crypto.py
@@ -1,6 +1,6 @@
 """Invariant: the relay path sheds platform crypto — it re-validates nothing.
 
-Under the A2 trust model (see docs/relay-connector-contract.md §6), the
+Under the A2 trust model (see website/docs/developer-guide/relay-connector-contract.md §6), the
 *connector* is the sole crypto/identity boundary: it verifies/decrypts every
 inbound platform payload at the edge (it holds the tenant secrets), normalizes
 it to a tenant-scoped ``MessageEvent``, and forwards only the sanitized event.
diff --git a/tests/monitoring/test_cron_health_export.py b/tests/monitoring/test_cron_health_export.py
index abfa396b9b..5ea801fefd 100644
--- a/tests/monitoring/test_cron_health_export.py
+++ b/tests/monitoring/test_cron_health_export.py
@@ -88,7 +88,7 @@ def test_registered_observable_metric_names_cover_snapshot_metrics(monkeypatch):
     observable-gauge metric_names list, or the OTLP exporter never observes it.
 
     This asserts the vocabulary-registration invariant documented in
-    docs/observability/monitoring.md: an emitted-but-unregistered gauge is
+    website/docs/developer-guide/gateway-monitoring.md: an emitted-but-unregistered gauge is
     silently dropped. Regression guard for background_work / cron additions.
     """
     from agent.monitoring import gateway_health_export
@@ -128,7 +128,7 @@ def test_registered_observable_metric_names_cover_snapshot_metrics(monkeypatch):
 def test_monitoring_docs_distinguish_relay_health_scope_and_terminal_flush():
     from pathlib import Path
 
-    text = Path("docs/observability/monitoring.md").read_text(encoding="utf-8")
+    text = Path("website/docs/developer-guide/gateway-monitoring.md").read_text(encoding="utf-8")
 
     assert "Hermes Agent-owned Relay transport health" in text
     assert "authoritative shared connector/platform state" in text
diff --git a/docs/billing-lifecycle.md b/website/docs/developer-guide/billing-lifecycle.md
similarity index 99%
rename from docs/billing-lifecycle.md
rename to website/docs/developer-guide/billing-lifecycle.md
index 761cdbe0f4..4ac7e406fe 100644
--- a/docs/billing-lifecycle.md
+++ b/website/docs/developer-guide/billing-lifecycle.md
@@ -1,3 +1,8 @@
+---
+title: "Billing Lifecycle (TUI)"
+description: "Map from every billing/subscription state and typed refusal to the exact TUI copy and recovery action"
+---
+
 # Billing lifecycle: client-side state, errors, and recovery
 
 This is the map from every `billing.*`/`subscription.*` state shape the gateway
diff --git a/docs/chronos-managed-cron-contract.md b/website/docs/developer-guide/chronos-managed-cron-contract.md
similarity index 98%
rename from docs/chronos-managed-cron-contract.md
rename to website/docs/developer-guide/chronos-managed-cron-contract.md
index f62de0f80f..fe331fea11 100644
--- a/docs/chronos-managed-cron-contract.md
+++ b/website/docs/developer-guide/chronos-managed-cron-contract.md
@@ -1,3 +1,8 @@
+---
+title: "Chronos Managed-Cron Contract"
+description: "Agent ↔ NAS wire contract for the Chronos cron provider"
+---
+
 # Chronos managed-cron — agent ↔ NAS wire contract
 
 **Status:** authoritative wire spec for the Chronos cron provider.
diff --git a/website/docs/developer-guide/cron-internals.md b/website/docs/developer-guide/cron-internals.md
index a8bab0a297..ca39feb6bc 100644
--- a/website/docs/developer-guide/cron-internals.md
+++ b/website/docs/developer-guide/cron-internals.md
@@ -224,7 +224,7 @@ If Chronos is misconfigured or the agent isn't logged into Nous,
 `resolve_cron_scheduler()` falls back to the built-in ticker (logged warning) —
 cron never loses its trigger. Recurring jobs re-arm after each fire; `repeat`-N
 jobs stop cleanly when the count is exhausted (no orphaned one-shot). The full
-agent↔Nous wire contract lives in `docs/chronos-managed-cron-contract.md`.
+agent↔Nous wire contract lives in [Chronos managed-cron contract](chronos-managed-cron-contract.md).
 
 ### Fresh Session Isolation
 
diff --git a/website/docs/developer-guide/gateway-internals.md b/website/docs/developer-guide/gateway-internals.md
index 5b92103db3..2e5361b1fb 100644
--- a/website/docs/developer-guide/gateway-internals.md
+++ b/website/docs/developer-guide/gateway-internals.md
@@ -176,7 +176,7 @@ gateway/platforms/                  # core base + legacy direct adapters
 
 **Deferred loading:** Bundled `kind: platform` plugins register cheap `register_deferred` loaders in `gateway/platform_registry.py` (via `hermes_cli/plugins.py`) so platform SDKs import only when the gateway starts, delivers, or runs setup/status — not on plain `hermes chat`. Resolution loads one adapter on lookup; full enumeration runs pending loaders only on paths that need every platform.
 
-Experimental connector-backed platforms use the generic relay adapter in `gateway/relay/` instead of a direct platform module. When `GATEWAY_RELAY_URL` or `gateway.relay_url` is configured, the gateway registers the `relay` platform, dials the connector over an outbound WebSocket, and receives `descriptor`, `inbound`, and `interrupt_inbound` frames on that same socket. The connector advertises a `CapabilityDescriptor`; Hermes can send normal outbound replies, token-less `follow_up` operations, and interrupt frames back through the relay. The source-grounded wire contract lives in [`docs/relay-connector-contract.md`](https://github.com/NousResearch/hermes-agent/blob/main/docs/relay-connector-contract.md).
+Experimental connector-backed platforms use the generic relay adapter in `gateway/relay/` instead of a direct platform module. When `GATEWAY_RELAY_URL` or `gateway.relay_url` is configured, the gateway registers the `relay` platform, dials the connector over an outbound WebSocket, and receives `descriptor`, `inbound`, and `interrupt_inbound` frames on that same socket. The connector advertises a `CapabilityDescriptor`; Hermes can send normal outbound replies, token-less `follow_up` operations, and interrupt frames back through the relay. The source-grounded wire contract lives in [Relay ↔ Connector contract](relay-connector-contract.md).
 
 Adapters implement a common interface:
 - `connect()` / `disconnect()` — lifecycle management
diff --git a/docs/observability/monitoring.md b/website/docs/developer-guide/gateway-monitoring.md
similarity index 99%
rename from docs/observability/monitoring.md
rename to website/docs/developer-guide/gateway-monitoring.md
index cba4ead1ff..dbea45a939 100644
--- a/docs/observability/monitoring.md
+++ b/website/docs/developer-guide/gateway-monitoring.md
@@ -1,3 +1,8 @@
+---
+title: "Gateway Monitoring"
+description: "Health export, structured diagnostics, fleet queries and how to extend the monitoring plane"
+---
+
 # Gateway Monitoring
 
 Service health monitoring plus structured operational diagnostics for the
diff --git a/docs/session-lifecycle.md b/website/docs/developer-guide/gateway-session-lifecycle.md
similarity index 98%
rename from docs/session-lifecycle.md
rename to website/docs/developer-guide/gateway-session-lifecycle.md
index 7e22ad6be6..69cefef544 100644
--- a/docs/session-lifecycle.md
+++ b/website/docs/developer-guide/gateway-session-lifecycle.md
@@ -1,3 +1,8 @@
+---
+title: "Gateway Session Lifecycle"
+description: "SessionSource, SessionEntry, SessionStore, session-key rules and multi-user isolation in the gateway"
+---
+
 # Session Lifecycle
 
 > **Audience:** Gateway developers and maintainers
@@ -282,7 +287,7 @@ def is_shared_multi_user_session(source, *, group_sessions_per_user, thread_sess
 ### Impact on System Prompt
 
 When `shared_multi_user_session=True`, the system prompt omits a fixed user name and instead
-states: *"Multi-user {thread|session} — messages are prefixed with [sender name]. Multiple
+states: *"Multi-user \{thread|session\} — messages are prefixed with [sender name]. Multiple
 users may participate."* Individual sender names are prefixed on each user message by the
 gateway at runtime, preserving prompt caching (the system prompt doesn't change per-turn).
 
@@ -605,7 +610,7 @@ conversation boundaries and shutdown.
 The canonical transcript lives in the `sessions` and `messages` tables. FTS5
 tables and their sync triggers are derived indexes that can be detached and
 rebuilt without deleting canonical messages. See
-[`docs/state-db-recovery.md`](state-db-recovery.md) for the bounded live failure
+[State DB recovery](state-db-recovery.md) for the bounded live failure
 mode and the explicit repair procedure.
 
 ### Conversation lifetime
diff --git a/docs/micro-compaction.md b/website/docs/developer-guide/micro-compaction.md
similarity index 99%
rename from docs/micro-compaction.md
rename to website/docs/developer-guide/micro-compaction.md
index 7c4a7176ba..27a332b687 100644
--- a/docs/micro-compaction.md
+++ b/website/docs/developer-guide/micro-compaction.md
@@ -1,3 +1,8 @@
+---
+title: "Micro-compaction"
+description: "How micro-compaction amortizes context compression cost: triggers, tail sizing, the cached-prefix trade-off"
+---
+
 # Micro-compaction
 
 **A way to amortize the cost of compression.**
diff --git a/docs/middleware/README.md b/website/docs/developer-guide/middleware.md
similarity index 97%
rename from docs/middleware/README.md
rename to website/docs/developer-guide/middleware.md
index 96304fa0e1..ad1764f904 100644
--- a/docs/middleware/README.md
+++ b/website/docs/developer-guide/middleware.md
@@ -1,3 +1,8 @@
+---
+title: "Middleware"
+description: "Behavior-changing plugin middleware for LLM and tool calls: contract, execution order, examples"
+---
+
 # Hermes Middleware
 
 Hermes middleware is the behavior-changing companion to observer hooks.
@@ -235,7 +240,7 @@ payload to later middleware and the base tool dispatcher.
 Plugin-specific examples should live with the plugin that owns the behavior.
 NeMo Relay execution middleware is installed through an explicitly selected
 Relay `plugins.toml`; see
-[Relay shared metrics](../observability/relay-shared-metrics.md).
+[Relay shared metrics](relay-shared-metrics.md).
 
 ## Safety Notes
 
diff --git a/docs/design/multiplexing-gateway.md b/website/docs/developer-guide/multiplexing-gateway.md
similarity index 95%
rename from docs/design/multiplexing-gateway.md
rename to website/docs/developer-guide/multiplexing-gateway.md
index cb9c5da63e..7f9ac7db94 100644
--- a/docs/design/multiplexing-gateway.md
+++ b/website/docs/developer-guide/multiplexing-gateway.md
@@ -1,3 +1,8 @@
+---
+title: "Multiplexing Gateway Internals"
+description: "Design of the one-gateway-for-all-profiles mode: scope composition, secret scope, inbound routing, persistence"
+---
+
 # Multiplexing Gateway
 
 One gateway process can serve every profile in the install. The mode is opt-in
@@ -124,7 +129,7 @@ profile; matching is conjunctive, most-specific-first, with parent-chain chat
 matching for threads. Routing only runs when multiplexing is active, and a
 matched route whose target is outside the served set is rejected (the event is
 dropped, not misdelivered). Full schema and matching rules:
-`docs/profile-routing.md`.
+[Routing shared-bot chats to profiles](../user-guide/multi-profile-gateways.md#routing-shared-bot-chats-to-profiles-profile_routes).
 
 ## Serving selected profiles
 
@@ -200,9 +205,8 @@ out of scope for this document.
 
 ## Related
 
-- `docs/profile-routing.md` — inbound routing schema and matching rules.
-- `website/docs/user-guide/multi-profile-gateways.md` — user-facing guide,
-  including the standalone one-gateway-per-profile alternative.
+- [Multi-profile gateways](../user-guide/multi-profile-gateways.md) — user-facing guide, including `profile_routes`
+  and the standalone one-gateway-per-profile alternative.
 - `agent/secret_scope.py`, `hermes_constants.py`, `gateway/profile_routing.py`,
   `gateway/run.py` (`_profile_runtime_scope`), `hermes_cli/profiles.py`
   (`profiles_to_serve`), `gateway/session.py`, `tui_gateway/methods_profiles.py`.
diff --git a/docs/observability/README.md b/website/docs/developer-guide/observer-hooks.md
similarity index 98%
rename from docs/observability/README.md
rename to website/docs/developer-guide/observer-hooks.md
index 4a05ec5013..30b912dda1 100644
--- a/docs/observability/README.md
+++ b/website/docs/developer-guide/observer-hooks.md
@@ -1,3 +1,8 @@
+---
+title: "Observer Hooks"
+description: "Read-only telemetry contract for plugins: event families, correlation IDs, payload safety"
+---
+
 # Hermes Observer Hooks
 
 Hermes observer hooks are the read-only telemetry contract for plugins that
diff --git a/docs/relay-connector-contract.md b/website/docs/developer-guide/relay-connector-contract.md
similarity index 99%
rename from docs/relay-connector-contract.md
rename to website/docs/developer-guide/relay-connector-contract.md
index a4038f8d41..5f8a3f6d75 100644
--- a/docs/relay-connector-contract.md
+++ b/website/docs/developer-guide/relay-connector-contract.md
@@ -1,3 +1,8 @@
+---
+title: "Relay ↔ Connector Contract"
+description: "Wire contract between the Hermes gateway relay adapter and external connectors (experimental)"
+---
+
 # Relay ↔ Connector Contract (v1, EXPERIMENTAL)
 
 > **Status:** EXPERIMENTAL. This contract MAY CHANGE without a deprecation
@@ -118,8 +123,7 @@ Both absent ⇒ byte-identical to today. A connector that never sends them, or a
 `dm`, or a no-context platform, yields no `channel_context`.
 
 `PassthroughForward` is the wire form of a forwarded passthrough-plane request
-(Class-2/3 webhooks — Discord interactions, Twilio): `{platform, botId, method,
-path, headers: [[k,v],…], bodyB64, profile?}`. `profile` is optional — the
+(Class-2/3 webhooks — Discord interactions, Twilio): `{platform, botId, method, path, headers: [[k,v],…], bodyB64, profile?}`. `profile` is optional — the
 connector stamps it when NAS resolves the target profile for a Team-Gateway
 interaction; omitting it (single-profile gateways) preserves legacy routing to
 the default `agent:main` session namespace, mirroring the `profile` field the
@@ -763,7 +767,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 `website/docs/user-guide/messaging/slack.md`.
+key: see [Slack](/user-guide/messaging/slack).
 
 Thread-anchor resolution applies to EVERY send lane — text (`send`) and media
 (`send_media`) alike — through one choke point
diff --git a/docs/observability/relay-shared-metrics.md b/website/docs/developer-guide/relay-shared-metrics.md
similarity index 99%
rename from docs/observability/relay-shared-metrics.md
rename to website/docs/developer-guide/relay-shared-metrics.md
index 23d016659c..2a8b7de2a8 100644
--- a/docs/observability/relay-shared-metrics.md
+++ b/website/docs/developer-guide/relay-shared-metrics.md
@@ -1,3 +1,8 @@
+---
+title: "Relay Shared Metrics"
+description: "NeMo Relay shared metrics: what is exported, consent and retention, staging validation"
+---
+
 # NeMo Relay Shared Metrics
 
 Hermes includes NeMo Relay as a normal runtime dependency on platforms for
diff --git a/docs/state-db-recovery.md b/website/docs/developer-guide/state-db-recovery.md
similarity index 97%
rename from docs/state-db-recovery.md
rename to website/docs/developer-guide/state-db-recovery.md
index 5cb69fb928..7a7af15bd6 100644
--- a/docs/state-db-recovery.md
+++ b/website/docs/developer-guide/state-db-recovery.md
@@ -1,3 +1,8 @@
+---
+title: "State DB Recovery"
+description: "How Hermes recovers state.db when the FTS index or the file itself is corrupt"
+---
+
 # State database and FTS recovery
 
 `state.db` stores two different data classes:
diff --git a/docs/streaming-tts.md b/website/docs/developer-guide/streaming-tts.md
similarity index 96%
rename from docs/streaming-tts.md
rename to website/docs/developer-guide/streaming-tts.md
index 1db2c812a6..72981dff27 100644
--- a/docs/streaming-tts.md
+++ b/website/docs/developer-guide/streaming-tts.md
@@ -1,3 +1,8 @@
+---
+title: "Streaming TTS Internals"
+description: "Sentence chunker, streaming provider ABC, capability matrix and how to add a streaming TTS provider"
+---
+
 # Streaming TTS
 
 Hermes can stream TTS audio as it arrives from the provider, instead of waiting
diff --git a/docs/security/network-egress-isolation.md b/website/docs/user-guide/egress/network-isolation.md
similarity index 90%
rename from docs/security/network-egress-isolation.md
rename to website/docs/user-guide/egress/network-isolation.md
index 46cde2fd74..0c0049974b 100644
--- a/docs/security/network-egress-isolation.md
+++ b/website/docs/user-guide/egress/network-isolation.md
@@ -1,3 +1,8 @@
+---
+title: "Network Egress Isolation (Docker)"
+description: "Segment Docker networks so the agent sandbox can only reach allowlisted hosts"
+---
+
 # Network Egress Isolation for Docker Deployments
 
 When running Hermes inside Docker, the default `network_mode: host` gives the
@@ -11,7 +16,7 @@ commands.
 
 ## Threat Model
 
-The Hermes [SECURITY.md](../../SECURITY.md) §2 defines the trust model. The
+The Hermes [SECURITY.md](https://github.com/NousResearch/hermes-agent/blob/main/SECURITY.md) §2 defines the trust model. The
 terminal backend is the primary execution boundary. However, when running with
 `network_mode: host`, any command the agent executes can reach any endpoint on
 the network, including external ones.
@@ -190,6 +195,7 @@ docker compose exec gateway \
 
 ## Related
 
-- [SECURITY.md](../../SECURITY.md) — Hermes trust model and vulnerability reporting
-- [Terminal backends](../../README.md) — sandboxed execution targets
-- [docker-compose.yml](../../docker-compose.yml) — default compose configuration
+- [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
+- [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/docs/kanban/multi-gateway.md b/website/docs/user-guide/features/kanban-multi-gateway.md
similarity index 92%
rename from docs/kanban/multi-gateway.md
rename to website/docs/user-guide/features/kanban-multi-gateway.md
index 18d55799f7..8ff65d8222 100644
--- a/docs/kanban/multi-gateway.md
+++ b/website/docs/user-guide/features/kanban-multi-gateway.md
@@ -1,3 +1,8 @@
+---
+title: "Kanban Multi-Gateway Deployment"
+description: "Running one kanban board across several per-profile gateways: single dispatcher, profile-owned delivery"
+---
+
 # Multi-gateway deployment
 
 Hermes supports multiple gateway processes running concurrently — one per profile
diff --git a/website/docs/user-guide/features/kanban.md b/website/docs/user-guide/features/kanban.md
index b3398bf744..85913e3bc1 100644
--- a/website/docs/user-guide/features/kanban.md
+++ b/website/docs/user-guide/features/kanban.md
@@ -1144,7 +1144,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](https://github.com/NousResearch/hermes-agent/blob/main/docs/kanban/multi-gateway.md)),
+guide](/user-guide/features/kanban-multi-gateway)),
 dispatch and delivery have separate owners:
 
 - **Dispatch stays single-owner.** Exactly one gateway keeps
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 d9d4e8d40b..0c78159f7c 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 指南](https://github.com/NousResearch/hermes-agent/blob/main/docs/kanban/multi-gateway.md)），
+运行独立的 gateway 进程 —— 参见[多 gateway 指南](/user-guide/features/kanban-multi-gateway)），
 调度与投递的归属是分开的：
 
 - **调度保持单一所有者。** 只有一个 gateway 保持
diff --git a/website/sidebars.ts b/website/sidebars.ts
index ff5a329559..7951d983d8 100644
--- a/website/sidebars.ts
+++ b/website/sidebars.ts
@@ -48,6 +48,7 @@ const sidebars: SidebarsConfig = {
           items: [
             'user-guide/egress/index',
             'user-guide/egress/iron-proxy',
+            'user-guide/egress/network-isolation',
           ],
         },
         'user-guide/sessions',
@@ -102,6 +103,7 @@ const sidebars: SidebarsConfig = {
             'user-guide/features/codex-app-server-runtime',
             'user-guide/features/kanban-tutorial',
             'user-guide/features/kanban-worker-lanes',
+            'user-guide/features/kanban-multi-gateway',
             'user-guide/features/goals',
             'user-guide/features/heartbeat',
             'user-guide/features/loops',
@@ -779,9 +781,13 @@ const sidebars: SidebarsConfig = {
             'developer-guide/agent-loop',
             'developer-guide/prompt-assembly',
             'developer-guide/context-compression-and-caching',
+            'developer-guide/micro-compaction',
             'developer-guide/gateway-internals',
+            'developer-guide/gateway-session-lifecycle',
+            'developer-guide/multiplexing-gateway',
             'developer-guide/completion-backlog-delivery',
             'developer-guide/session-storage',
+            'developer-guide/state-db-recovery',
             'developer-guide/provider-runtime',
             'developer-guide/programmatic-integration',
           ],
@@ -799,6 +805,8 @@ const sidebars: SidebarsConfig = {
               link: {type: 'doc', id: 'developer-guide/plugins/index'},
               items: [
                 'developer-guide/plugin-llm-access',
+                'developer-guide/observer-hooks',
+                'developer-guide/middleware',
                 'developer-guide/subagent-lifecycle-api',
                 'developer-guide/desktop-plugin-sdk',
                 'developer-guide/memory-provider-plugin',
@@ -824,7 +832,13 @@ const sidebars: SidebarsConfig = {
             'developer-guide/browser-supervisor',
             'developer-guide/acp-internals',
             'developer-guide/cron-internals',
+            'developer-guide/chronos-managed-cron-contract',
             'developer-guide/egress-internals',
+            'developer-guide/gateway-monitoring',
+            'developer-guide/relay-connector-contract',
+            'developer-guide/relay-shared-metrics',
+            'developer-guide/streaming-tts',
+            'developer-guide/billing-lifecycle',
             'developer-guide/trajectory-format',
           ],
         },