docs: fix internal doc links

docs/concepts/agent.md

@@ -13,11 +13,11 @@ CLAWDBOT uses a single agent workspace directory (`agent.workspace`) as the agen
 
 Recommended: use `clawdbot setup` to create `~/.clawdbot/clawdbot.json` if missing and initialize the workspace files.
 
-Full workspace layout + backup guide: [`docs/agent-workspace.md`](/agent-workspace)
+Full workspace layout + backup guide: [`docs/agent-workspace.md`](/concepts/agent-workspace)
 
 If `agent.sandbox` is enabled, non-main sessions can override this with
 per-session workspaces under `agent.sandbox.workspaceRoot` (see
-[`docs/configuration.md`](/configuration)).
+[`docs/configuration.md`](/gateway/configuration)).
 
 ## Bootstrap files (injected)
 
@@ -52,7 +52,7 @@ Clawdbot loads skills from three locations (workspace wins on name conflict):
 - Managed/local: `~/.clawdbot/skills`
 - Workspace: `<workspace>/skills`
 
-Skills can be gated by config/env (see `skills` in [`docs/configuration.md`](/configuration)).
+Skills can be gated by config/env (see `skills` in [`docs/configuration.md`](/gateway/configuration)).
 
 ## p-mono integration
 
@@ -91,7 +91,7 @@ message is injected before the next assistant response.
 
 When queue mode is `followup` or `collect`, inbound messages are held until the
 current turn ends, then a new agent turn starts with the queued payloads. See
-[`docs/queue.md`](/queue) for mode + debounce/cap behavior.
+[`docs/queue.md`](/concepts/queue) for mode + debounce/cap behavior.
 
 Block streaming sends completed assistant blocks as soon as they finish; disable
 via `agent.blockStreamingDefault: "off"` if you only want the final response.
@@ -109,4 +109,4 @@ At minimum, set:
 
 ---
 
-*Next: [Group Chats](/group-messages)* 🦞
+*Next: [Group Chats](/concepts/group-messages)* 🦞

docs/concepts/architecture.md

@@ -46,7 +46,7 @@ Last updated: 2026-01-05
 - **Clients (mac app / CLI / web admin)**  
   - One WS connection per client.  
   - Send requests (`health`, `status`, `send`, `agent`, `system-presence`, toggles) and subscribe to events (`tick`, `agent`, `presence`, `shutdown`).
-  - On macOS, the app can also be invoked via deep links (`clawdbot://agent?...`) which translate into the same Gateway `agent` request path (see [`docs/macos.md`](/macos)).
+  - On macOS, the app can also be invoked via deep links (`clawdbot://agent?...`) which translate into the same Gateway `agent` request path (see [`docs/macos.md`](/platforms/macos)).
 - **Agent process (Pi)**  
   - Spawned by the Gateway on demand for `agent` calls; streams events back over the same WS connection.
 - **WebChat**  

docs/concepts/groups.md

@@ -127,4 +127,4 @@ The agent system prompt includes a group intro on the first turn of a new group
 - Group replies always go back to the same `chat_id`.
 
 ## WhatsApp specifics
-See [`docs/group-messages.md`](/group-messages) for WhatsApp-only behavior (history injection, mention handling details).
+See [`docs/group-messages.md`](/concepts/group-messages) for WhatsApp-only behavior (history injection, mention handling details).

docs/concepts/model-failover.md

@@ -85,9 +85,9 @@ timeouts that exhausted profile rotation.
 
 ## Related config
 
-See [`docs/configuration.md`](/configuration) for:
+See [`docs/configuration.md`](/gateway/configuration) for:
 - `auth.profiles` / `auth.order`
 - `agent.model.primary` / `agent.model.fallbacks`
 - `agent.imageModel` routing
 
-See [`docs/models.md`](/models) for the broader model selection and fallback overview.
+See [`docs/models.md`](/concepts/models) for the broader model selection and fallback overview.

docs/concepts/models.md

@@ -7,7 +7,7 @@ read_when:
 ---
 # Models CLI plan
 
-See [`docs/model-failover.md`](/model-failover) for how auth profiles rotate (OAuth vs API keys), cooldowns, and how that interacts with model fallbacks.
+See [`docs/model-failover.md`](/concepts/model-failover) for how auth profiles rotate (OAuth vs API keys), cooldowns, and how that interacts with model fallbacks.
 
 Goal: give clear model visibility + control (configured vs available), plus scan tooling
 that prefers tool-call + image-capable models and maintains ordered fallbacks.
@@ -83,7 +83,7 @@ Output
 - Image routing uses `agent.imageModel` **only when configured** and the primary
   model lacks image input.
 - Persist last successful provider/model to session entry; auth profile success is global.
-- See [`docs/model-failover.md`](/model-failover) for auth profile rotation, cooldowns, and timeout handling.
+- See [`docs/model-failover.md`](/concepts/model-failover) for auth profile rotation, cooldowns, and timeout handling.
 
 ## Tests
 
@@ -93,5 +93,5 @@ Output
 
 ## Docs
 
-- Update [`docs/configuration.md`](/configuration) with `agent.models` + `agent.model` + `agent.imageModel`.
+- Update [`docs/configuration.md`](/gateway/configuration) with `agent.models` + `agent.model` + `agent.imageModel`.
 - Keep this doc current when CLI surface or scan logic changes.

docs/concepts/sessions.md

@@ -5,4 +5,4 @@ read_when:
 ---
 # Sessions
 
-Canonical session management docs live in [`docs/session.md`](/session).
+Canonical session management docs live in [`docs/session.md`](/concepts/session).

docs/experiments/plans/cron-add-hardening.md

