From 718dba8cb69201e3163a62a3542a9777e4df0538 Mon Sep 17 00:00:00 2001
From: Seb Slight <sebslight@gmail.com>
Date: Wed, 4 Feb 2026 10:37:14 -0500
Subject: [PATCH] Docs: landing page revamp (#8885)

* Docs: refresh landing page

* Docs: add landing page companion pages

* Docs: drop legacy Jekyll assets

* Docs: remove legacy terminal css test

* Docs: restore terminal css assets

* Docs: remove terminal css assets
---
 docs/_config.yml              |  53 ----
 docs/_layouts/default.html    | 145 -----------
 docs/assets/markdown.css      | 179 -------------
 docs/assets/terminal.css      | 473 ----------------------------------
 docs/assets/theme.js          |  55 ----
 docs/concepts/features.md     |  53 ++++
 docs/custom.css               |   4 +
 docs/docs.json                |  60 +++--
 docs/gateway/network-model.md |  17 ++
 docs/index.md                 | 315 +++++++++-------------
 docs/reference/credits.md     |  27 ++
 docs/start/docs-directory.md  |  63 +++++
 docs/start/quickstart.md      |  81 ++++++
 src/docs/terminal-css.test.ts |  28 --
 14 files changed, 405 insertions(+), 1148 deletions(-)
 delete mode 100644 docs/_config.yml
 delete mode 100644 docs/_layouts/default.html
 delete mode 100644 docs/assets/markdown.css
 delete mode 100644 docs/assets/terminal.css
 delete mode 100644 docs/assets/theme.js
 create mode 100644 docs/concepts/features.md
 create mode 100644 docs/custom.css
 create mode 100644 docs/gateway/network-model.md
 create mode 100644 docs/reference/credits.md
 create mode 100644 docs/start/docs-directory.md
 create mode 100644 docs/start/quickstart.md
 delete mode 100644 src/docs/terminal-css.test.ts
diff --git a/docs/_config.yml b/docs/_config.yml
deleted file mode 100644
index 4466a5291..000000000
--- a/docs/_config.yml
+++ /dev/null
@@ -1,53 +0,0 @@
-title: "OpenClaw Docs"
-description: "A TypeScript/Node gateway + macOS/iOS/Android companions for WhatsApp (web) and Telegram (bot)."
-markdown: kramdown
-highlighter: rouge
-
-# Keep GitHub Pages' default page URLs (e.g. /gateway.html). Many docs links
-# are written as relative *.md links and are rewritten during the build.
-
-plugins:
-  - jekyll-relative-links
-
-relative_links:
-  enabled: true
-  collections: true
-
-defaults:
-  - scope:
-      path: ""
-    values:
-      layout: default
-
-nav:
-  - title: "Home"
-    url: "/"
-  - title: "OpenClaw Assistant"
-    url: "/start/openclaw/"
-  - title: "Gateway"
-    url: "/gateway/"
-  - title: "Remote"
-    url: "/gateway/remote/"
-  - title: "Discovery"
-    url: "/gateway/discovery/"
-  - title: "Configuration"
-    url: "/gateway/configuration/"
-  - title: "WebChat"
-    url: "/web/webchat/"
-  - title: "macOS App"
-    url: "/platforms/macos/"
-  - title: "iOS App"
-    url: "/platforms/ios/"
-  - title: "Android App"
-    url: "/platforms/android/"
-  - title: "Telegram"
-    url: "/channels/telegram/"
-  - title: "Security"
-    url: "/gateway/security/"
-  - title: "Troubleshooting"
-    url: "/gateway/troubleshooting/"
-
-kramdown:
-  input: GFM
-  hard_wrap: false
-  syntax_highlighter: rouge
diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
deleted file mode 100644
index dfff0b9ad..000000000
--- a/docs/_layouts/default.html
+++ /dev/null
@@ -1,145 +0,0 @@
-<!doctype html>
-<html lang="en" data-theme="auto">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <meta name="color-scheme" content="light dark" />
-    <title>
-      {% if page.url == "/" %}{{ site.title }}{% else %}{{ page.title | default: page.path | split: "/" | last | replace: ".md", "" }} · {{ site.title }}{% endif %}
-    </title>
-
-    <link rel="preconnect" href="https://fonts.googleapis.com" />
-    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-    <link
-      href="https://fonts.googleapis.com/css2?family=Pixelify+Sans:wght@400..700&family=Fragment+Mono:ital,wght@0,400;0,700;1,400;1,700&display=swap"
-      rel="stylesheet"
-    />
-    <script>
-      (() => {
-        try {
-          const stored = localStorage.getItem("openclaw:theme");
-          if (stored === "light" || stored === "dark") document.documentElement.dataset.theme = stored;
-        } catch {
-          // ignore
-        }
-      })();
-    </script>
-    <link rel="stylesheet" href="{{ "/assets/terminal.css" | relative_url }}" />
-    <link rel="stylesheet" href="{{ "/assets/markdown.css" | relative_url }}" />
-    <script defer src="{{ "/assets/theme.js" | relative_url }}"></script>
-  </head>
-
-  <body>
-    <a class="skip-link" href="#content">Skip to content</a>
-
-    <header class="shell">
-      <div class="shell__frame" role="banner">
-        <div class="shell__titlebar">
-          <div class="brand" aria-label="OpenClaw docs terminal">
-            <img
-              class="brand__logo"
-              src="{{ "/assets/pixel-lobster.svg" | relative_url }}"
-              alt=""
-              width="40"
-              height="40"
-              decoding="async"
-            />
-            <div class="brand__text">
-              <div class="brand__name">OpenClaw</div>
-              <div class="brand__hint">docs // lobster terminal</div>
-            </div>
-          </div>
-
-          <div class="titlebar__actions">
-            <a class="titlebar__cta" href="https://github.com/openclaw/openclaw">
-              <span class="titlebar__cta-label">GitHub</span>
-              <span class="titlebar__cta-meta">repo</span>
-            </a>
-            <a class="titlebar__cta titlebar__cta--accent" href="https://github.com/openclaw/openclaw/releases/latest">
-              <span class="titlebar__cta-label">Download</span>
-              <span class="titlebar__cta-meta">latest</span>
-            </a>
-          </div>
-        </div>
-
-        <div class="shell__nav" aria-label="Primary">
-          <nav class="nav">
-            {% assign nav = site.nav | default: empty %}
-            {% for item in nav %}
-              {% assign item_url = item.url | relative_url %}
-              <a class="nav__link" href="{{ item_url }}">
-                <span class="nav__chev">›</span>{{ item.title }}
-              </a>
-            {% endfor %}
-          </nav>
-
-          <div class="shell__status" aria-hidden="true">
-            <span class="status__dot"></span>
-            <span class="status__text">
-              {% if page.url == "/" %}
-                ready
-              {% else %}
-                viewing: {{ page.path }}
-              {% endif %}
-            </span>
-          </div>
-        </div>
-      </div>
-    </header>
-
-    <main id="content" class="content" role="main">
-      <div class="terminal">
-        <div class="terminal__prompt" aria-hidden="true">
-          <span class="prompt__user">openclaw</span>@<span class="prompt__host">openclaw</span>:<span class="prompt__path">~/docs</span>$<span class="prompt__cmd">
-            {% if page.url == "/" %}cat index.md{% else %}less {{ page.path }}{% endif %}
-          </span>
-        </div>
-
-        {% if page.summary %}
-          <p class="terminal__summary">{{ page.summary }}</p>
-        {% endif %}
-
-        {% if page.read_when %}
-          <details class="terminal__meta">
-            <summary>Read when…</summary>
-            <ul>
-              {% for hint in page.read_when %}
-                <li>{{ hint }}</li>
-              {% endfor %}
-            </ul>
-          </details>
-        {% endif %}
-
-        <article class="markdown">
-          {{ content }}
-        </article>
-
-        <footer class="terminal__footer" role="contentinfo">
-          <div class="footer__line">
-            <span class="footer__sig">openclaw.ai</span>
-            <span class="footer__sep">·</span>
-            <a href="https://github.com/openclaw/openclaw">source</a>
-            <span class="footer__sep">·</span>
-            <a href="https://github.com/openclaw/openclaw/releases">releases</a>
-          </div>
-          <div class="footer__hint" aria-hidden="true">
-            tip: press <kbd>F2</kbd> (Mac: <kbd>fn</kbd>+<kbd>F2</kbd>) to flip
-            the universe
-          </div>
-          <div class="footer__actions">
-            <button
-              class="theme-toggle"
-              type="button"
-              data-theme-toggle
-              aria-label="Toggle theme (F2; on Mac: fn+F2)"
-              aria-pressed="false"
-            >
-              <span class="theme-toggle__key">F2</span>
-              <span class="theme-toggle__label" data-theme-label>theme</span>
-            </button>
-          </div>
-	        </footer>
-	      </div>
-	    </main>
-	  </body>
-</html>
diff --git a/docs/assets/markdown.css b/docs/assets/markdown.css
deleted file mode 100644
index 6ad456334..000000000
--- a/docs/assets/markdown.css
+++ /dev/null
@@ -1,179 +0,0 @@
-.markdown {
-  margin-top: 18px;
-  line-height: 1.7;
-}
-
-.mdx-content > h1:first-of-type {
-  display: none;
-}
-
-.markdown h1,
-.markdown h2,
-.markdown h3,
-.markdown h4 {
-  font-family: var(--font-pixel);
-  letter-spacing: 0.04em;
-  line-height: 1.15;
-}
-
-.markdown h1 {
-  font-size: clamp(28px, 4vw, 44px);
-  margin: 26px 0 10px;
-}
-
-.markdown h2 {
-  font-size: 22px;
-  margin: 26px 0 10px;
-}
-
-.markdown h3 {
-  font-size: 18px;
-  margin: 22px 0 8px;
-}
-
-.markdown p {
-  margin: 0 0 14px;
-}
-
-.markdown a {
-  color: var(--link);
-  text-decoration: none;
-  border-bottom: 1px dotted color-mix(in oklab, var(--link) 65%, transparent);
-}
-
-.markdown a:hover {
-  color: var(--link2);
-  border-bottom-color: color-mix(in oklab, var(--link2) 75%, transparent);
-}
-
-.markdown hr {
-  border: 0;
-  height: 1px;
-  background: linear-gradient(
-    90deg,
-    transparent,
-    color-mix(in oklab, var(--frame-border) 30%, transparent),
-    transparent
-  );
-  margin: 26px 0;
-}
-
-.markdown blockquote {
-  margin: 18px 0;
-  padding: 14px 14px;
-  border-radius: var(--radius-sm);
-  background: color-mix(in oklab, var(--panel) 70%, transparent);
-  border-left: 6px solid color-mix(in oklab, var(--accent) 60%, transparent);
-  color: var(--muted);
-}
-
-.markdown ul,
-.markdown ol {
-  margin: 0 0 14px 22px;
-}
-
-.markdown li {
-  margin: 4px 0;
-}
-
-.markdown img {
-  max-width: 100%;
-  height: auto;
-  border-radius: 12px;
-  border: 1px solid color-mix(in oklab, var(--frame-border) 20%, transparent);
-  box-shadow: 0 12px 0 -8px rgba(0, 0, 0, 0.18);
-}
-
-.showcase-link {
-  position: relative;
-  display: inline-flex;
-  align-items: center;
-  gap: 6px;
-}
-
-.showcase-preview {
-  position: absolute;
-  left: 50%;
-  top: 100%;
-  width: min(420px, 80vw);
-  padding: 8px;
-  border-radius: 14px;
-  background: color-mix(in oklab, var(--panel) 92%, transparent);
-  border: 1px solid color-mix(in oklab, var(--frame-border) 30%, transparent);
-  box-shadow: 0 18px 40px -18px rgba(0, 0, 0, 0.55);
-  transform: translate(-50%, 10px) scale(0.98);
-  opacity: 0;
-  visibility: hidden;
-  pointer-events: none;
-  z-index: 20;
-  transition: opacity 0.18s ease, transform 0.18s ease, visibility 0.18s ease;
-}
-
-.showcase-preview img {
-  width: 100%;
-  height: auto;
-  border-radius: 10px;
-  border: 1px solid color-mix(in oklab, var(--frame-border) 25%, transparent);
-  box-shadow: none;
-}
-
-.showcase-link:hover .showcase-preview,
-.showcase-link:focus-within .showcase-preview {
-  opacity: 1;
-  visibility: visible;
-  transform: translate(-50%, 6px) scale(1);
-}
-
-@media (hover: none) {
-  .showcase-preview {
-    display: none;
-  }
-}
-
-.markdown code {
-  font-family: var(--font-body);
-  font-size: 0.95em;
-  padding: 0.15em 0.35em;
-  border-radius: 8px;
-  background: color-mix(in oklab, var(--panel) 70%, var(--code-bg));
-  border: 1px solid color-mix(in oklab, var(--frame-border) 18%, transparent);
-}
-
-.markdown pre {
-  background: var(--code-bg);
-  color: var(--code-fg);
-  padding: 14px 14px;
-  border-radius: var(--radius-sm);
-  border: 1px solid color-mix(in oklab, var(--frame-border) 18%, transparent);
-  overflow-x: auto;
-  box-shadow: inset 0 0 0 1px color-mix(in oklab, var(--code-accent) 12%, transparent);
-}
-
-.markdown pre code {
-  background: transparent;
-  border: 0;
-  padding: 0;
-  color: inherit;
-}
-
-.markdown table {
-  width: 100%;
-  border-collapse: collapse;
-  margin: 16px 0 22px;
-  border: 1px solid color-mix(in oklab, var(--frame-border) 20%, transparent);
-  border-radius: var(--radius-sm);
-  overflow: hidden;
-}
-
-.markdown th,
-.markdown td {
-  padding: 10px 10px;
-  border-bottom: 1px solid color-mix(in oklab, var(--frame-border) 15%, transparent);
-  vertical-align: top;
-}
-
-.markdown th {
-  background: color-mix(in oklab, var(--panel2) 85%, transparent);
-  font-family: var(--font-pixel);
-  letter-spacing: 0.06em;
-}
diff --git a/docs/assets/terminal.css b/docs/assets/terminal.css
deleted file mode 100644
index e5e51af9e..000000000
--- a/docs/assets/terminal.css
+++ /dev/null
@@ -1,473 +0,0 @@
-:root {
-  --font-body: "Fragment Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
-  --font-pixel: "Pixelify Sans", system-ui, sans-serif;
-  --radius: 14px;
-  --radius-sm: 10px;
-  --border: 2px;
-  --shadow-px: 0 0 0 var(--border) var(--frame-border), 0 12px 0 -4px rgba(0, 0, 0, 0.25);
-  --scanline-size: 6px;
-  --scanline-opacity: 0.08;
-}
-
-html[data-theme="light"],
-html[data-theme="auto"] {
-  --bg0: #fbf4e7;
-  --bg1: #fffaf0;
-  --panel: #fffdf8;
-  --panel2: #fff6e5;
-  --text: #10221c;
-  --muted: #3e5a50;
-  --faint: #6b7f77;
-  --link: #0f6b4c;
-  --link2: #ff4f40;
-  --accent: #ff4f40;
-  --accent2: #00b88a;
-  --frame-border: #1b2e27;
-  --code-bg: #0b1713;
-  --code-fg: #eafff6;
-  --code-accent: #67ff9b;
-}
-
-html[data-theme="dark"] {
-  --bg0: #0b1a22;
-  --bg1: #0a1720;
-  --panel: #0e231f;
-  --panel2: #102a24;
-  --text: #c9eadc;
-  --muted: #8ab8aa;
-  --faint: #699b8d;
-  --link: #6fe8c7;
-  --link2: #ff7b63;
-  --accent: #ff4f40;
-  --accent2: #5fdfa2;
-  --frame-border: #6fbfa8;
-  --code-bg: #091814;
-  --code-fg: #d7f5e8;
-  --code-accent: #5fdfa2;
-}
-
-@media (prefers-color-scheme: dark) {
-  html[data-theme="auto"] {
-    --bg0: #0b1a22;
-    --bg1: #0a1720;
-    --panel: #0e231f;
-    --panel2: #102a24;
-    --text: #c9eadc;
-    --muted: #8ab8aa;
-    --faint: #699b8d;
-    --link: #6fe8c7;
-    --link2: #ff7b63;
-    --accent: #ff4f40;
-    --accent2: #5fdfa2;
-    --frame-border: #6fbfa8;
-    --code-bg: #091814;
-    --code-fg: #d7f5e8;
-    --code-accent: #5fdfa2;
-  }
-}
-
-* {
-  box-sizing: border-box;
-}
-
-html {
-  height: 100%;
-}
-
-body {
-  min-height: 100%;
-}
-
-body {
-  margin: 0;
-  font-family: var(--font-body);
-  color: var(--text);
-  background:
-    radial-gradient(1100px 700px at 20% -10%, color-mix(in oklab, var(--accent) 18%, transparent), transparent 55%),
-    radial-gradient(900px 600px at 95% 10%, color-mix(in oklab, var(--accent2) 14%, transparent), transparent 60%),
-    radial-gradient(900px 600px at 50% 120%, color-mix(in oklab, var(--link) 10%, transparent), transparent 55%),
-    linear-gradient(180deg, var(--bg0), var(--bg1));
-  overflow-x: hidden;
-}
-
-body::before,
-body::after {
-  display: none;
-}
-
-.skip-link {
-  position: absolute;
-  top: 10px;
-  left: 10px;
-  z-index: 10;
-  padding: 10px 12px;
-  border-radius: 999px;
-  background: var(--panel);
-  color: var(--text);
-  text-decoration: none;
-  transform: translateY(-130%);
-  box-shadow: var(--shadow-px);
-}
-
-.skip-link:focus {
-  transform: translateY(0);
-  outline: none;
-}
-
-.shell {
-  position: sticky;
-  top: 0;
-  z-index: 100;
-  padding: 22px 16px 10px;
-}
-
-.shell__frame {
-  max-width: 1120px;
-  margin: 0 auto;
-  border-radius: var(--radius);
-  background:
-    linear-gradient(180deg, color-mix(in oklab, var(--panel2) 88%, transparent), color-mix(in oklab, var(--panel) 92%, transparent));
-  box-shadow: var(--shadow-px);
-  border: var(--border) solid var(--frame-border);
-  overflow: hidden;
-}
-
-.shell__titlebar {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: 12px;
-  padding: 14px 14px 12px;
-  background:
-    linear-gradient(90deg, color-mix(in oklab, var(--accent) 26%, transparent), transparent 42%),
-    linear-gradient(180deg, color-mix(in oklab, var(--panel) 90%, #000 10%), color-mix(in oklab, var(--panel2) 90%, #000 10%));
-}
-
-.brand {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  min-width: 0;
-}
-
-.brand__logo {
-  flex: 0 0 auto;
-  width: 40px;
-  height: 40px;
-  image-rendering: pixelated;
-  filter: drop-shadow(0 2px 0 color-mix(in oklab, var(--frame-border) 80%, transparent));
-}
-
-.brand__text {
-  min-width: 0;
-}
-
-.brand__name {
-  font-family: var(--font-pixel);
-  letter-spacing: 0.14em;
-  font-weight: 700;
-  font-size: 18px;
-  line-height: 1.1;
-  text-shadow: 0 1px 0 color-mix(in oklab, var(--frame-border) 55%, transparent);
-}
-
-.brand__hint {
-  margin-top: 2px;
-  font-size: 12px;
-  color: var(--muted);
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
-}
-
-.titlebar__actions {
-  display: flex;
-  align-items: center;
-  gap: 10px;
-}
-
-.titlebar__cta {
-  display: inline-flex;
-  align-items: center;
-  gap: 8px;
-  padding: 8px 12px 8px 10px;
-  border-radius: 12px;
-  background:
-    linear-gradient(140deg, color-mix(in oklab, var(--accent) 10%, transparent), transparent 60%),
-    color-mix(in oklab, var(--panel) 92%, transparent);
-  border: var(--border) solid color-mix(in oklab, var(--frame-border) 80%, transparent);
-  color: var(--text);
-  text-decoration: none;
-  box-shadow:
-    0 6px 0 -3px rgba(0, 0, 0, 0.25),
-    inset 0 0 0 1px color-mix(in oklab, var(--panel2) 55%, transparent);
-}
-
-.titlebar__cta:hover {
-  border-color: color-mix(in oklab, var(--accent2) 45%, transparent);
-  box-shadow:
-    0 0 0 2px color-mix(in oklab, var(--accent2) 30%, transparent),
-    0 6px 0 -3px rgba(0, 0, 0, 0.25);
-}
-
-.titlebar__cta:active {
-  transform: translateY(1px);
-  box-shadow: 0 4px 0 -3px rgba(0, 0, 0, 0.25);
-}
-
-.titlebar__cta:focus-visible {
-  outline: 3px solid color-mix(in oklab, var(--accent2) 60%, transparent);
-  outline-offset: 2px;
-}
-
-.titlebar__cta--accent {
-  background:
-    linear-gradient(120deg, color-mix(in oklab, var(--accent) 22%, transparent), transparent 70%),
-    color-mix(in oklab, var(--panel) 88%, transparent);
-  border-color: color-mix(in oklab, var(--accent) 60%, var(--frame-border));
-}
-
-.titlebar__cta-label {
-  font-family: var(--font-pixel);
-  letter-spacing: 0.12em;
-  font-size: 12px;
-  text-transform: uppercase;
-}
-
-.titlebar__cta-meta {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  height: 20px;
-  padding: 0 8px;
-  border-radius: 999px;
-  font-size: 11px;
-  text-transform: uppercase;
-  letter-spacing: 0.08em;
-  background: var(--code-bg);
-  color: var(--code-accent);
-  border: 1px solid color-mix(in oklab, var(--code-accent) 30%, transparent);
-  box-shadow: inset 0 0 12px color-mix(in oklab, var(--code-accent) 25%, transparent);
-}
-
-.theme-toggle {
-  display: inline-flex;
-  align-items: center;
-  gap: 10px;
-  padding: 9px 10px;
-  border-radius: 12px;
-  background: color-mix(in oklab, var(--panel) 92%, transparent);
-  border: var(--border) solid var(--frame-border);
-  color: var(--text);
-  cursor: pointer;
-  box-shadow: 0 6px 0 -3px rgba(0, 0, 0, 0.25);
-  user-select: none;
-}
-
-.theme-toggle:active {
-  transform: translateY(1px);
-  box-shadow: 0 4px 0 -3px rgba(0, 0, 0, 0.25);
-}
-
-.theme-toggle__key {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 36px;
-  height: 28px;
-  border-radius: 9px;
-  background: var(--code-bg);
-  color: var(--code-accent);
-  border: 1px solid color-mix(in oklab, var(--code-accent) 30%, transparent);
-  font-weight: 700;
-  font-size: 12px;
-  letter-spacing: 0.06em;
-  text-shadow: 0 0 14px color-mix(in oklab, var(--code-accent) 55%, transparent);
-}
-
-.theme-toggle__label {
-  font-family: var(--font-pixel);
-  letter-spacing: 0.12em;
-  font-size: 12px;
-  text-transform: uppercase;
-}
-
-.theme-toggle:focus-visible {
-  outline: 3px solid color-mix(in oklab, var(--accent2) 60%, transparent);
-  outline-offset: 2px;
-}
-
-.shell__nav {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: 10px;
-  padding: 10px 14px 12px;
-  border-top: 1px solid color-mix(in oklab, var(--frame-border) 25%, transparent);
-  background: linear-gradient(180deg, transparent, color-mix(in oklab, var(--panel2) 78%, transparent));
-}
-
-.nav {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 12px;
-}
-
-.nav__link {
-  display: inline-flex;
-  align-items: center;
-  gap: 8px;
-  padding: 6px 10px;
-  border-radius: 999px;
-  text-decoration: none;
-  color: var(--text);
-  background: color-mix(in oklab, var(--panel) 85%, transparent);
-  border: 1px solid color-mix(in oklab, var(--frame-border) 20%, transparent);
-}
-
-.nav__link:hover {
-  border-color: color-mix(in oklab, var(--accent2) 45%, transparent);
-  box-shadow: 0 0 0 2px color-mix(in oklab, var(--accent2) 30%, transparent);
-}
-
-.nav__chev {
-  color: var(--accent);
-  font-weight: 700;
-}
-
-.shell__status {
-  display: inline-flex;
-  align-items: center;
-  gap: 10px;
-  color: var(--muted);
-  font-size: 12px;
-  white-space: nowrap;
-}
-
-.status__dot {
-  width: 10px;
-  height: 10px;
-  border-radius: 999px;
-  background: radial-gradient(circle at 30% 30%, var(--accent2), color-mix(in oklab, var(--accent2) 30%, #000));
-  box-shadow: 0 0 0 2px color-mix(in oklab, var(--accent2) 18%, transparent), 0 0 18px color-mix(in oklab, var(--accent2) 50%, transparent);
-}
-
-.content {
-  padding: 18px 16px 48px;
-}
-
-.terminal {
-  position: relative;
-  max-width: 1120px;
-  margin: 0 auto;
-  border-radius: var(--radius);
-  border: var(--border) solid var(--frame-border);
-  background: linear-gradient(180deg, color-mix(in oklab, var(--panel) 92%, transparent), color-mix(in oklab, var(--panel2) 86%, transparent));
-  box-shadow: var(--shadow-px);
-  padding: 18px 16px 16px;
-}
-
-.terminal__prompt {
-  display: block;
-  padding: 10px 12px;
-  border-radius: var(--radius-sm);
-  background: var(--code-bg);
-  color: var(--code-fg);
-  border: 1px solid color-mix(in oklab, var(--frame-border) 18%, transparent);
-  overflow-x: auto;
-  white-space: nowrap;
-}
-
-.prompt__user {
-  color: var(--code-accent);
-  text-shadow: 0 0 16px color-mix(in oklab, var(--code-accent) 52%, transparent);
-}
-
-.prompt__host {
-  color: color-mix(in oklab, var(--code-fg) 92%, var(--accent2));
-}
-
-.prompt__path {
-  color: color-mix(in oklab, var(--code-fg) 78%, var(--link));
-}
-
-.prompt__cmd {
-  margin-left: 8px;
-  color: color-mix(in oklab, var(--code-fg) 90%, var(--accent));
-}
-
-.terminal__summary {
-  margin: 12px 2px 0;
-  color: var(--muted);
-  font-size: 14px;
-  line-height: 1.5;
-}
-
-.terminal__meta {
-  margin: 12px 2px 0;
-  padding: 12px 12px;
-  border-radius: var(--radius-sm);
-  border: 1px dashed color-mix(in oklab, var(--frame-border) 25%, transparent);
-  background: color-mix(in oklab, var(--panel) 76%, transparent);
-  color: var(--faint);
-  font-size: 13px;
-}
-
-.terminal__meta summary {
-  cursor: pointer;
-  font-family: var(--font-pixel);
-  letter-spacing: 0.08em;
-  text-transform: uppercase;
-  color: var(--text);
-}
-
-.terminal__meta ul {
-  margin: 10px 0 0 18px;
-}
-
-.terminal__footer {
-  margin-top: 22px;
-  padding-top: 16px;
-  border-top: 1px solid color-mix(in oklab, var(--frame-border) 20%, transparent);
-  color: var(--muted);
-  font-size: 13px;
-}
-
-.footer__actions {
-  margin-top: 14px;
-  display: flex;
-  justify-content: flex-end;
-}
-
-.terminal__footer a {
-  color: var(--link);
-  text-decoration: none;
-  border-bottom: 1px dotted color-mix(in oklab, var(--link) 55%, transparent);
-}
-
-.terminal__footer a:hover {
-  color: var(--link2);
-  border-bottom-color: color-mix(in oklab, var(--link2) 75%, transparent);
-}
-
-.footer__hint {
-  margin-top: 8px;
-  color: var(--faint);
-}
-
-kbd {
-  font-family: var(--font-body);
-  font-size: 0.9em;
-  padding: 2px 6px;
-  border-radius: 8px;
-  border: 1px solid color-mix(in oklab, var(--frame-border) 18%, transparent);
-  background: color-mix(in oklab, var(--panel) 65%, transparent);
-  box-shadow: 0 6px 0 -4px rgba(0, 0, 0, 0.18);
-}
-
-@supports not (color: color-mix(in oklab, black, white)) {
-  body::before,
-  body::after {
-    opacity: 0.2;
-  }
-}
diff --git a/docs/assets/theme.js b/docs/assets/theme.js
deleted file mode 100644
index b91f21aae..000000000
--- a/docs/assets/theme.js
+++ /dev/null
@@ -1,55 +0,0 @@
-const THEME_STORAGE_KEY = "openclaw:theme";
-
-function safeGet(key) {
-  try {
-    return localStorage.getItem(key);
-  } catch {
-    return null;
-  }
-}
-
-function safeSet(key, value) {
-  try {
-    localStorage.setItem(key, value);
-  } catch {
-    // ignore
-  }
-}
-
-function preferredTheme() {
-  const stored = safeGet(THEME_STORAGE_KEY);
-  if (stored === "light" || stored === "dark") return stored;
-  return window.matchMedia?.("(prefers-color-scheme: dark)").matches ? "dark" : "light";
-}
-
-function applyTheme(theme) {
-  document.documentElement.dataset.theme = theme;
-
-  const toggle = document.querySelector("[data-theme-toggle]");
-  const label = document.querySelector("[data-theme-label]");
-
-  if (toggle instanceof HTMLButtonElement) toggle.setAttribute("aria-pressed", theme === "dark" ? "true" : "false");
-  if (label) label.textContent = theme === "dark" ? "dark" : "light";
-}
-
-function toggleTheme() {
-  const current = document.documentElement.dataset.theme === "dark" ? "dark" : "light";
-  const next = current === "dark" ? "light" : "dark";
-  safeSet(THEME_STORAGE_KEY, next);
-  applyTheme(next);
-}
-
-applyTheme(preferredTheme());
-
-document.addEventListener("click", (event) => {
-  const target = event.target;
-  const button = target instanceof Element ? target.closest("[data-theme-toggle]") : null;
-  if (button) toggleTheme();
-});
-
-document.addEventListener("keydown", (event) => {
-  if (event.key === "F2") {
-    event.preventDefault();
-    toggleTheme();
-  }
-});
diff --git a/docs/concepts/features.md b/docs/concepts/features.md
new file mode 100644
index 000000000..5eecd2153
--- /dev/null
+++ b/docs/concepts/features.md
@@ -0,0 +1,53 @@
+---
+summary: "OpenClaw capabilities across channels, routing, media, and UX."
+read_when:
+  - You want a full list of what OpenClaw supports
+title: "Features"
+---
+
+## Highlights
+
+<Columns>
+  <Card title="Channels" icon="message-square">
+    WhatsApp, Telegram, Discord, and iMessage with a single Gateway.
+  </Card>
+  <Card title="Plugins" icon="plug">
+    Add Mattermost and more with extensions.
+  </Card>
+  <Card title="Routing" icon="route">
+    Multi-agent routing with isolated sessions.
+  </Card>
+  <Card title="Media" icon="image">
+    Images, audio, and documents in and out.
+  </Card>
+  <Card title="Apps and UI" icon="monitor">
+    Web Control UI and macOS companion app.
+  </Card>
+  <Card title="Mobile nodes" icon="smartphone">
+    iOS and Android nodes with Canvas support.
+  </Card>
+</Columns>
+
+## Full list
+
+- WhatsApp integration via WhatsApp Web (Baileys)
+- Telegram bot support (grammY)
+- Discord bot support (channels.discord.js)
+- Mattermost bot support (plugin)
+- iMessage integration via local imsg CLI (macOS)
+- Agent bridge for Pi in RPC mode with tool streaming
+- Streaming and chunking for long responses
+- Multi-agent routing for isolated sessions per workspace or sender
+- Subscription auth for Anthropic and OpenAI via OAuth
+- Sessions: direct chats collapse into shared `main`; groups are isolated
+- Group chat support with mention based activation
+- Media support for images, audio, and documents
+- Optional voice note transcription hook
+- WebChat and macOS menu bar app
+- iOS node with pairing and Canvas surface
+- Android node with pairing, Canvas, chat, and camera
+
+<Note>
+Legacy Claude, Codex, Gemini, and Opencode paths have been removed. Pi is the only
+coding agent path.
+</Note>
diff --git a/docs/custom.css b/docs/custom.css
new file mode 100644
index 000000000..0c88a45f7
--- /dev/null
+++ b/docs/custom.css
@@ -0,0 +1,4 @@
+#content-area h1:first-of-type,
+.prose h1:first-of-type {
+  display: none !important;
+}
diff --git a/docs/docs.json b/docs/docs.json
index 7e6950c65..d02a0673d 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -2,28 +2,41 @@
   "$schema": "https://mintlify.com/docs.json",
   "name": "OpenClaw",
   "theme": "mint",
+  "icons": {
+    "library": "lucide"
+  },
   "logo": {
     "light": "/assets/pixel-lobster.svg",
     "dark": "/assets/pixel-lobster.svg"
   },
+  "fonts": {
+    "body": {
+      "family": "Fragment Mono"
+    },
+    "heading": {
+      "family": "DM Sans"
+    }
+  },
   "favicon": "/assets/pixel-lobster.svg",
   "colors": {
-    "primary": "#FF5A36"
+    "primary": "#FF5A36",
+    "dark": "#FF5A36",
+    "light": "#FF8A6B"
+  },
+  "navbar": {
+    "links": [
+      {
+        "label": "GitHub",
+        "href": "https://github.com/openclaw/openclaw",
+        "icon": "github"
+      },
+      {
+        "label": "Releases",
+        "href": "https://github.com/openclaw/openclaw/releases",
+        "icon": "package"
+      }
+    ]
   },
-  "topbarLinks": [
-    {
-      "name": "中文",
-      "url": "/zh-CN"
-    },
-    {
-      "name": "GitHub",
-      "url": "https://github.com/openclaw/openclaw"
-    },
-    {
-      "name": "Releases",
-      "url": "https://github.com/openclaw/openclaw/releases"
-    }
-  ],
   "redirects": [
     {
       "source": "/cron",
@@ -716,7 +729,7 @@
             "groups": [
               {
                 "group": "Overview",
-                "pages": ["index", "start/showcase", "start/lore"]
+                "pages": ["index", "concepts/features", "start/showcase", "start/lore"]
               },
               {
                 "group": "Installation",
@@ -736,12 +749,14 @@
                 "group": "Setup",
                 "pages": [
                   "start/getting-started",
+                  "start/quickstart",
                   "start/wizard",
                   "start/setup",
                   "start/onboarding",
                   "start/pairing",
                   "start/openclaw",
-                  "start/hubs"
+                  "start/hubs",
+                  "start/docs-directory"
                 ]
               },
               {
@@ -983,7 +998,12 @@
                   },
                   {
                     "group": "Networking and discovery",
-                    "pages": ["gateway/pairing", "gateway/discovery", "gateway/bonjour"]
+                    "pages": [
+                      "gateway/network-model",
+                      "gateway/pairing",
+                      "gateway/discovery",
+                      "gateway/bonjour"
+                    ]
                   }
                 ]
               },
@@ -1109,6 +1129,10 @@
                   "token-use"
                 ]
               },
+              {
+                "group": "Project",
+                "pages": ["reference/credits"]
+              },
               {
                 "group": "Release notes",
                 "pages": ["reference/RELEASING", "reference/test"]
diff --git a/docs/gateway/network-model.md b/docs/gateway/network-model.md
new file mode 100644
index 000000000..1cbd6a99b
--- /dev/null
+++ b/docs/gateway/network-model.md
@@ -0,0 +1,17 @@
+---
+summary: "How the Gateway, nodes, and canvas host connect."
+read_when:
+  - You want a concise view of the Gateway networking model
+title: "Network model"
+---
+
+Most operations flow through the Gateway (`openclaw gateway`), a single long-running
+process that owns channel connections and the WebSocket control plane.
+
+## Core rules
+
+- One Gateway per host is recommended. It is the only process allowed to own the WhatsApp Web session. For rescue bots or strict isolation, run multiple gateways with isolated profiles and ports. See [Multiple gateways](/gateway/multiple-gateways).
+- Loopback first: the Gateway WS defaults to `ws://127.0.0.1:18789`. The wizard generates a gateway token by default, even for loopback. For tailnet access, run `openclaw gateway --bind tailnet --token ...` because tokens are required for non-loopback binds.
+- Nodes connect to the Gateway WS over LAN, tailnet, or SSH as needed. The legacy TCP bridge is deprecated.
+- Canvas host is an HTTP file server on `canvasHost.port` (default `18793`) serving `/__openclaw__/canvas/` for node WebViews. See [Gateway configuration](/gateway/configuration) (`canvasHost`).
+- Remote use is typically SSH tunnel or tailnet VPN. See [Remote access](/gateway/remote) and [Discovery](/gateway/discovery).
diff --git a/docs/index.md b/docs/index.md
index 357bafaa1..8010466d0 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,5 +1,5 @@
 ---
-summary: "Top-level overview of OpenClaw, features, and purpose"
+summary: "OpenClaw is a multi-channel gateway for AI agents that runs on any OS."
 read_when:
   - Introducing OpenClaw to newcomers
 title: "OpenClaw"
@@ -7,8 +7,6 @@ title: "OpenClaw"
 
 # OpenClaw 🦞
 
-> _"EXFOLIATE! EXFOLIATE!"_ — A space lobster, probably
-
 <p align="center">
     <img
         src="/assets/openclaw-logo-text-dark.png"
@@ -24,143 +22,98 @@ title: "OpenClaw"
     />
 </p>
 
-<p align="center">
-  <strong>Any OS + WhatsApp/Telegram/Discord/iMessage gateway for AI agents (Pi).</strong><br />
-  Plugins add Mattermost and more.
-  Send a message, get an agent response — from your pocket.
-</p>
+> _"EXFOLIATE! EXFOLIATE!"_ — A space lobster, probably
 
 <p align="center">
-  <a href="https://github.com/openclaw/openclaw">GitHub</a> ·
-  <a href="https://github.com/openclaw/openclaw/releases">Releases</a> ·
-  <a href="/">Docs</a> ·
-  <a href="/start/openclaw">OpenClaw assistant setup</a>
+  <strong>Any OS gateway for AI agents across WhatsApp, Telegram, Discord, iMessage, and more.</strong><br />
+  Send a message, get an agent response from your pocket. Plugins add Mattermost and more.
 </p>
 
-OpenClaw bridges WhatsApp (via WhatsApp Web / Baileys), Telegram (Bot API / grammY), Discord (Bot API / channels.discord.js), and iMessage (imsg CLI) to coding agents like [Pi](https://github.com/badlogic/pi-mono). Plugins add Mattermost (Bot API + WebSocket) and more.
-OpenClaw also powers the OpenClaw assistant.
+<Columns>
+  <Card title="Get Started" href="/start/getting-started" icon="rocket">
+    Install OpenClaw and bring up the Gateway in minutes.
+  </Card>
+  <Card title="Run the Wizard" href="/start/wizard" icon="sparkles">
+    Guided setup with `openclaw onboard` and pairing flows.
+  </Card>
+  <Card title="Open the Control UI" href="/web/control-ui" icon="layout-dashboard">
+    Launch the browser dashboard for chat, config, and sessions.
+  </Card>
+</Columns>
 
-## Start here
+OpenClaw connects chat apps to coding agents like Pi through a single Gateway process. It powers the OpenClaw assistant and supports local or remote setups.
 
-- **New install from zero:** [Getting Started](/start/getting-started)
-- **Guided setup (recommended):** [Wizard](/start/wizard) (`openclaw onboard`)
-- **Open the dashboard (local Gateway):** http://127.0.0.1:18789/ (or http://localhost:18789/)
+## How it works
 
-If the Gateway is running on the same computer, that link opens the browser Control UI
-immediately. If it fails, start the Gateway first: `openclaw gateway`.
+```mermaid
+flowchart LR
+  A["Chat apps + plugins"] --> B["Gateway"]
+  B --> C["Pi agent"]
+  B --> D["CLI"]
+  B --> E["Web Control UI"]
+  B --> F["macOS app"]
+  B --> G["iOS and Android nodes"]
+```
 
-## Dashboard (browser Control UI)
+The Gateway is the single source of truth for sessions, routing, and channel connections.
 
-The dashboard is the browser Control UI for chat, config, nodes, sessions, and more.
-Local default: http://127.0.0.1:18789/
-Remote access: [Web surfaces](/web) and [Tailscale](/gateway/tailscale)
+## Key capabilities
+
+<Columns>
+  <Card title="Multi-channel gateway" icon="network">
+    WhatsApp, Telegram, Discord, and iMessage with a single Gateway process.
+  </Card>
+  <Card title="Plugin channels" icon="plug">
+    Add Mattermost and more with extension packages.
+  </Card>
+  <Card title="Multi-agent routing" icon="route">
+    Isolated sessions per agent, workspace, or sender.
+  </Card>
+  <Card title="Media support" icon="image">
+    Send and receive images, audio, and documents.
+  </Card>
+  <Card title="Web Control UI" icon="monitor">
+    Browser dashboard for chat, config, sessions, and nodes.
+  </Card>
+  <Card title="Mobile nodes" icon="smartphone">
+    Pair iOS and Android nodes with Canvas support.
+  </Card>
+</Columns>
+
+## Quick start
+
+<Steps>
+  <Step title="Install OpenClaw">
+    ```bash
+    npm install -g openclaw@latest
+    ```
+  </Step>
+  <Step title="Onboard and install the service">
+    ```bash
+    openclaw onboard --install-daemon
+    ```
+  </Step>
+  <Step title="Pair WhatsApp and start the Gateway">
+    ```bash
+    openclaw channels login
+    openclaw gateway --port 18789
+    ```
+  </Step>
+</Steps>
+
+Need the full install and dev setup? See [Quick start](/start/quickstart).
+
+## Dashboard
+
+Open the browser Control UI after the Gateway starts.
+
+- Local default: http://127.0.0.1:18789/
+- Remote access: [Web surfaces](/web) and [Tailscale](/gateway/tailscale)
 
 <p align="center">
   <img src="whatsapp-openclaw.jpg" alt="OpenClaw" width="420" />
 </p>
 
-## How it works
-
-```
-WhatsApp / Telegram / Discord / iMessage (+ plugins)
-        │
-        ▼
-  ┌───────────────────────────┐
-  │          Gateway          │  ws://127.0.0.1:18789 (loopback-only)
-  │     (single source)       │
-  │                           │  http://<gateway-host>:18793
-  │                           │    /__openclaw__/canvas/ (Canvas host)
-  └───────────┬───────────────┘
-              │
-              ├─ Pi agent (RPC)
-              ├─ CLI (openclaw …)
-              ├─ Chat UI (SwiftUI)
-              ├─ macOS app (OpenClaw.app)
-              ├─ iOS node via Gateway WS + pairing
-              └─ Android node via Gateway WS + pairing
-```
-
-Most operations flow through the **Gateway** (`openclaw gateway`), a single long-running process that owns channel connections and the WebSocket control plane.
-
-## Network model
-
-- **One Gateway per host (recommended)**: it is the only process allowed to own the WhatsApp Web session. If you need a rescue bot or strict isolation, run multiple gateways with isolated profiles and ports; see [Multiple gateways](/gateway/multiple-gateways).
-- **Loopback-first**: Gateway WS defaults to `ws://127.0.0.1:18789`.
-  - The wizard now generates a gateway token by default (even for loopback).
-  - For Tailnet access, run `openclaw gateway --bind tailnet --token ...` (token is required for non-loopback binds).
-- **Nodes**: connect to the Gateway WebSocket (LAN/tailnet/SSH as needed); legacy TCP bridge is deprecated/removed.
-- **Canvas host**: HTTP file server on `canvasHost.port` (default `18793`), serving `/__openclaw__/canvas/` for node WebViews; see [Gateway configuration](/gateway/configuration) (`canvasHost`).
-- **Remote use**: SSH tunnel or tailnet/VPN; see [Remote access](/gateway/remote) and [Discovery](/gateway/discovery).
-
-## Features (high level)
-
-- 📱 **WhatsApp Integration** — Uses Baileys for WhatsApp Web protocol
-- ✈️ **Telegram Bot** — DMs + groups via grammY
-- 🎮 **Discord Bot** — DMs + guild channels via channels.discord.js
-- 🧩 **Mattermost Bot (plugin)** — Bot token + WebSocket events
-- 💬 **iMessage** — Local imsg CLI integration (macOS)
-- 🤖 **Agent bridge** — Pi (RPC mode) with tool streaming
-- ⏱️ **Streaming + chunking** — Block streaming + Telegram draft streaming details ([/concepts/streaming](/concepts/streaming))
-- 🧠 **Multi-agent routing** — Route provider accounts/peers to isolated agents (workspace + per-agent sessions)
-- 🔐 **Subscription auth** — Anthropic (Claude Pro/Max) + OpenAI (ChatGPT/Codex) via OAuth
-- 💬 **Sessions** — Direct chats collapse into shared `main` (default); groups are isolated
-- 👥 **Group Chat Support** — Mention-based by default; owner can toggle `/activation always|mention`
-- 📎 **Media Support** — Send and receive images, audio, documents
-- 🎤 **Voice notes** — Optional transcription hook
-- 🖥️ **WebChat + macOS app** — Local UI + menu bar companion for ops and voice wake
-- 📱 **iOS node** — Pairs as a node and exposes a Canvas surface
-- 📱 **Android node** — Pairs as a node and exposes Canvas + Chat + Camera
-
-Note: legacy Claude/Codex/Gemini/Opencode paths have been removed; Pi is the only coding-agent path.
-
-## Quick start
-
-Runtime requirement: **Node ≥ 22**.
-
-```bash
-# Recommended: global install (npm/pnpm)
-npm install -g openclaw@latest
-# or: pnpm add -g openclaw@latest
-
-# Onboard + install the service (launchd/systemd user service)
-openclaw onboard --install-daemon
-
-# Pair WhatsApp Web (shows QR)
-openclaw channels login
-
-# Gateway runs via the service after onboarding; manual run is still possible:
-openclaw gateway --port 18789
-```
-
-Switching between npm and git installs later is easy: install the other flavor and run `openclaw doctor` to update the gateway service entrypoint.
-
-From source (development):
-
-```bash
-git clone https://github.com/openclaw/openclaw.git
-cd openclaw
-pnpm install
-pnpm ui:build # auto-installs UI deps on first run
-pnpm build
-openclaw onboard --install-daemon
-```
-
-If you don’t have a global install yet, run the onboarding step via `pnpm openclaw ...` from the repo.
-
-Multi-instance quickstart (optional):
-
-```bash
-OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
-OPENCLAW_STATE_DIR=~/.openclaw-a \
-openclaw gateway --port 19001
-```
-
-Send a test message (requires a running Gateway):
-
-```bash
-openclaw message send --target +15555550123 --message "Hello from OpenClaw"
-```
-
 ## Configuration (optional)
 
 Config lives at `~/.openclaw/openclaw.json`.
@@ -182,77 +135,45 @@ Example:
 }
 ```
 
-## Docs
+## Start here
 
-- Start here:
-  - [Docs hubs (all pages linked)](/start/hubs)
-  - [Help](/help) ← _common fixes + troubleshooting_
-  - [Configuration](/gateway/configuration)
-  - [Configuration examples](/gateway/configuration-examples)
-  - [Slash commands](/tools/slash-commands)
-  - [Multi-agent routing](/concepts/multi-agent)
-  - [Updating / rollback](/install/updating)
-  - [Pairing (DM + nodes)](/start/pairing)
-  - [Nix mode](/install/nix)
-  - [OpenClaw assistant setup](/start/openclaw)
-  - [Skills](/tools/skills)
-  - [Skills config](/tools/skills-config)
-  - [Workspace templates](/reference/templates/AGENTS)
-  - [RPC adapters](/reference/rpc)
-  - [Gateway runbook](/gateway)
-  - [Nodes (iOS/Android)](/nodes)
-  - [Web surfaces (Control UI)](/web)
-  - [Discovery + transports](/gateway/discovery)
-  - [Remote access](/gateway/remote)
-- Providers and UX:
-  - [WebChat](/web/webchat)
-  - [Control UI (browser)](/web/control-ui)
-  - [Telegram](/channels/telegram)
-  - [Discord](/channels/discord)
-  - [Mattermost (plugin)](/channels/mattermost)
-  - [BlueBubbles (iMessage)](/channels/bluebubbles)
-  - [iMessage (legacy)](/channels/imessage)
-  - [Groups](/concepts/groups)
-  - [WhatsApp group messages](/concepts/group-messages)
-  - [Media: images](/nodes/images)
-  - [Media: audio](/nodes/audio)
-- Companion apps:
-  - [macOS app](/platforms/macos)
-  - [iOS app](/platforms/ios)
-  - [Android app](/platforms/android)
-  - [Windows (WSL2)](/platforms/windows)
-  - [Linux app](/platforms/linux)
-- Ops and safety:
-  - [Sessions](/concepts/session)
-  - [Cron jobs](/automation/cron-jobs)
-  - [Webhooks](/automation/webhook)
-  - [Gmail hooks (Pub/Sub)](/automation/gmail-pubsub)
-  - [Security](/gateway/security)
-  - [Troubleshooting](/gateway/troubleshooting)
+<Columns>
+  <Card title="Docs hubs" href="/start/hubs" icon="book-open">
+    All docs and guides, organized by use case.
+  </Card>
+  <Card title="Configuration" href="/gateway/configuration" icon="settings">
+    Core Gateway settings, tokens, and provider config.
+  </Card>
+  <Card title="Remote access" href="/gateway/remote" icon="globe">
+    SSH and tailnet access patterns.
+  </Card>
+  <Card title="Channels" href="/channels/telegram" icon="message-square">
+    Channel-specific setup for WhatsApp, Telegram, Discord, and more.
+  </Card>
+  <Card title="Nodes" href="/nodes" icon="smartphone">
+    iOS and Android nodes with pairing and Canvas.
+  </Card>
+  <Card title="Help" href="/help" icon="life-buoy">
+    Common fixes and troubleshooting entry point.
+  </Card>
+</Columns>
 
-## The name
+## Learn more
 
-**OpenClaw = CLAW + TARDIS** — because every space lobster needs a time-and-space machine.
-
----
-
-_"We're all just playing with our own prompts."_ — an AI, probably high on tokens
-
-## Credits
-
-- **Peter Steinberger** ([@steipete](https://x.com/steipete)) — Creator, lobster whisperer
-- **Mario Zechner** ([@badlogicc](https://x.com/badlogicgames)) — Pi creator, security pen-tester
-- **Clawd** — The space lobster who demanded a better name
-
-## Core Contributors
-
-- **Maxim Vovshin** (@Hyaxia, 36747317+Hyaxia@users.noreply.github.com) — Blogwatcher skill
-- **Nacho Iacovino** (@nachoiacovino, nacho.iacovino@gmail.com) — Location parsing (Telegram + WhatsApp)
-
-## License
-
-MIT — Free as a lobster in the ocean 🦞
-
----
-
-_"We're all just playing with our own prompts."_ — An AI, probably high on tokens
+<Columns>
+  <Card title="Full feature list" href="/concepts/features" icon="list">
+    Complete channel, routing, and media capabilities.
+  </Card>
+  <Card title="Multi-agent routing" href="/concepts/multi-agent" icon="route">
+    Workspace isolation and per-agent sessions.
+  </Card>
+  <Card title="Security" href="/gateway/security" icon="shield">
+    Tokens, allowlists, and safety controls.
+  </Card>
+  <Card title="Troubleshooting" href="/gateway/troubleshooting" icon="wrench">
+    Gateway diagnostics and common errors.
+  </Card>
+  <Card title="About and credits" href="/reference/credits" icon="info">
+    Project origins, contributors, and license.
+  </Card>
+</Columns>
diff --git a/docs/reference/credits.md b/docs/reference/credits.md
new file mode 100644
index 000000000..e9ba9bca3
--- /dev/null
+++ b/docs/reference/credits.md
@@ -0,0 +1,27 @@
+---
+summary: "Project origin, contributors, and license."
+read_when:
+  - You want the project backstory or contributor credits
+title: "Credits"
+---
+
+## The name
+
+OpenClaw = CLAW + TARDIS, because every space lobster needs a time and space machine.
+
+## Credits
+
+- **Peter Steinberger** ([@steipete](https://x.com/steipete)) - Creator, lobster whisperer
+- **Mario Zechner** ([@badlogicc](https://x.com/badlogicgames)) - Pi creator, security pen tester
+- **Clawd** - The space lobster who demanded a better name
+
+## Core contributors
+
+- **Maxim Vovshin** (@Hyaxia, 36747317+Hyaxia@users.noreply.github.com) - Blogwatcher skill
+- **Nacho Iacovino** (@nachoiacovino, nacho.iacovino@gmail.com) - Location parsing (Telegram and WhatsApp)
+
+## License
+
+MIT - Free as a lobster in the ocean.
+
+> "We are all just playing with our own prompts." (An AI, probably high on tokens)
diff --git a/docs/start/docs-directory.md b/docs/start/docs-directory.md
new file mode 100644
index 000000000..c429a7354
--- /dev/null
+++ b/docs/start/docs-directory.md
@@ -0,0 +1,63 @@
+---
+summary: "Curated links to the most used OpenClaw docs."
+read_when:
+  - You want quick access to key docs pages
+title: "Docs directory"
+---
+
+<Note>
+For a complete map of the docs, see [Docs hubs](/start/hubs).
+</Note>
+
+## Start here
+
+- [Docs hubs (all pages linked)](/start/hubs)
+- [Help](/help)
+- [Configuration](/gateway/configuration)
+- [Configuration examples](/gateway/configuration-examples)
+- [Slash commands](/tools/slash-commands)
+- [Multi-agent routing](/concepts/multi-agent)
+- [Updating and rollback](/install/updating)
+- [Pairing (DM and nodes)](/start/pairing)
+- [Nix mode](/install/nix)
+- [OpenClaw assistant setup](/start/openclaw)
+- [Skills](/tools/skills)
+- [Skills config](/tools/skills-config)
+- [Workspace templates](/reference/templates/AGENTS)
+- [RPC adapters](/reference/rpc)
+- [Gateway runbook](/gateway)
+- [Nodes (iOS and Android)](/nodes)
+- [Web surfaces (Control UI)](/web)
+- [Discovery and transports](/gateway/discovery)
+- [Remote access](/gateway/remote)
+
+## Providers and UX
+
+- [WebChat](/web/webchat)
+- [Control UI (browser)](/web/control-ui)
+- [Telegram](/channels/telegram)
+- [Discord](/channels/discord)
+- [Mattermost (plugin)](/channels/mattermost)
+- [BlueBubbles (iMessage)](/channels/bluebubbles)
+- [iMessage (legacy)](/channels/imessage)
+- [Groups](/concepts/groups)
+- [WhatsApp group messages](/concepts/group-messages)
+- [Media images](/nodes/images)
+- [Media audio](/nodes/audio)
+
+## Companion apps
+
+- [macOS app](/platforms/macos)
+- [iOS app](/platforms/ios)
+- [Android app](/platforms/android)
+- [Windows (WSL2)](/platforms/windows)
+- [Linux app](/platforms/linux)
+
+## Operations and safety
+
+- [Sessions](/concepts/session)
+- [Cron jobs](/automation/cron-jobs)
+- [Webhooks](/automation/webhook)
+- [Gmail hooks (Pub/Sub)](/automation/gmail-pubsub)
+- [Security](/gateway/security)
+- [Troubleshooting](/gateway/troubleshooting)
diff --git a/docs/start/quickstart.md b/docs/start/quickstart.md
new file mode 100644
index 000000000..3df3de9e5
--- /dev/null
+++ b/docs/start/quickstart.md
@@ -0,0 +1,81 @@
+---
+summary: "Install OpenClaw, onboard the Gateway, and pair your first channel."
+read_when:
+  - You want the fastest path from install to a working Gateway
+title: "Quick start"
+---
+
+<Note>
+OpenClaw requires Node 22 or newer.
+</Note>
+
+## Install
+
+<Tabs>
+  <Tab title="npm">
+    ```bash
+    npm install -g openclaw@latest
+    ```
+  </Tab>
+  <Tab title="pnpm">
+    ```bash
+    pnpm add -g openclaw@latest
+    ```
+  </Tab>
+</Tabs>
+
+## Onboard and run the Gateway
+
+<Steps>
+  <Step title="Onboard and install the service">
+    ```bash
+    openclaw onboard --install-daemon
+    ```
+  </Step>
+  <Step title="Pair WhatsApp">
+    ```bash
+    openclaw channels login
+    ```
+  </Step>
+  <Step title="Start the Gateway">
+    ```bash
+    openclaw gateway --port 18789
+    ```
+  </Step>
+</Steps>
+
+After onboarding, the Gateway runs via the user service. You can still run it manually with `openclaw gateway`.
+
+<Info>
+Switching between npm and git installs later is easy. Install the other flavor and run
+`openclaw doctor` to update the gateway service entrypoint.
+</Info>
+
+## From source (development)
+
+```bash
+git clone https://github.com/openclaw/openclaw.git
+cd openclaw
+pnpm install
+pnpm ui:build # auto-installs UI deps on first run
+pnpm build
+openclaw onboard --install-daemon
+```
+
+If you do not have a global install yet, run onboarding via `pnpm openclaw ...` from the repo.
+
+## Multi instance quickstart (optional)
+
+```bash
+OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
+OPENCLAW_STATE_DIR=~/.openclaw-a \
+openclaw gateway --port 19001
+```
+
+## Send a test message
+
+Requires a running Gateway.
+
+```bash
+openclaw message send --target +15555550123 --message "Hello from OpenClaw"
+```
diff --git a/src/docs/terminal-css.test.ts b/src/docs/terminal-css.test.ts
deleted file mode 100644
index 838d387a3..000000000
--- a/src/docs/terminal-css.test.ts
+++ /dev/null
@@ -1,28 +0,0 @@
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-import { describe, expect, test } from "vitest";
-
-function readTerminalCss() {
-  // This test is intentionally simple: it guards against regressions where the
-  // docs header stops being sticky because sticky elements live inside an
-  // overflow-clipped container.
-  const path = join(process.cwd(), "docs", "assets", "terminal.css");
-  return readFileSync(path, "utf8");
-}
-
-describe("docs terminal.css", () => {
-  test("keeps the docs header sticky (shell is sticky)", () => {
-    const css = readTerminalCss();
-    expect(css).toMatch(/\.shell\s*\{[^}]*position:\s*sticky;[^}]*top:\s*0;[^}]*\}/s);
-  });
-
-  test("does not rely on making body overflow visible", () => {
-    const css = readTerminalCss();
-    expect(css).not.toMatch(/body\s*\{[^}]*overflow-x:\s*visible;[^}]*\}/s);
-  });
-
-  test("does not make the terminal frame overflow visible (can break layout)", () => {
-    const css = readTerminalCss();
-    expect(css).not.toMatch(/\.shell__frame\s*\{[^}]*overflow:\s*visible;[^}]*\}/s);
-  });
-});
