diff --git a/docs/agent.md b/docs/agent.md
index f477ca257..632994ebf 100644
--- a/docs/agent.md
+++ b/docs/agent.md
@@ -99,4 +99,4 @@ At minimum, set:
 
 ---
 
-*Next: [Group Chats](./group-messages.md)* 🦞
+*Next: [Group Chats](group-messages)* 🦞
diff --git a/docs/clawd.md b/docs/clawd.md
index 044c89536..835f143f5 100644
--- a/docs/clawd.md
+++ b/docs/clawd.md
@@ -81,7 +81,7 @@ clawdbot gateway --port 18789
 
 Now message the assistant number from your allowlisted phone.
 
-## Give the agent a workspace (AGENTS.md)
+## Give the agent a workspace (AGENTS)
 
 Clawd reads operating instructions and “memory” from its workspace directory.
 
@@ -191,12 +191,12 @@ Logs live under `/tmp/clawdbot/` (default: `clawdbot-YYYY-MM-DD.log`).
 
 ## Next steps
 
-- WebChat: [WebChat](./webchat.md)
-- Gateway ops: [Gateway runbook](./gateway.md)
-- Cron + wakeups: [Cron + wakeups](./cron.md)
-- macOS menu bar companion: [Clawdbot macOS app](./macos.md)
-- iOS node app: [iOS app](./ios.md)
-- Android node app: [Android app](./android.md)
-- Windows status: [Windows app](./windows.md)
-- Linux status: [Linux app](./linux.md)
-- Security: [Security](./security.md)
+- WebChat: [WebChat](webchat)
+- Gateway ops: [Gateway runbook](gateway)
+- Cron + wakeups: [Cron + wakeups](cron)
+- macOS menu bar companion: [Clawdbot macOS app](macos)
+- iOS node app: [iOS app](ios)
+- Android node app: [Android app](android)
+- Windows status: [Windows app](windows)
+- Linux status: [Linux app](linux)
+- Security: [Security](security)
diff --git a/docs/configuration.md b/docs/configuration.md
index 5c184dec2..1f1f8976b 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1356,7 +1356,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 + wakeups](./cron.md) for the full RFC and CLI examples.
+Cron is a Gateway-owned scheduler for wakeups and scheduled jobs. See [Cron + wakeups](cron) for the full RFC and CLI examples.
 
 ```json5
 {
@@ -1369,4 +1369,4 @@ Cron is a Gateway-owned scheduler for wakeups and scheduled jobs. See [Cron + wa
 
 ---
 
-*Next: [Agent Runtime](./agent.md)* 🦞
+*Next: [Agent Runtime](agent)* 🦞
diff --git a/docs/faq.md b/docs/faq.md
index f51fe824d..957c78888 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -3,7 +3,7 @@ summary: "Frequently asked questions about Clawdbot setup, configuration, and us
 ---
 # FAQ 🦞
 
-Common questions from the community. For detailed configuration, see [configuration.md](./configuration.md).
+Common questions from the community. For detailed configuration, see [configuration.md](configuration).
 
 ## Installation & Setup
 
@@ -290,7 +290,7 @@ Per-group activation can be changed by the owner:
 - `/activation mention` — respond only when mentioned (default)
 - `/activation always` — respond to all messages
 
-See [groups.md](./groups.md) for details.
+See [groups.md](groups) for details.
 
 ---
 
@@ -327,7 +327,7 @@ cat ~/.clawdbot/clawdbot.json | grep workspace
 - **Telegram** — Via Bot API (grammY).
 - **Discord** — Bot integration.
 - **iMessage** — Via `imsg` CLI (macOS only).
-- **Signal** — Via `signal-cli` (see [signal.md](./signal.md)).
+- **Signal** — Via `signal-cli` (see [signal.md](signal)).
 - **WebChat** — Browser-based chat UI.
 
 ### Discord: Bot works in channels but not DMs?
diff --git a/docs/index.md b/docs/index.md
index 88a2a33da..94d8310f0 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -128,41 +128,41 @@ Example:
 ## Docs
 
 - Start here:
-  - [Docs hubs (all pages linked)](./hubs.md)
-  - [FAQ](./faq.md) ← *common questions answered*
-  - [Configuration](./configuration.md)
-  - [Nix mode](./nix.md)
-  - [Clawd personal assistant setup](./clawd.md)
-  - [Skills](./skills.md)
-  - [Skills config](./skills-config.md)
-  - [Workspace templates](./templates/AGENTS.md)
-  - [RPC adapters](./rpc.md)
-  - [Gateway runbook](./gateway.md)
-  - [Nodes (iOS/Android)](./nodes.md)
-  - [Web surfaces (Control UI)](./web.md)
-  - [Discovery + transports](./discovery.md)
-  - [Remote access](./remote.md)
+  - [Docs hubs (all pages linked)](hubs)
+  - [FAQ](faq) ← *common questions answered*
+  - [Configuration](configuration)
+  - [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)
 - Providers and UX:
-  - [WebChat](./webchat.md)
-  - [Control UI (browser)](./control-ui.md)
-  - [Telegram](./telegram.md)
-  - [Discord](./discord.md)
-  - [iMessage](./imessage.md)
-  - [Groups](./groups.md)
-  - [WhatsApp group messages](./group-messages.md)
-  - [Media: images](./images.md)
-  - [Media: audio](./audio.md)
+  - [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)
 - Companion apps:
-  - [macOS app](./macos.md)
-  - [iOS app](./ios.md)
-  - [Android app](./android.md)
-  - [Windows app](./windows.md)
-  - [Linux app](./linux.md)
+  - [macOS app](macos)
+  - [iOS app](ios)
+  - [Android app](android)
+  - [Windows app](windows)
+  - [Linux app](linux)
 - Ops and safety:
-  - [Sessions](./session.md)
-  - [Cron + wakeups](./cron.md)
-  - [Security](./security.md)
-  - [Troubleshooting](./troubleshooting.md)
+  - [Sessions](session)
+  - [Cron + wakeups](cron)
+  - [Security](security)
+  - [Troubleshooting](troubleshooting)
 
 ## The name