docs: reorganize documentation structure

docs/_config.yml

@@ -23,29 +23,29 @@ nav:
   - title: "Home"
     url: "/"
   - title: "Clawd Setup"
-    url: "/clawd.html"
+    url: "/start/clawd/"
   - title: "Gateway"
-    url: "/gateway.html"
+    url: "/gateway/"
   - title: "Remote"
-    url: "/remote.html"
+    url: "/gateway/remote/"
   - title: "Discovery"
-    url: "/discovery.html"
+    url: "/gateway/discovery/"
   - title: "Configuration"
-    url: "/configuration.html"
+    url: "/gateway/configuration/"
   - title: "WebChat"
-    url: "/webchat.html"
+    url: "/web/webchat/"
   - title: "macOS App"
-    url: "/macos.html"
+    url: "/platforms/macos/"
   - title: "iOS App"
-    url: "/ios.html"
+    url: "/platforms/ios/"
   - title: "Android App"
-    url: "/android.html"
+    url: "/platforms/android/"
   - title: "Telegram"
-    url: "/telegram.html"
+    url: "/providers/telegram/"
   - title: "Security"
-    url: "/security.html"
+    url: "/gateway/security/"
   - title: "Troubleshooting"
-    url: "/troubleshooting.html"
+    url: "/gateway/troubleshooting/"
 
 kramdown:
   input: GFM

docs/automation/gmail-pubsub.md