@@ -43,7 +43,7 @@ Recent gateway logs show repeated `cron.add` failures with invalid parameters (m
 - [x] Fix UI CronStatus type to match gateway (`jobs` instead of `jobCount`).
 - [x] Update cron UI provider select to include Discord/Slack/Signal/iMessage.
 - [x] Update macOS CronJobEditor provider picker + enum to include Slack/Signal/iMessage.
-- [x] Document cron compatibility normalization policy in [`docs/cron-jobs.md`](/cron-jobs).
+- [x] Document cron compatibility normalization policy in [`docs/cron-jobs.md`](/automation/cron-jobs).
 
 ### Phase 2 — Input normalization + tooling hardening
 - [x] Add shared cron input normalization helpers (`normalizeCronJobCreate`/`normalizeCronJobPatch`).

docs/experiments/plans/group-policy-hardening.md

@@ -69,8 +69,8 @@ Follow-up hardening work ensures Telegram allowlists behave consistently across
 ### Phase 3: Documentation Updates
 
 **Files**:
-- [`docs/groups.md`](/groups)
+- [`docs/groups.md`](/concepts/groups)
-- [`docs/telegram.md`](/telegram)
+- [`docs/telegram.md`](/providers/telegram)
 
 **Changes**:
 - Document `tg:` alias and case-insensitive prefixes for Telegram allowlists.
@@ -90,8 +90,8 @@ Follow-up hardening work ensures Telegram allowlists behave consistently across
 |------|-------------|-------------|
 | [`src/telegram/bot.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/telegram/bot.ts) | Fix | Trim allowlist values; strip `telegram:` / `tg:` prefixes case-insensitively |
 | [`src/telegram/bot.test.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/telegram/bot.test.ts) | Test | Add DM + group allowlist coverage for `TG:` prefix + whitespace |
-| [`docs/groups.md`](/groups) | Docs | Mention `tg:` alias + case-insensitive prefixes |
+| [`docs/groups.md`](/concepts/groups) | Docs | Mention `tg:` alias + case-insensitive prefixes |
-| [`docs/telegram.md`](/telegram) | Docs | Mention `tg:` alias + case-insensitive prefixes |
+| [`docs/telegram.md`](/providers/telegram) | Docs | Mention `tg:` alias + case-insensitive prefixes |
 
 ---
 

docs/gateway/bonjour.md

@@ -155,5 +155,5 @@ Bonjour/DNS-SD often escapes bytes in service instance names as decimal `\\DDD`
 
 ## Related docs
 
-- Discovery policy and transport selection: [`docs/discovery.md`](/discovery)
+- Discovery policy and transport selection: [`docs/discovery.md`](/gateway/discovery)
 - Node pairing + approvals: [`docs/gateway/pairing.md`](/gateway/pairing)

docs/gateway/configuration.md

@@ -1488,7 +1488,7 @@ Template placeholders are expanded in `routing.transcribeAudio.command` (and any
 
 ## Cron (Gateway scheduler)
 
-Cron is a Gateway-owned scheduler for wakeups and scheduled jobs. See [Cron jobs](/cron-jobs) for the feature overview and CLI examples.
+Cron is a Gateway-owned scheduler for wakeups and scheduled jobs. See [Cron jobs](/automation/cron-jobs) for the feature overview and CLI examples.
 
 ```json5
 {
@@ -1501,4 +1501,4 @@ Cron is a Gateway-owned scheduler for wakeups and scheduled jobs. See [Cron jobs
 
 ---
 
-*Next: [Agent Runtime](/agent)* 🦞
+*Next: [Agent Runtime](/concepts/agent)* 🦞

docs/gateway/discovery.md

@@ -42,7 +42,7 @@ Target direction:
 - The **gateway** advertises its bridge via Bonjour.
 - Clients browse and show a “pick a gateway” list, then store the chosen endpoint.
 
-Troubleshooting and beacon details: [`docs/bonjour.md`](/bonjour).
+Troubleshooting and beacon details: [`docs/bonjour.md`](/gateway/bonjour).
 
 #### Current implementation
 
@@ -77,7 +77,7 @@ If the gateway can detect it is running under Tailscale, it publishes `tailnetDn
 
 When there is no direct route (or direct is disabled), clients can always connect via SSH by forwarding the loopback gateway port.
 
-See [`docs/remote.md`](/remote).
+See [`docs/remote.md`](/gateway/remote).
 
 ## Transport selection (client policy)
 

docs/gateway/heartbeat.md

@@ -96,7 +96,7 @@ bloat.
 - Handle mundane tasks (triage inboxes, summarize queues, refresh notes).
 - Nudge on open loops or reminders.
 - Background monitoring (health checks, status polling, low-priority alerts).
-- Scheduled routines (use [Cron jobs](/cron-jobs) when you
+- Scheduled routines (use [Cron jobs](/automation/cron-jobs) when you
   need exact schedules or isolated runs).
 
 ## Wake hook

docs/gateway/index.md

@@ -111,7 +111,7 @@ CLAWDBOT_CONFIG_PATH=~/.clawdbot/b.json CLAWDBOT_STATE_DIR=~/.clawdbot-b clawdbo
 - `node.invoke` — invoke a command on a node (e.g. `canvas.*`, `camera.*`).
 - `node.pair.*` — pairing lifecycle (`request`, `list`, `approve`, `reject`, `verify`).
 
-See also: [`docs/presence.md`](/presence) for how presence is produced/deduped and why `instanceId` matters.
+See also: [`docs/presence.md`](/concepts/presence) for how presence is produced/deduped and why `instanceId` matters.
 
 ## Events
 - `agent` — streamed tool/output events from the agent run (seq-tagged).

docs/gateway/remote.md

@@ -8,7 +8,7 @@ read_when:
 This repo supports “remote over SSH” by keeping a single Gateway (the master) running on a host (e.g., your Mac Studio) and connecting clients to it.
 
 - For **operators (you / the macOS app)**: SSH tunneling is the universal fallback.
-- For **nodes (iOS/Android and future devices)**: prefer the Gateway **Bridge** when on the same LAN/tailnet (see [`docs/discovery.md`](/discovery)).
+- For **nodes (iOS/Android and future devices)**: prefer the Gateway **Bridge** when on the same LAN/tailnet (see [`docs/discovery.md`](/gateway/discovery)).
 
 ## The core idea
 
@@ -58,4 +58,4 @@ WebChat no longer uses a separate HTTP port. The SwiftUI chat UI connects direct
 
 The macOS menu bar app can drive the same setup end-to-end (remote status checks, WebChat, and Voice Wake forwarding).
 
-Runbook: [`docs/mac/remote.md`](/mac/remote).
+Runbook: [`docs/mac/remote.md`](/platforms/mac/remote).

docs/gateway/security.md

@@ -50,7 +50,7 @@ clawdbot pairing list --provider <provider>
 clawdbot pairing approve --provider <provider> <code>
 ```
 
-Details + files on disk: [Pairing](/pairing)
+Details + files on disk: [Pairing](/start/pairing)
 
 ## Allowlists (DM + groups) — terminology
 
@@ -64,7 +64,7 @@ Clawdbot has two separate “who can trigger me?” layers:
     - `groupPolicy="allowlist"` + `groupAllowFrom`: restrict who can trigger the bot *inside* a group session (WhatsApp/Telegram/Signal/iMessage).
     - `discord.guilds` / `slack.channels`: per-surface allowlists + mention defaults.
 
-Details: [Configuration](/configuration) and [Groups](/groups)
+Details: [Configuration](/gateway/configuration) and [Groups](/concepts/groups)
 
 ## Prompt injection (what it is, why it matters)
 
@@ -139,8 +139,8 @@ We're considering a `readOnlyMode` flag that prevents the AI from:
 
 Two complementary approaches:
 
-- **Run the full Gateway in Docker** (container boundary): [Docker](/docker)
+- **Run the full Gateway in Docker** (container boundary): [Docker](/install/docker)
-- **Per-session tool sandbox** (`agent.sandbox`, host gateway + Docker-isolated tools): [Configuration](/configuration)
+- **Per-session tool sandbox** (`agent.sandbox`, host gateway + Docker-isolated tools): [Configuration](/gateway/configuration)
 
 Note: to prevent cross-agent access, keep `perSession: true` so each session gets
 its own container + workspace. `perSession: false` shares a single container.

docs/gateway/troubleshooting.md

@@ -254,4 +254,4 @@ Then set in config:
 }
 ```
 
-**Full guide:** See [browser-linux-troubleshooting](/browser-linux-troubleshooting)
+**Full guide:** See [browser-linux-troubleshooting](/tools/browser-linux-troubleshooting)

docs/install/nix.md

@@ -91,5 +91,5 @@ packaging and Nix builds (which do not rely on a full Xcode toolchain).
 ## Related
 
 - [nix-clawdbot](https://github.com/clawdbot/nix-clawdbot) — full setup guide
-- [Wizard](/wizard) — non-Nix CLI setup
+- [Wizard](/start/wizard) — non-Nix CLI setup
-- [Docker](/docker) — containerized setup
+- [Docker](/install/docker) — containerized setup

docs/install/updating.md

@@ -71,7 +71,7 @@ Typical things it does:
 - Detect and migrate older gateway services (launchd/systemd; legacy schtasks) to current Clawdbot services.
 - On Linux, ensure systemd user lingering (so the Gateway survives logout).
 
-Details: [Doctor](/doctor)
+Details: [Doctor](/gateway/doctor)
 
 ## Start / stop / restart the Gateway
 
@@ -134,5 +134,5 @@ git pull
 ## If you’re stuck
 
 - Run `clawdbot doctor` again and read the output carefully (it often tells you the fix).
-- Check: [Troubleshooting](/troubleshooting)
+- Check: [Troubleshooting](/gateway/troubleshooting)
 - Ask in Discord: https://discord.gg/clawd

docs/platforms/android.md

@@ -47,7 +47,7 @@ From the gateway machine:
 dns-sd -B _clawdbot-bridge._tcp local.
 ```
 
-More debugging notes: [`docs/bonjour.md`](/bonjour).
+More debugging notes: [`docs/bonjour.md`](/gateway/bonjour).
 
 #### Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD
 
@@ -56,7 +56,7 @@ Android NSD/mDNS discovery won’t cross networks. If your Android node and the
 1) Set up a DNS-SD zone (example `clawdbot.internal.`) on the gateway host and publish `_clawdbot-bridge._tcp` records.
 2) Configure Tailscale split DNS for `clawdbot.internal` pointing at that DNS server.
 
-Details and example CoreDNS config: [`docs/bonjour.md`](/bonjour).
+Details and example CoreDNS config: [`docs/bonjour.md`](/gateway/bonjour).
 
 ### 3) Connect from Android
 
@@ -130,4 +130,4 @@ Camera commands (foreground only; permission-gated):
 - `camera.snap` (jpg)
 - `camera.clip` (mp4)
 
-See [`docs/camera.md`](/camera) for parameters and CLI helpers.
+See [`docs/camera.md`](/nodes/camera) for parameters and CLI helpers.

docs/platforms/ios.md

@@ -61,7 +61,7 @@ If browse works, but the iOS node can’t connect, try resolving one instance:
 dns-sd -L "<instance name>" _clawdbot-bridge._tcp local.
 ```
 
-More debugging notes: [`docs/bonjour.md`](/bonjour).
+More debugging notes: [`docs/bonjour.md`](/gateway/bonjour).
 
 #### Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD
 
@@ -70,7 +70,7 @@ If the iOS node and the gateway are on different networks but connected via Tail
 1) Set up a DNS-SD zone (example `clawdbot.internal.`) on the gateway host and publish `_clawdbot-bridge._tcp` records.
 2) Configure Tailscale split DNS for `clawdbot.internal` pointing at that DNS server.
 
-Details and example CoreDNS config: [`docs/bonjour.md`](/bonjour).
+Details and example CoreDNS config: [`docs/bonjour.md`](/gateway/bonjour).
 
 ### 3) Connect from the iOS node app
 
@@ -169,7 +169,7 @@ The response includes `{ format, base64 }` image data (default `format="jpeg"`;
 
 - **iOS in background:** all `canvas.*` commands fail fast with `NODE_BACKGROUND_UNAVAILABLE` (bring the iOS node app to foreground).
 - **Return to default scaffold:** `canvas.navigate` with `{"url":""}` or `{"url":"/"}` returns to the built-in scaffold page.
-- **mDNS blocked:** some networks block multicast; use a different LAN or plan a tailnet-capable bridge (see [`docs/discovery.md`](/discovery)).
+- **mDNS blocked:** some networks block multicast; use a different LAN or plan a tailnet-capable bridge (see [`docs/discovery.md`](/gateway/discovery)).
 - **Wrong node selector:** `--node` can be the node id (UUID), display name (e.g. `iOS Node`), IP, or an unambiguous prefix. If it’s ambiguous, the CLI will tell you.
 - **Stale pairing / Keychain cleared:** if the pairing token is missing (or iOS Keychain was wiped), the node must pair again; approve a new pending request.
 - **App reinstall but no reconnect:** the node restores `instanceId` + last bridge preference from Keychain; if it still comes up “unpaired”, verify Keychain persistence on your device/simulator and re-pair once.
@@ -195,8 +195,8 @@ Non-goals (v1):
 
 ### Current repo reality (constraints we respect)
 - The Gateway WebSocket server binds to `127.0.0.1:18789` ([`src/gateway/server.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/server.ts)) with an optional `CLAWDBOT_GATEWAY_TOKEN`.
-- The Gateway exposes a Canvas file server (`canvasHost`) on `canvasHost.port` (default `18793`), so nodes can `canvas.navigate` to `http://<lanHost>:18793/__clawdbot__/canvas/` and auto-reload on file changes ([`docs/configuration.md`](/configuration)).
+- The Gateway exposes a Canvas file server (`canvasHost`) on `canvasHost.port` (default `18793`), so nodes can `canvas.navigate` to `http://<lanHost>:18793/__clawdbot__/canvas/` and auto-reload on file changes ([`docs/configuration.md`](/gateway/configuration)).
-- macOS “Canvas” is controlled via the Gateway node protocol (`canvas.*`), matching iOS/Android ([`docs/mac/canvas.md`](/mac/canvas)).
+- macOS “Canvas” is controlled via the Gateway node protocol (`canvas.*`), matching iOS/Android ([`docs/mac/canvas.md`](/platforms/mac/canvas)).
 - Voice wake forwards via `GatewayChannel` to Gateway `agent` (mac app: `VoiceWakeForwarder` → `GatewayConnection.sendAgent`).
 
 ### Recommended topology (B): Gateway-owned Bridge + loopback Gateway
@@ -368,5 +368,5 @@ open Clawdbot.xcodeproj
 
 - [`docs/gateway.md`](/gateway) (gateway runbook)
 - [`docs/gateway/pairing.md`](/gateway/pairing) (approval + storage)
-- [`docs/bonjour.md`](/bonjour) (discovery debugging)
+- [`docs/bonjour.md`](/gateway/bonjour) (discovery debugging)
-- [`docs/discovery.md`](/discovery) (LAN vs tailnet vs SSH)
+- [`docs/discovery.md`](/gateway/discovery) (LAN vs tailnet vs SSH)

docs/platforms/mac/canvas.md

@@ -10,7 +10,7 @@ read_when:
 
 Status: draft spec · Date: 2025-12-12
 
-Note: for iOS/Android nodes that should render agent-edited HTML/CSS/JS over the network, prefer the Gateway `canvasHost` (serves `~/clawd/canvas` over LAN/tailnet with live reload). A2UI is also **hosted by the Gateway** over HTTP. This doc focuses on the macOS in-app canvas panel. See [`docs/configuration.md`](/configuration).
+Note: for iOS/Android nodes that should render agent-edited HTML/CSS/JS over the network, prefer the Gateway `canvasHost` (serves `~/clawd/canvas` over LAN/tailnet with live reload). A2UI is also **hosted by the Gateway** over HTTP. This doc focuses on the macOS in-app canvas panel. See [`docs/configuration.md`](/gateway/configuration).
 
 Clawdbot can embed an agent-controlled “visual workspace” panel (“Canvas”) inside the macOS app using `WKWebView`, served via a **custom URL scheme** (no loopback HTTP port required).
 
@@ -81,7 +81,7 @@ Canvas is exposed via the Gateway **node bridge**, so the agent can:
 This should be modeled after `WebChatManager`/`WebChatSwiftUIWindowController` but targeting `clawdbot-canvas://…` URLs.
 
 Related:
-- For “invoke the agent again from UI” flows, prefer the macOS deep link scheme (`clawdbot://agent?...`) so *any* UI surface (Canvas, WebChat, native views) can trigger a new agent run. See [`docs/macos.md`](/macos).
+- For “invoke the agent again from UI” flows, prefer the macOS deep link scheme (`clawdbot://agent?...`) so *any* UI surface (Canvas, WebChat, native views) can trigger a new agent run. See [`docs/macos.md`](/platforms/macos).
 
 ## Agent commands (current)
 

docs/platforms/mac/health.md

@@ -25,4 +25,4 @@ How to see whether the WhatsApp Web/Baileys bridge is healthy from the menu bar
 - Cache the last good snapshot and the last error separately to avoid flicker; show the timestamp of each.
 
 ## When in doubt
-- You can still use the CLI flow in [`docs/health.md`](/health) (`clawdbot status`, `clawdbot status --deep`, `clawdbot health --json`) and tail `/tmp/clawdbot/clawdbot-*.log` for `web-heartbeat` / `web-reconnect`.
+- You can still use the CLI flow in [`docs/health.md`](/gateway/health) (`clawdbot status`, `clawdbot status --deep`, `clawdbot health --json`) and tail `/tmp/clawdbot/clawdbot-*.log` for `web-heartbeat` / `web-reconnect`.

docs/platforms/mac/signing.md

@@ -9,7 +9,7 @@ This app is usually built from [`scripts/package-mac-app.sh`](https://github.com
 
 - sets a stable debug bundle identifier: `com.clawdbot.mac.debug`
 - writes the Info.plist with that bundle id (override via `BUNDLE_ID=...`)
-- calls [`scripts/codesign-mac-app.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/codesign-mac-app.sh) to sign the main binary, bundled CLI, and app bundle so macOS treats each rebuild as the same signed bundle and keeps TCC permissions (notifications, accessibility, screen recording, mic, speech). For stable permissions, use a real signing identity; ad-hoc is opt-in and fragile (see [`docs/mac/permissions.md`](/mac/permissions)).
+- calls [`scripts/codesign-mac-app.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/codesign-mac-app.sh) to sign the main binary, bundled CLI, and app bundle so macOS treats each rebuild as the same signed bundle and keeps TCC permissions (notifications, accessibility, screen recording, mic, speech). For stable permissions, use a real signing identity; ad-hoc is opt-in and fragile (see [`docs/mac/permissions.md`](/platforms/mac/permissions)).
 - uses `CODESIGN_TIMESTAMP=auto` by default; it enables trusted timestamps for Developer ID signatures. Set `CODESIGN_TIMESTAMP=off` to skip timestamping (offline debug builds).
 - inject build metadata into Info.plist: `ClawdbotBuildTimestamp` (UTC) and `ClawdbotGitCommit` (short hash) so the About pane can show build, git, and debug/release channel.
 - **Packaging requires Bun**: The embedded gateway relay is compiled using `bun`. Ensure it is installed (`curl -fsSL https://bun.sh/install | bash`).
@@ -26,7 +26,7 @@ SIGN_IDENTITY="-" scripts/package-mac-app.sh        # explicit ad-hoc (same cave
 ```
 
 ### Ad-hoc Signing Note
-When signing with `SIGN_IDENTITY="-"` (ad-hoc), the script automatically disables the **Hardened Runtime** (`--options runtime`). This is necessary to prevent crashes when the app attempts to load embedded frameworks (like Sparkle) that do not share the same Team ID. Ad-hoc signatures also break TCC permission persistence; see [`docs/mac/permissions.md`](/mac/permissions) for recovery steps.
+When signing with `SIGN_IDENTITY="-"` (ad-hoc), the script automatically disables the **Hardened Runtime** (`--options runtime`). This is necessary to prevent crashes when the app attempts to load embedded frameworks (like Sparkle) that do not share the same Team ID. Ad-hoc signatures also break TCC permission persistence; see [`docs/mac/permissions.md`](/platforms/mac/permissions) for recovery steps.
 
 ## Build metadata for About
 

docs/platforms/mac/voice-overlay.md

@@ -3,7 +3,7 @@ summary: "Voice overlay lifecycle when wake-word and push-to-talk overlap"
 read_when:
   - Adjusting voice overlay behavior
 ---
-## Voice Overlay Lifecycle (macOS)
+# Voice Overlay Lifecycle (macOS)
 
 Audience: macOS app contributors. Goal: keep the voice overlay predictable when wake-word and push-to-talk overlap.
 

docs/platforms/mac/xpc.md

@@ -21,7 +21,7 @@ read_when:
 - UI automation uses a separate UNIX socket named `bridge.sock` and the PeekabooBridge JSON protocol.
 - Host preference order (client-side): Peekaboo.app → Claude.app → Clawdbot.app → local execution.
 - Security: bridge hosts require TeamID `Y5PE65HELJ`; DEBUG-only same-UID escape hatch is guarded by `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` (Peekaboo convention).
-- See: [`docs/mac/peekaboo.md`](/mac/peekaboo) for the Clawdbot plan and naming.
+- See: [`docs/mac/peekaboo.md`](/platforms/mac/peekaboo) for the Clawdbot plan and naming.
 
 ### Mach/XPC (future direction)
 - Still optional for internal app services, but **not required** for automation now that node.invoke is the surface.

docs/platforms/macos.md

@@ -13,7 +13,7 @@ Author: steipete · Status: draft spec · Date: 2025-12-20
   - Shows native notifications for Clawdbot/clawdbot events.
   - Owns TCC prompts (Notifications, Accessibility, Screen Recording, Automation/AppleScript, Microphone, Speech Recognition).
   - Runs (or connects to) the **Gateway** and exposes itself as a **node** so agents can reach macOS‑only features.
-  - Hosts **PeekabooBridge** for UI automation (consumed by `peekaboo`; see [`docs/mac/peekaboo.md`](/mac/peekaboo)).
+  - Hosts **PeekabooBridge** for UI automation (consumed by `peekaboo`; see [`docs/mac/peekaboo.md`](/platforms/mac/peekaboo)).
   - Installs a single CLI (`clawdbot`) by symlinking the bundled binary.
 
 ## High-level design

docs/platforms/windows.md

@@ -65,7 +65,7 @@ pnpm build
 pnpm clawdbot onboard
 ```
 
-Full guide: [Getting Started](/getting-started)
+Full guide: [Getting Started](/start/getting-started)
 
 ## Windows companion app
 

docs/providers/discord.md

@@ -30,7 +30,7 @@ Status: ready for DM and guild text channels via the official Discord bot gatewa
 8. Group DMs are ignored by default; enable via `discord.dm.groupEnabled` and optionally restrict by `discord.dm.groupChannels`.
 9. Optional guild rules: set `discord.guilds` keyed by guild id (preferred) or slug, with per-channel rules.
 10. Optional native commands: set `commands.native: true` to register native commands in Discord; set `commands.native: false` to clear previously registered native commands. Text commands are controlled by `commands.text` and must be sent as standalone `/...` messages. Use `commands.useAccessGroups: false` to bypass access-group checks for commands.
-    - Full command list + config: [Slash commands](/slash-commands)
+    - Full command list + config: [Slash commands](/tools/slash-commands)
 11. Optional guild context history: set `discord.historyLimit` (default 20) to include the last N guild messages as context when replying to a mention. Set `0` to disable.
 12. Reactions: the agent can trigger reactions via the `discord` tool (gated by `discord.actions.*`).
     - The `discord` tool is only exposed when the current provider is Discord.

docs/providers/imessage.md

@@ -43,7 +43,7 @@ DMs:
 - Approve via:
   - `clawdbot pairing list --provider imessage`
   - `clawdbot pairing approve --provider imessage <CODE>`
-- Pairing is the default token exchange for iMessage DMs. Details: [Pairing](/pairing)
+- Pairing is the default token exchange for iMessage DMs. Details: [Pairing](/start/pairing)
 
 Groups:
 - `imessage.groupPolicy = open | allowlist | disabled`.
@@ -71,7 +71,7 @@ imsg chats --limit 20
 ```
 
 ## Configuration reference (iMessage)
-Full configuration: [Configuration](/configuration)
+Full configuration: [Configuration](/gateway/configuration)
 
 Provider options:
 - `imessage.enabled`: enable/disable provider startup.

docs/providers/signal.md

@@ -46,7 +46,7 @@ DMs:
 - Approve via:
   - `clawdbot pairing list --provider signal`
   - `clawdbot pairing approve --provider signal <CODE>`
-- Pairing is the default token exchange for Signal DMs. Details: [Pairing](/pairing)
+- Pairing is the default token exchange for Signal DMs. Details: [Pairing](/start/pairing)
 
 Groups:
 - `signal.groupPolicy = open | allowlist | disabled`.
@@ -68,7 +68,7 @@ Groups:
 - Usernames: `username:<name>` (if supported by your Signal account).
 
 ## Configuration reference (Signal)
-Full configuration: [Configuration](/configuration)
+Full configuration: [Configuration](/gateway/configuration)
 
 Provider options:
 - `signal.enabled`: enable/disable provider startup.

docs/providers/slack.md

@@ -192,7 +192,7 @@ Ack reactions are controlled globally via `messages.ackReaction` +
 - Channels map to `slack:channel:<channelId>` sessions.
 - Slash commands use `slack:slash:<userId>` sessions.
 - Native command registration is controlled by `commands.native`; text commands require standalone `/...` messages and can be disabled with `commands.text: false`. Slack slash commands are managed in the Slack app and are not removed automatically. Use `commands.useAccessGroups: false` to bypass access-group checks for commands.
-- Full command list + config: [Slash commands](/slash-commands)
+- Full command list + config: [Slash commands](/tools/slash-commands)
 
 ## DM security (pairing)
 - Default: `slack.dm.policy="pairing"` — unknown DM senders get a pairing code.

docs/providers/telegram.md

@@ -43,7 +43,7 @@ Status: production-ready for bot DMs + groups via grammY. Long-polling by defaul
 - Approve via:
   - `clawdbot pairing list --provider telegram`
   - `clawdbot pairing approve --provider telegram <CODE>`
-- Pairing is the default token exchange used for Telegram DMs. Details: [Pairing](/pairing)
+- Pairing is the default token exchange used for Telegram DMs. Details: [Pairing](/start/pairing)
 
 Group gating:
 - `telegram.groupPolicy = open | allowlist | disabled`.
@@ -68,7 +68,7 @@ Controlled by `telegram.replyToMode`:
 - Example: `clawdbot send --provider telegram --to 123456789 "hi"`.
 
 ## Configuration reference (Telegram)
-Full configuration: [Configuration](/configuration)
+Full configuration: [Configuration](/gateway/configuration)
 
 Provider options:
 - `telegram.enabled`: enable/disable provider startup.

docs/providers/whatsapp.md

@@ -148,7 +148,7 @@ WhatsApp requires a real mobile number for verification. VoIP and virtual number
 ## Logs + troubleshooting
 - Subsystems: `whatsapp/inbound`, `whatsapp/outbound`, `web-heartbeat`, `web-reconnect`.
 - Log file: `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` (configurable).
-- Troubleshooting guide: [`docs/troubleshooting.md`](/troubleshooting).
+- Troubleshooting guide: [`docs/troubleshooting.md`](/gateway/troubleshooting).
 
 ## Tests
 - [`src/web/auto-reply.test.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/web/auto-reply.test.ts) (mention gating, history injection, reply flow)

docs/reference/RELEASING.md

@@ -36,9 +36,9 @@ Use `pnpm` (Node 22+) from the repo root. Keep the working tree clean before tag
 - [ ] Build + sign the macOS app, then zip it for distribution.
 - [ ] Generate the Sparkle appcast (HTML notes via [`scripts/make_appcast.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/make_appcast.sh)) and update `appcast.xml`.
 - [ ] Keep the app zip (and optional dSYM zip) ready to attach to the GitHub release.
-- [ ] Follow [`docs/mac/release.md`](/mac/release) for the exact commands and required env vars.
+- [ ] Follow [`docs/mac/release.md`](/platforms/mac/release) for the exact commands and required env vars.
   - `APP_BUILD` must be numeric + monotonic (no `-beta`) so Sparkle compares versions correctly.
-  - If notarizing, use the `clawdbot-notary` keychain profile created from App Store Connect API env vars (see [`docs/mac/release.md`](/mac/release)).
+  - If notarizing, use the `clawdbot-notary` keychain profile created from App Store Connect API env vars (see [`docs/mac/release.md`](/platforms/mac/release)).
 
 6) **Publish (npm)**
 - [ ] Confirm git status is clean; commit and push as needed.

docs/reference/rpc.md

@@ -14,7 +14,7 @@ Clawdbot integrates external CLIs via JSON-RPC. Two patterns are used today.
 - Health probe: `/api/v1/check`.
 - Clawdbot owns lifecycle when `signal.autoStart=true`.
 
-See [`docs/signal.md`](/signal) for setup and endpoints.
+See [`docs/signal.md`](/providers/signal) for setup and endpoints.
 
 ## Pattern B: stdio child process (imsg)
 - Clawdbot spawns `imsg rpc` as a child process.
@@ -27,7 +27,7 @@ Core methods used:
 - `send`
 - `chats.list` (probe/diagnostics)
 
-See [`docs/imessage.md`](/imessage) for setup and addressing (`chat_id` preferred).
+See [`docs/imessage.md`](/providers/imessage) for setup and addressing (`chat_id` preferred).
 
 ## Adapter guidelines
 - Gateway owns the process (start/stop tied to provider lifecycle).

docs/start/clawd.md

@@ -93,7 +93,7 @@ Tip: treat this folder like Clawd’s “memory” and make it a git repo (ideal
 clawdbot setup
 ```
 
-Full workspace layout + backup guide: [`docs/agent-workspace.md`](/agent-workspace)
+Full workspace layout + backup guide: [`docs/agent-workspace.md`](/concepts/agent-workspace)
 
 Optional: choose a different workspace with `agent.workspace` (supports `~`).
 
@@ -206,12 +206,12 @@ Logs live under `/tmp/clawdbot/` (default: `clawdbot-YYYY-MM-DD.log`).
 
 ## Next steps
 
-- WebChat: [WebChat](/webchat)
+- WebChat: [WebChat](/web/webchat)
 - Gateway ops: [Gateway runbook](/gateway)
-- Cron + wakeups: [Cron jobs](/cron-jobs)
+- Cron + wakeups: [Cron jobs](/automation/cron-jobs)
-- macOS menu bar companion: [Clawdbot macOS app](/macos)
+- macOS menu bar companion: [Clawdbot macOS app](/platforms/macos)
-- iOS node app: [iOS app](/ios)
+- iOS node app: [iOS app](/platforms/ios)
-- Android node app: [Android app](/android)
+- Android node app: [Android app](/platforms/android)
-- Windows status: [Windows (WSL2)](/windows)
+- Windows status: [Windows (WSL2)](/platforms/windows)
-- Linux status: [Linux app](/linux)
+- Linux status: [Linux app](/platforms/linux)
-- Security: [Security](/security)
+- Security: [Security](/gateway/security)

docs/start/getting-started.md

@@ -17,7 +17,7 @@ Recommended path: use the **CLI onboarding wizard** (`clawdbot onboard`). It set
 - workspace bootstrap + skills
 - optional background daemon
 
-If you want the deeper reference pages, jump to: [Wizard](/wizard), [Setup](/setup), [Pairing](/pairing), [Security](/security).
+If you want the deeper reference pages, jump to: [Wizard](/start/wizard), [Setup](/start/setup), [Pairing](/start/pairing), [Security](/gateway/security).
 
 ## 0) Prereqs
 
@@ -26,7 +26,7 @@ If you want the deeper reference pages, jump to: [Wizard](/wizard), [Setup](/set
 - Git
 
 macOS: if you plan to build the apps, install Xcode / CLT. For the CLI + gateway only, Node is enough.
-Windows: use **WSL2** (Ubuntu recommended). WSL2 is strongly recommended; native Windows is untested and more problematic. Install WSL2 first, then run the Linux steps inside WSL. See [Windows (WSL2)](/windows).
+Windows: use **WSL2** (Ubuntu recommended). WSL2 is strongly recommended; native Windows is untested and more problematic. Install WSL2 first, then run the Linux steps inside WSL. See [Windows (WSL2)](/platforms/windows).
 
 ## 1) Check out from source
 
@@ -67,7 +67,7 @@ What you’ll choose:
 - **Daemon**: optional background install (launchd/systemd; WSL2 uses systemd)
   - **Runtime**: Node (recommended; required for WhatsApp) or Bun (faster, but incompatible with WhatsApp)
 
-Wizard doc: [Wizard](/wizard)
+Wizard doc: [Wizard](/start/wizard)
 
 ### Auth: where it lives (important)
 
@@ -104,13 +104,13 @@ pnpm clawdbot login
 
 Scan via WhatsApp → Settings → Linked Devices.
 
-WhatsApp doc: [WhatsApp](/whatsapp)
+WhatsApp doc: [WhatsApp](/providers/whatsapp)
 
 ### Telegram / Discord / others
 
 The wizard can write tokens/config for you. If you prefer manual config, start with:
-- Telegram: [Telegram](/telegram)
+- Telegram: [Telegram](/providers/telegram)
-- Discord: [Discord](/discord)
+- Discord: [Discord](/providers/discord)
 
 ## 6) DM safety (pairing approvals)
 
@@ -123,7 +123,7 @@ pnpm clawdbot pairing list --provider telegram
 pnpm clawdbot pairing approve --provider telegram <CODE>
 ```
 
-Pairing doc: [Pairing](/pairing)
+Pairing doc: [Pairing](/start/pairing)
 
 ## 7) Verify end-to-end
 
@@ -138,6 +138,6 @@ If `health` shows “no auth configured”, go back to the wizard and set OAuth/
 
 ## Next steps (optional, but great)
 
-- macOS menu bar app + voice wake: [macOS app](/macos)
+- macOS menu bar app + voice wake: [macOS app](/platforms/macos)
 - iOS/Android nodes (Canvas/camera/voice): [Nodes](/nodes)
-- Remote access (SSH tunnel / Tailscale Serve): [Remote access](/remote) and [Tailscale](/tailscale)
+- Remote access (SSH tunnel / Tailscale Serve): [Remote access](/gateway/remote) and [Tailscale](/gateway/tailscale)

docs/start/pairing.md

@@ -14,13 +14,13 @@ It is used in two places:
 1) **DM pairing** (who is allowed to talk to the bot)
 2) **Node pairing** (which devices/nodes are allowed to join the gateway network)
 
-Security context: [Security](/security)
+Security context: [Security](/gateway/security)
 
 ## 1) DM pairing (inbound chat access)
 
 When a provider is configured with DM policy `pairing`, unknown senders get a short code and their message is **not processed** until you approve.
 
-Default DM policies are documented in: [Security](/security)
+Default DM policies are documented in: [Security](/gateway/security)
 
 ### Approve a sender
 
@@ -74,12 +74,12 @@ Full protocol + design notes: [Gateway pairing](/gateway/pairing)
 
 ## Related docs
 
-- Security model + prompt injection: [Security](/security)
+- Security model + prompt injection: [Security](/gateway/security)
-- Updating safely (run doctor): [Updating](/updating)
+- Updating safely (run doctor): [Updating](/install/updating)
 - Provider configs:
-  - Telegram: [Telegram](/telegram)
+  - Telegram: [Telegram](/providers/telegram)
-  - WhatsApp: [WhatsApp](/whatsapp)
+  - WhatsApp: [WhatsApp](/providers/whatsapp)
-  - Signal: [Signal](/signal)
+  - Signal: [Signal](/providers/signal)
-  - iMessage: [iMessage](/imessage)
+  - iMessage: [iMessage](/providers/imessage)
-  - Discord: [Discord](/discord)
+  - Discord: [Discord](/providers/discord)
-  - Slack: [Slack](/slack)
+  - Slack: [Slack](/providers/slack)

docs/start/setup.md

@@ -17,7 +17,7 @@ Last updated: 2026-01-01
 ## Prereqs (from source)
 - Node `>=22`
 - `pnpm`
-- Docker (optional; only for containerized setup/e2e — see [`docs/docker.md`](/docker))
+- Docker (optional; only for containerized setup/e2e — see [`docs/docker.md`](/install/docker))
 
 ## Tailoring strategy (so updates don’t hurt)
 
@@ -126,7 +126,7 @@ user service (no lingering needed). See [`docs/gateway.md`](/gateway) for the sy
 ## Related docs
 
 - [`docs/gateway.md`](/gateway) (Gateway runbook; flags, supervision, ports)
-- [`docs/configuration.md`](/configuration) (config schema + examples)
+- [`docs/configuration.md`](/gateway/configuration) (config schema + examples)
-- [`docs/discord.md`](/discord) and [`docs/telegram.md`](/telegram) (reply tags + replyToMode settings)
+- [`docs/discord.md`](/providers/discord) and [`docs/telegram.md`](/providers/telegram) (reply tags + replyToMode settings)
-- [`docs/clawd.md`](/clawd) (personal assistant setup)
+- [`docs/clawd.md`](/start/clawd) (personal assistant setup)
-- [`docs/macos.md`](/macos) (macOS app behavior; gateway lifecycle + “Attach only”)
+- [`docs/macos.md`](/platforms/macos) (macOS app behavior; gateway lifecycle + “Attach only”)

docs/start/wizard.md

@@ -60,7 +60,7 @@ It does **not** install or change anything on the remote host.
 3) **Workspace**
    - Default `~/clawd` (configurable).
    - Seeds the workspace files needed for the agent bootstrap ritual.
-   - Full workspace layout + backup guide: [`docs/agent-workspace.md`](/agent-workspace)
+   - Full workspace layout + backup guide: [`docs/agent-workspace.md`](/concepts/agent-workspace)
 
 4) **Gateway**
    - Port, bind, auth mode, tailscale exposure.
@@ -164,7 +164,7 @@ Sessions are stored under `~/.clawdbot/agents/<agentId>/sessions/`.
 
 ## Related docs
 
-- macOS app onboarding: [`docs/onboarding.md`](/onboarding)
+- macOS app onboarding: [`docs/onboarding.md`](/start/onboarding)
-- Config reference: [`docs/configuration.md`](/configuration)
+- Config reference: [`docs/configuration.md`](/gateway/configuration)
-- Providers: [`docs/whatsapp.md`](/whatsapp), [`docs/telegram.md`](/telegram), [`docs/discord.md`](/discord), [`docs/signal.md`](/signal), [`docs/imessage.md`](/imessage)
+- Providers: [`docs/whatsapp.md`](/providers/whatsapp), [`docs/telegram.md`](/providers/telegram), [`docs/discord.md`](/providers/discord), [`docs/signal.md`](/providers/signal), [`docs/imessage.md`](/providers/imessage)
-- Skills: [`docs/skills.md`](/skills), [`docs/skills-config.md`](/skills-config)
+- Skills: [`docs/skills.md`](/tools/skills), [`docs/skills-config.md`](/tools/skills-config)

docs/tools/browser.md

@@ -306,4 +306,4 @@ Notes:
 
 ## Troubleshooting
 
-For Linux-specific issues (especially Ubuntu with snap Chromium), see [browser-linux-troubleshooting](/browser-linux-troubleshooting).
+For Linux-specific issues (especially Ubuntu with snap Chromium), see [browser-linux-troubleshooting](/tools/browser-linux-troubleshooting).

docs/tools/skills.md

@@ -142,10 +142,10 @@ copy). Workspace skills are user-owned and override both on name conflicts.
 
 ## Config reference
 
-See [`docs/skills-config.md`](/skills-config) for the full configuration schema.
+See [`docs/skills-config.md`](/tools/skills-config) for the full configuration schema.
 
 ## Looking for more skills?
 
-Browse [ClawdHub](/clawdhub).
+Browse [ClawdHub](/tools/clawdhub).
 
 ---

docs/tools/thinking.md

@@ -35,7 +35,7 @@ read_when:
 - When verbose is on, agents that emit structured tool results (Pi, other JSON agents) send each tool result back as its own metadata-only message, prefixed with `<emoji> <tool-name>: <arg>` when available (path/command); the tool output itself is not forwarded. These tool summaries are sent as soon as each tool finishes (separate bubbles), not as streaming deltas. If you toggle `/verbose on|off` while a run is in-flight, subsequent tool bubbles honor the new setting.
 
 ## Related
-- Elevated mode docs live in [`docs/elevated.md`](/elevated).
+- Elevated mode docs live in [`docs/elevated.md`](/tools/elevated).
 
 ## Heartbeats
 - Heartbeat probe body is the configured heartbeat prompt (default: `Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`). Inline directives in a heartbeat message apply as usual (but avoid changing session defaults from heartbeats).

docs/web/webchat.md

@@ -24,7 +24,7 @@ Status: the macOS/iOS SwiftUI chat UI talks directly to the Gateway WebSocket.
 - You do not need to run a separate WebChat server.
 
 ## Configuration reference (WebChat)
-Full configuration: [Configuration](/configuration)
+Full configuration: [Configuration](/gateway/configuration)
 
 Provider options:
 - No dedicated `webchat.*` block. WebChat uses the gateway endpoint + auth settings below.

package.json

@@ -47,6 +47,7 @@
     "dev": "tsx src/entry.ts",
     "postinstall": "node scripts/postinstall.js",
     "docs:list": "tsx scripts/docs-list.ts",
+    "docs:bin": "bun build scripts/docs-list.ts --compile --outfile bin/docs-list",
     "docs:dev": "cd docs && mint dev",
     "docs:build": "cd docs && pnpm dlx mint broken-links",
     "build": "tsc -p tsconfig.json && tsx scripts/canvas-a2ui-copy.ts",