@@ -13,7 +13,7 @@ Goal: Gmail watch -> Pub/Sub push -> `gog gmail watch serve` -> Clawdbot webhook
 
 - `gcloud` installed and logged in ([install guide](https://docs.cloud.google.com/sdk/docs/install-sdk)).
 - `gog` (gogcli) installed and authorized for the Gmail account ([gogcli.sh](https://gogcli.sh/)).
-- Clawdbot hooks enabled (see [`docs/webhook.md`](/webhook)).
+- Clawdbot hooks enabled (see [`docs/webhook.md`](https://docs.clawd.bot/automation/webhook)).
 - `tailscale` logged in ([tailscale.com](https://tailscale.com/)). Supported setup uses Tailscale Funnel for the public HTTPS endpoint.
   Other tunnel services can work, but are DIY/unsupported and require manual wiring.
   Right now, Tailscale is what we support.
@@ -32,7 +32,7 @@ Example hook config (enable Gmail preset mapping):
 ```
 
 To customize payload handling, add `hooks.mappings` or a JS/TS transform module
-under `hooks.transformsDir` (see [`docs/webhook.md`](/webhook)).
+under `hooks.transformsDir` (see [`docs/webhook.md`](https://docs.clawd.bot/automation/webhook)).
 
 ## Wizard (recommended)
 

docs/automation/webhook.md

@@ -93,6 +93,7 @@ Mapping options (summary):
 - Use `match.source` to keep a generic ingest endpoint (payload-driven routing).
 - TS transforms require a TS loader (e.g. `bun`) or precompiled `.js` at runtime.
 - `clawdbot hooks gmail setup` writes `hooks.gmail` config for `clawdbot hooks gmail run`.
+See [`docs/gmail-pubsub.md`](https://docs.clawd.bot/automation/gmail-pubsub) for the full Gmail watch flow.
 
 ## Responses
 

docs/docs.json

@@ -36,6 +36,478 @@
     {
       "source": "/model/",
       "destination": "/models"
+    },
+    {
+      "source": "/AGENTS.default",
+      "destination": "/reference/AGENTS.default"
+    },
+    {
+      "source": "/RELEASING",
+      "destination": "/reference/RELEASING"
+    },
+    {
+      "source": "/agent",
+      "destination": "/concepts/agent"
+    },
+    {
+      "source": "/agent-loop",
+      "destination": "/concepts/agent-loop"
+    },
+    {
+      "source": "/agent-send",
+      "destination": "/tools/agent-send"
+    },
+    {
+      "source": "/agent-workspace",
+      "destination": "/concepts/agent-workspace"
+    },
+    {
+      "source": "/android",
+      "destination": "/platforms/android"
+    },
+    {
+      "source": "/architecture",
+      "destination": "/concepts/architecture"
+    },
+    {
+      "source": "/audio",
+      "destination": "/nodes/audio"
+    },
+    {
+      "source": "/background-process",
+      "destination": "/gateway/background-process"
+    },
+    {
+      "source": "/bash",
+      "destination": "/tools/bash"
+    },
+    {
+      "source": "/bonjour",
+      "destination": "/gateway/bonjour"
+    },
+    {
+      "source": "/browser",
+      "destination": "/tools/browser"
+    },
+    {
+      "source": "/browser-linux-troubleshooting",
+      "destination": "/tools/browser-linux-troubleshooting"
+    },
+    {
+      "source": "/bun",
+      "destination": "/install/bun"
+    },
+    {
+      "source": "/camera",
+      "destination": "/nodes/camera"
+    },
+    {
+      "source": "/clawd",
+      "destination": "/start/clawd"
+    },
+    {
+      "source": "/clawdhub",
+      "destination": "/tools/clawdhub"
+    },
+    {
+      "source": "/configuration",
+      "destination": "/gateway/configuration"
+    },
+    {
+      "source": "/control-ui",
+      "destination": "/web/control-ui"
+    },
+    {
+      "source": "/cron-jobs",
+      "destination": "/automation/cron-jobs"
+    },
+    {
+      "source": "/dashboard",
+      "destination": "/web/dashboard"
+    },
+    {
+      "source": "/device-models",
+      "destination": "/reference/device-models"
+    },
+    {
+      "source": "/discord",
+      "destination": "/providers/discord"
+    },
+    {
+      "source": "/discovery",
+      "destination": "/gateway/discovery"
+    },
+    {
+      "source": "/docker",
+      "destination": "/install/docker"
+    },
+    {
+      "source": "/doctor",
+      "destination": "/gateway/doctor"
+    },
+    {
+      "source": "/elevated",
+      "destination": "/tools/elevated"
+    },
+    {
+      "source": "/faq",
+      "destination": "/start/faq"
+    },
+    {
+      "source": "/gateway-lock",
+      "destination": "/gateway/gateway-lock"
+    },
+    {
+      "source": "/getting-started",
+      "destination": "/start/getting-started"
+    },
+    {
+      "source": "/gmail-pubsub",
+      "destination": "/automation/gmail-pubsub"
+    },
+    {
+      "source": "/grammy",
+      "destination": "/providers/grammy"
+    },
+    {
+      "source": "/group-messages",
+      "destination": "/concepts/group-messages"
+    },
+    {
+      "source": "/groups",
+      "destination": "/concepts/groups"
+    },
+    {
+      "source": "/health",
+      "destination": "/gateway/health"
+    },
+    {
+      "source": "/heartbeat",
+      "destination": "/gateway/heartbeat"
+    },
+    {
+      "source": "/hubs",
+      "destination": "/start/hubs"
+    },
+    {
+      "source": "/images",
+      "destination": "/nodes/images"
+    },
+    {
+      "source": "/imessage",
+      "destination": "/providers/imessage"
+    },
+    {
+      "source": "/ios",
+      "destination": "/platforms/ios"
+    },
+    {
+      "source": "/linux",
+      "destination": "/platforms/linux"
+    },
+    {
+      "source": "/location",
+      "destination": "/providers/location"
+    },
+    {
+      "source": "/location-command",
+      "destination": "/nodes/location-command"
+    },
+    {
+      "source": "/logging",
+      "destination": "/gateway/logging"
+    },
+    {
+      "source": "/lore",
+      "destination": "/start/lore"
+    },
+    {
+      "source": "/mac/bun",
+      "destination": "/platforms/mac/bun"
+    },
+    {
+      "source": "/mac/canvas",
+      "destination": "/platforms/mac/canvas"
+    },
+    {
+      "source": "/mac/child-process",
+      "destination": "/platforms/mac/child-process"
+    },
+    {
+      "source": "/mac/dev-setup",
+      "destination": "/platforms/mac/dev-setup"
+    },
+    {
+      "source": "/mac/health",
+      "destination": "/platforms/mac/health"
+    },
+    {
+      "source": "/mac/icon",
+      "destination": "/platforms/mac/icon"
+    },
+    {
+      "source": "/mac/logging",
+      "destination": "/platforms/mac/logging"
+    },
+    {
+      "source": "/mac/menu-bar",
+      "destination": "/platforms/mac/menu-bar"
+    },
+    {
+      "source": "/mac/peekaboo",
+      "destination": "/platforms/mac/peekaboo"
+    },
+    {
+      "source": "/mac/permissions",
+      "destination": "/platforms/mac/permissions"
+    },
+    {
+      "source": "/mac/release",
+      "destination": "/platforms/mac/release"
+    },
+    {
+      "source": "/mac/remote",
+      "destination": "/platforms/mac/remote"
+    },
+    {
+      "source": "/mac/signing",
+      "destination": "/platforms/mac/signing"
+    },
+    {
+      "source": "/mac/skills",
+      "destination": "/platforms/mac/skills"
+    },
+    {
+      "source": "/mac/voice-overlay",
+      "destination": "/platforms/mac/voice-overlay"
+    },
+    {
+      "source": "/mac/voicewake",
+      "destination": "/platforms/mac/voicewake"
+    },
+    {
+      "source": "/mac/webchat",
+      "destination": "/platforms/mac/webchat"
+    },
+    {
+      "source": "/mac/xpc",
+      "destination": "/platforms/mac/xpc"
+    },
+    {
+      "source": "/macos",
+      "destination": "/platforms/macos"
+    },
+    {
+      "source": "/model-failover",
+      "destination": "/concepts/model-failover"
+    },
+    {
+      "source": "/models",
+      "destination": "/concepts/models"
+    },
+    {
+      "source": "/multi-agent",
+      "destination": "/concepts/multi-agent"
+    },
+    {
+      "source": "/nix",
+      "destination": "/install/nix"
+    },
+    {
+      "source": "/onboarding",
+      "destination": "/start/onboarding"
+    },
+    {
+      "source": "/onboarding-config-protocol",
+      "destination": "/experiments/onboarding-config-protocol"
+    },
+    {
+      "source": "/pairing",
+      "destination": "/start/pairing"
+    },
+    {
+      "source": "/plans/cron-add-hardening",
+      "destination": "/experiments/plans/cron-add-hardening"
+    },
+    {
+      "source": "/plans/group-policy-hardening",
+      "destination": "/experiments/plans/group-policy-hardening"
+    },
+    {
+      "source": "/poll",
+      "destination": "/automation/poll"
+    },
+    {
+      "source": "/presence",
+      "destination": "/concepts/presence"
+    },
+    {
+      "source": "/proposals/model-config",
+      "destination": "/experiments/proposals/model-config"
+    },
+    {
+      "source": "/provider-routing",
+      "destination": "/concepts/provider-routing"
+    },
+    {
+      "source": "/queue",
+      "destination": "/concepts/queue"
+    },
+    {
+      "source": "/remote",
+      "destination": "/gateway/remote"
+    },
+    {
+      "source": "/remote-gateway-readme",
+      "destination": "/gateway/remote-gateway-readme"
+    },
+    {
+      "source": "/research/memory",
+      "destination": "/experiments/research/memory"
+    },
+    {
+      "source": "/rpc",
+      "destination": "/reference/rpc"
+    },
+    {
+      "source": "/security",
+      "destination": "/gateway/security"
+    },
+    {
+      "source": "/session",
+      "destination": "/concepts/session"
+    },
+    {
+      "source": "/session-tool",
+      "destination": "/concepts/session-tool"
+    },
+    {
+      "source": "/sessions",
+      "destination": "/concepts/sessions"
+    },
+    {
+      "source": "/setup",
+      "destination": "/start/setup"
+    },
+    {
+      "source": "/showcase",
+      "destination": "/start/showcase"
+    },
+    {
+      "source": "/signal",
+      "destination": "/providers/signal"
+    },
+    {
+      "source": "/skills",
+      "destination": "/tools/skills"
+    },
+    {
+      "source": "/skills-config",
+      "destination": "/tools/skills-config"
+    },
+    {
+      "source": "/slack",
+      "destination": "/providers/slack"
+    },
+    {
+      "source": "/slash-commands",
+      "destination": "/tools/slash-commands"
+    },
+    {
+      "source": "/subagents",
+      "destination": "/tools/subagents"
+    },
+    {
+      "source": "/tailscale",
+      "destination": "/gateway/tailscale"
+    },
+    {
+      "source": "/talk",
+      "destination": "/nodes/talk"
+    },
+    {
+      "source": "/telegram",
+      "destination": "/providers/telegram"
+    },
+    {
+      "source": "/templates/AGENTS",
+      "destination": "/reference/templates/AGENTS"
+    },
+    {
+      "source": "/templates/BOOTSTRAP",
+      "destination": "/reference/templates/BOOTSTRAP"
+    },
+    {
+      "source": "/templates/HEARTBEAT",
+      "destination": "/reference/templates/HEARTBEAT"
+    },
+    {
+      "source": "/templates/IDENTITY",
+      "destination": "/reference/templates/IDENTITY"
+    },
+    {
+      "source": "/templates/SOUL",
+      "destination": "/reference/templates/SOUL"
+    },
+    {
+      "source": "/templates/TOOLS",
+      "destination": "/reference/templates/TOOLS"
+    },
+    {
+      "source": "/templates/USER",
+      "destination": "/reference/templates/USER"
+    },
+    {
+      "source": "/test",
+      "destination": "/reference/test"
+    },
+    {
+      "source": "/thinking",
+      "destination": "/tools/thinking"
+    },
+    {
+      "source": "/timezone",
+      "destination": "/concepts/timezone"
+    },
+    {
+      "source": "/troubleshooting",
+      "destination": "/gateway/troubleshooting"
+    },
+    {
+      "source": "/tui",
+      "destination": "/web/tui"
+    },
+    {
+      "source": "/typebox",
+      "destination": "/concepts/typebox"
+    },
+    {
+      "source": "/updating",
+      "destination": "/install/updating"
+    },
+    {
+      "source": "/voicewake",
+      "destination": "/nodes/voicewake"
+    },
+    {
+      "source": "/webchat",
+      "destination": "/web/webchat"
+    },
+    {
+      "source": "/webhook",
+      "destination": "/automation/webhook"
+    },
+    {
+      "source": "/whatsapp",
+      "destination": "/providers/whatsapp"
+    },
+    {
+      "source": "/windows",
+      "destination": "/platforms/windows"
+    },
+    {
+      "source": "/wizard",
+      "destination": "/start/wizard"
     }
   ],
   "navigation": {
@@ -43,73 +515,185 @@
       {
         "group": "Start Here",
         "pages": [
-          "getting-started",
-          "wizard",
           "index",
-          "setup",
-          "pairing",
-          "faq",
-          "clawd",
-          "showcase",
-          "hubs",
-          "onboarding"
+          "start/getting-started",
+          "start/wizard",
+          "start/setup",
+          "start/pairing",
+          "start/faq",
+          "start/clawd",
+          "start/showcase",
+          "start/hubs",
+          "start/onboarding",
+          "start/lore"
         ]
       },
       {
-        "group": "Install Options",
+        "group": "Install & Updates",
         "pages": [
-          "nix",
-          "docker"
+          "install/updating",
+          "install/nix",
+          "install/docker",
+          "install/bun"
         ]
       },
       {
         "group": "Core Concepts",
         "pages": [
-          "architecture",
-          "agent",
-          "session",
-          "rpc",
-          "queue",
-          "tools"
+          "concepts/architecture",
+          "concepts/agent",
+          "concepts/agent-loop",
+          "concepts/agent-workspace",
+          "concepts/multi-agent",
+          "concepts/session",
+          "concepts/sessions",
+          "concepts/session-tool",
+          "concepts/presence",
+          "concepts/provider-routing",
+          "concepts/groups",
+          "concepts/group-messages",
+          "concepts/queue",
+          "concepts/models",
+          "concepts/model-failover",
+          "concepts/timezone",
+          "concepts/typebox"
         ]
       },
       {
-        "group": "Gateway & Providers",
+        "group": "Gateway & Ops",
         "pages": [
           "gateway",
           "gateway/pairing",
-          "whatsapp",
-          "telegram",
-          "discord",
-          "imessage",
-          "webhook",
-          "gmail-pubsub"
+          "gateway/gateway-lock",
+          "gateway/configuration",
+          "gateway/background-process",
+          "gateway/health",
+          "gateway/heartbeat",
+          "gateway/doctor",
+          "gateway/logging",
+          "gateway/security",
+          "gateway/troubleshooting",
+          "gateway/remote",
+          "gateway/remote-gateway-readme",
+          "gateway/discovery",
+          "gateway/bonjour",
+          "gateway/tailscale"
+        ]
+      },
+      {
+        "group": "Web & Interfaces",
+        "pages": [
+          "web",
+          "web/control-ui",
+          "web/dashboard",
+          "web/webchat",
+          "web/tui"
+        ]
+      },
+      {
+        "group": "Providers",
+        "pages": [
+          "providers/whatsapp",
+          "providers/telegram",
+          "providers/grammy",
+          "providers/discord",
+          "providers/slack",
+          "providers/signal",
+          "providers/imessage",
+          "providers/location"
+        ]
+      },
+      {
+        "group": "Automation & Hooks",
+        "pages": [
+          "automation/webhook",
+          "automation/gmail-pubsub",
+          "automation/cron-jobs",
+          "automation/poll"
+        ]
+      },
+      {
+        "group": "Tools & Skills",
+        "pages": [
+          "tools",
+          "tools/bash",
+          "tools/elevated",
+          "tools/browser",
+          "tools/browser-linux-troubleshooting",
+          "tools/slash-commands",
+          "tools/thinking",
+          "tools/agent-send",
+          "tools/subagents",
+          "tools/skills",
+          "tools/skills-config",
+          "tools/clawdhub"
+        ]
+      },
+      {
+        "group": "Nodes & Media",
+        "pages": [
+          "nodes",
+          "nodes/camera",
+          "nodes/images",
+          "nodes/audio",
+          "nodes/location-command",
+          "nodes/voicewake",
+          "nodes/talk"
         ]
       },
       {
         "group": "Platforms",
         "pages": [
-          "mac/dev-setup",
-          "mac/menu-bar",
-          "mac/voicewake",
-          "macos",
-          "ios",
-          "android",
-          "webchat",
-          "web"
+          "platforms/macos",
+          "platforms/mac/dev-setup",
+          "platforms/mac/menu-bar",
+          "platforms/mac/voicewake",
+          "platforms/mac/voice-overlay",
+          "platforms/mac/webchat",
+          "platforms/mac/canvas",
+          "platforms/mac/child-process",
+          "platforms/mac/health",
+          "platforms/mac/icon",
+          "platforms/mac/logging",
+          "platforms/mac/permissions",
+          "platforms/mac/remote",
+          "platforms/mac/signing",
+          "platforms/mac/release",
+          "platforms/mac/bun",
+          "platforms/mac/xpc",
+          "platforms/mac/skills",
+          "platforms/mac/peekaboo",
+          "platforms/ios",
+          "platforms/android",
+          "platforms/windows",
+          "platforms/linux"
         ]
       },
       {
-        "group": "Operations",
+        "group": "Reference & Templates",
         "pages": [
-          "doctor",
-          "troubleshooting",
-          "logging",
-          "security",
-          "health",
-          "background-process",
-          "gateway-lock",
-          "remote"
+          "reference/rpc",
+          "reference/device-models",
+          "reference/test",
+          "reference/RELEASING",
+          "reference/AGENTS.default",
+          "reference/templates/AGENTS",
+          "reference/templates/BOOTSTRAP",
+          "reference/templates/HEARTBEAT",
+          "reference/templates/IDENTITY",
+          "reference/templates/SOUL",
+          "reference/templates/TOOLS",
+          "reference/templates/USER"
+        ]
+      },
+      {
+        "group": "Experiments & Proposals",
+        "pages": [
+          "experiments/onboarding-config-protocol",
+          "experiments/plans/cron-add-hardening",
+          "experiments/plans/group-policy-hardening",
+          "experiments/proposals/model-config",
+          "experiments/research/memory"
         ]
       }
     ]

docs/hubs.md

@@ -1,152 +0,0 @@
----
-summary: "Hubs that link to every Clawdbot doc"
-read_when:
-  - You want a complete map of the documentation
----
-# Docs hubs
-
-Use these hubs to discover every page, including deep dives and reference docs that don’t appear in the left nav.
-
-## Start here
-
-- [Index](/)
-- [Getting Started](/getting-started)
-- [Onboarding](/onboarding)
-- [Wizard](/wizard)
-- [Setup](/setup)
-- [FAQ](/faq)
-- [Configuration](/configuration)
-- [Clawd (personal assistant)](/clawd)
-- [Lore](/lore)
-
-## Installation + distribution
-
-- [Docker](/docker)
-- [Nix](/nix)
-
-## Core concepts
-
-- [Architecture](/architecture)
-- [Agent runtime](/agent)
-- [Agent workspace](/agent-workspace)
-- [Agent loop](/agent-loop)
-- [Multi-agent routing](/multi-agent)
-- [Sessions](/session)
-- [Sessions (alias)](/sessions)
-- [Session tools](/session-tool)
-- [Queue](/queue)
-- [Slash commands](/slash-commands)
-- [RPC adapters](/rpc)
-- [TypeBox schemas](/typebox)
-- [Presence](/presence)
-- [Discovery + transports](/discovery)
-- [Bonjour](/bonjour)
-- [Provider routing](/provider-routing)
-- [Groups](/groups)
-- [Group messages](/group-messages)
-
-## Providers + ingress
-
-- [WhatsApp](/whatsapp)
-- [Telegram](/telegram)
-- [Telegram (grammY notes)](/grammy)
-- [Slack](/slack)
-- [Discord](/discord)
-- [Signal](/signal)
-- [iMessage](/imessage)
-- [WebChat](/webchat)
-- [Webhooks](/webhook)
-- [Gmail Pub/Sub](/gmail-pubsub)
-
-## Gateway + operations
-
-- [Gateway runbook](/gateway)
-- [Gateway pairing](/gateway/pairing)
-- [Gateway lock](/gateway-lock)
-- [Background process](/background-process)
-- [Health](/health)
-- [Heartbeat](/heartbeat)
-- [Doctor](/doctor)
-- [Logging](/logging)
-- [Dashboard](/dashboard)
-- [Control UI](/control-ui)
-- [Remote access](/remote)
-- [Remote gateway README](/remote-gateway-readme)
-- [Tailscale](/tailscale)
-- [Security](/security)
-- [Troubleshooting](/troubleshooting)
-
-## Tools + automation
-
-- [Tools surface](/tools)
-- [Bash tool](/bash)
-- [Elevated mode](/elevated)
-- [Cron jobs](/cron-jobs)
-- [Thinking + verbose](/thinking)
-- [Models](/models)
-- [Agent send CLI](/agent-send)
-- [Terminal UI](/tui)
-- [Browser control](/browser)
-- [Browser (Linux troubleshooting)](/browser-linux-troubleshooting)
-
-## Nodes, media, voice
-
-- [Nodes overview](/nodes)
-- [Camera](/camera)
-- [Images](/images)
-- [Audio](/audio)
-- [Location command](/location-command)
-- [Voice wake](/voicewake)
-- [Talk mode](/talk)
-
-## Platforms
-
-- [macOS app overview](/macos)
-- [macOS dev setup](/mac/dev-setup)
-- [macOS menu bar](/mac/menu-bar)
-- [macOS voice wake](/mac/voicewake)
-- [macOS voice overlay](/mac/voice-overlay)
-- [macOS WebChat](/mac/webchat)
-- [macOS Canvas](/mac/canvas)
-- [macOS child process](/mac/child-process)
-- [macOS health](/mac/health)
-- [macOS icon](/mac/icon)
-- [macOS logging](/mac/logging)
-- [macOS permissions](/mac/permissions)
-- [macOS remote](/mac/remote)
-- [macOS signing](/mac/signing)
-- [macOS release](/mac/release)
-- [macOS bun gateway](/mac/bun)
-- [macOS XPC](/mac/xpc)
-- [macOS skills](/mac/skills)
-- [macOS Peekaboo plan](/mac/peekaboo)
-- [iOS node](/ios)
-- [Android node](/android)
-- [Windows app](/windows)
-- [Linux app](/linux)
-- [Web surfaces](/web)
-
-## Workspace + templates
-
-- [Skills](/skills)
-- [ClawdHub](/clawdhub)
-- [Skills config](/skills-config)
-- [Default AGENTS](/AGENTS.default)
-- [Templates: AGENTS](/templates/AGENTS)
-- [Templates: BOOTSTRAP](/templates/BOOTSTRAP)
-- [Templates: IDENTITY](/templates/IDENTITY)
-- [Templates: SOUL](/templates/SOUL)
-- [Templates: TOOLS](/templates/TOOLS)
-- [Templates: USER](/templates/USER)
-
-## Experiments + proposals
-
-- [Onboarding config protocol](/onboarding-config-protocol)
-- [Research: memory](/research/memory)
-- [Proposal: model config](/proposals/model-config)
-
-## Testing + release
-
-- [Testing](/test)
-- [Release checklist](/RELEASING)
-- [Device models](/device-models)

docs/index.md

@@ -19,8 +19,8 @@ read_when:
 <p align="center">
   <a href="https://github.com/clawdbot/clawdbot">GitHub</a> ·
   <a href="https://github.com/clawdbot/clawdbot/releases">Releases</a> ·
-  <a href="/">Docs</a> ·
-  <a href="/clawd">Clawd setup</a>
+  <a href="https://docs.clawd.bot">Docs</a> ·
+  <a href="https://docs.clawd.bot/start/clawd">Clawd setup</a>
 </p>
 
 CLAWDBOT bridges WhatsApp (via WhatsApp Web / Baileys), Telegram (Bot API / grammY), Discord (Bot API / discord.js), and iMessage (imsg CLI) to coding agents like [Pi](https://github.com/badlogic/pi-mono).
@@ -28,8 +28,18 @@ It’s built for [Clawd](https://clawd.me), a space lobster who needed a TARDIS.
 
 ## Start here
 
-- **New install from zero:** [Getting started](/getting-started)
-- **Guided setup (recommended):** [Wizard](/wizard) (`clawdbot onboard`)
+- **New install from zero:** https://docs.clawd.bot/start/getting-started
+- **Guided setup (recommended):** https://docs.clawd.bot/start/wizard (`clawdbot onboard`)
+- **Open the dashboard (local Gateway):** http://127.0.0.1:18789/ (or http://localhost:18789/)
+
+If the Gateway is running on the same computer, that link opens the browser Control UI
+immediately. If it fails, start the Gateway first: `clawdbot gateway`.
+
+## Dashboard (browser Control UI)
+
+The dashboard is the browser Control UI for chat, config, nodes, sessions, and more.
+Local default: http://127.0.0.1:18789/
+Remote access: https://docs.clawd.bot/web and https://docs.clawd.bot/gateway/tailscale
 
 ## How it works
 
@@ -60,8 +70,8 @@ Most operations flow through the **Gateway** (`clawdbot gateway`), a single long
 - **Loopback-first**: Gateway WS defaults to `ws://127.0.0.1:18789`.
   - For Tailnet access, run `clawdbot gateway --bind tailnet --token ...` (token is required for non-loopback binds).
 - **Bridge for nodes**: optional LAN/tailnet-facing bridge on `tcp://0.0.0.0:18790` for paired nodes (Bonjour-discoverable).
-- **Canvas host**: HTTP file server on `canvasHost.port` (default `18793`), serving `/__clawdbot__/canvas/` for node WebViews; see [`docs/configuration.md`](/configuration) (`canvasHost`).
-- **Remote use**: SSH tunnel or tailnet/VPN; see [`docs/remote.md`](/remote) and [`docs/discovery.md`](/discovery).
+- **Canvas host**: HTTP file server on `canvasHost.port` (default `18793`), serving `/__clawdbot__/canvas/` for node WebViews; see [`docs/configuration.md`](https://docs.clawd.bot/gateway/configuration) (`canvasHost`).
+- **Remote use**: SSH tunnel or tailnet/VPN; see [`docs/remote.md`](https://docs.clawd.bot/gateway/remote) and [`docs/discovery.md`](https://docs.clawd.bot/gateway/discovery).
 
 ## Features (high level)
 
@@ -135,45 +145,47 @@ Example:
 ## Docs
 
 - Start here:
-  - [Docs hubs (all pages linked)](/hubs)
-  - [FAQ](/faq) ← *common questions answered*
-  - [Configuration](/configuration)
-  - [Slash commands](/slash-commands)
-  - [Multi-agent routing](/multi-agent)
-  - [Updating / rollback](/updating)
-  - [Pairing (DM + nodes)](/pairing)
-  - [Nix mode](/nix)
-  - [Clawd personal assistant setup](/clawd)
-  - [Skills](/skills)
-  - [Skills config](/skills-config)
-  - [Workspace templates](/templates/AGENTS)
-  - [RPC adapters](/rpc)
-  - [Gateway runbook](/gateway)
-  - [Nodes (iOS/Android)](/nodes)
-  - [Web surfaces (Control UI)](/web)
-  - [Discovery + transports](/discovery)
-  - [Remote access](/remote)
+  - [Docs hubs (all pages linked)](https://docs.clawd.bot/start/hubs)
+  - [FAQ](https://docs.clawd.bot/start/faq) ← *common questions answered*
+  - [Configuration](https://docs.clawd.bot/gateway/configuration)
+  - [Slash commands](https://docs.clawd.bot/tools/slash-commands)
+  - [Multi-agent routing](https://docs.clawd.bot/concepts/multi-agent)
+  - [Updating / rollback](https://docs.clawd.bot/install/updating)
+  - [Pairing (DM + nodes)](https://docs.clawd.bot/start/pairing)
+  - [Nix mode](https://docs.clawd.bot/install/nix)
+  - [Clawd personal assistant setup](https://docs.clawd.bot/start/clawd)
+  - [Skills](https://docs.clawd.bot/tools/skills)
+  - [Skills config](https://docs.clawd.bot/tools/skills-config)
+  - [Workspace templates](https://docs.clawd.bot/reference/templates/AGENTS)
+  - [RPC adapters](https://docs.clawd.bot/reference/rpc)
+  - [Gateway runbook](https://docs.clawd.bot/gateway)
+  - [Nodes (iOS/Android)](https://docs.clawd.bot/nodes)
+  - [Web surfaces (Control UI)](https://docs.clawd.bot/web)
+  - [Discovery + transports](https://docs.clawd.bot/gateway/discovery)
+  - [Remote access](https://docs.clawd.bot/gateway/remote)
 - Providers and UX:
-  - [WebChat](/webchat)
-  - [Control UI (browser)](/control-ui)
-  - [Telegram](/telegram)
-  - [Discord](/discord)
-  - [iMessage](/imessage)
-  - [Groups](/groups)
-  - [WhatsApp group messages](/group-messages)
-  - [Media: images](/images)
-  - [Media: audio](/audio)
+  - [WebChat](https://docs.clawd.bot/web/webchat)
+  - [Control UI (browser)](https://docs.clawd.bot/web/control-ui)
+  - [Telegram](https://docs.clawd.bot/providers/telegram)
+  - [Discord](https://docs.clawd.bot/providers/discord)
+  - [iMessage](https://docs.clawd.bot/providers/imessage)
+  - [Groups](https://docs.clawd.bot/concepts/groups)
+  - [WhatsApp group messages](https://docs.clawd.bot/concepts/group-messages)
+  - [Media: images](https://docs.clawd.bot/nodes/images)
+  - [Media: audio](https://docs.clawd.bot/nodes/audio)
 - Companion apps:
-  - [macOS app](/macos)
-  - [iOS app](/ios)
-  - [Android app](/android)
-  - [Windows app](/windows)
-  - [Linux app](/linux)
+  - [macOS app](https://docs.clawd.bot/platforms/macos)
+  - [iOS app](https://docs.clawd.bot/platforms/ios)
+  - [Android app](https://docs.clawd.bot/platforms/android)
+  - [Windows app](https://docs.clawd.bot/platforms/windows)
+  - [Linux app](https://docs.clawd.bot/platforms/linux)
 - Ops and safety:
-  - [Sessions](/session)
-  - [Cron jobs](/cron-jobs)
-  - [Security](/security)
-  - [Troubleshooting](/troubleshooting)
+  - [Sessions](https://docs.clawd.bot/concepts/session)
+  - [Cron jobs](https://docs.clawd.bot/automation/cron-jobs)
+  - [Webhooks](https://docs.clawd.bot/automation/webhook)
+  - [Gmail hooks (Pub/Sub)](https://docs.clawd.bot/automation/gmail-pubsub)
+  - [Security](https://docs.clawd.bot/gateway/security)
+  - [Troubleshooting](https://docs.clawd.bot/gateway/troubleshooting)
 
 ## The name
 

docs/reference/AGENTS.default.md

@@ -19,15 +19,15 @@ mkdir -p ~/clawd
 2) Copy the default workspace templates into the workspace:
 
 ```bash
-cp docs/templates/AGENTS.md ~/clawd/AGENTS.md
-cp docs/templates/SOUL.md ~/clawd/SOUL.md
-cp docs/templates/TOOLS.md ~/clawd/TOOLS.md
+cp docs/reference/templates/AGENTS.md ~/clawd/AGENTS.md
+cp docs/reference/templates/SOUL.md ~/clawd/SOUL.md
+cp docs/reference/templates/TOOLS.md ~/clawd/TOOLS.md
 ```
 
 3) Optional: if you want the personal assistant skill roster, replace AGENTS.md with this file:
 
 ```bash
-cp docs/AGENTS.default.md ~/clawd/AGENTS.md
+cp docs/reference/AGENTS.default.md ~/clawd/AGENTS.md
 ```
 
 4) Optional: choose a different workspace by setting `agent.workspace` (supports `~`):