docs: add Nix installation guide and navigation

- Expand docs/nix.md from runtime-only to full installation guide
- Reference nix-clawdbot as the recommended Nix setup path
- Add "Installation" section to docs.json navigation (wizard, nix, docker, setup)
- Add Nix link to README quick links

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

README.md

@@ -20,7 +20,7 @@ It answers you on the surfaces you already use (WhatsApp, Telegram, Discord, iMe
 
 If you want a personal, single-user assistant that feels local, fast, and always-on, this is it.
 
-Website: https://clawd.me · Docs: [`docs/index.md`](docs/index.md) · FAQ: [`docs/faq.md`](docs/faq.md) · Wizard: [`docs/wizard.md`](docs/wizard.md) · Docker (optional): [`docs/docker.md`](docs/docker.md) · Discord: https://discord.gg/clawd
+Website: https://clawd.me · Docs: [`docs/index.md`](docs/index.md) · FAQ: [`docs/faq.md`](docs/faq.md) · Wizard: [`docs/wizard.md`](docs/wizard.md) · Nix: [nix-clawdbot](https://github.com/clawdbot/nix-clawdbot) · Docker: [`docs/docker.md`](docs/docker.md) · Discord: https://discord.gg/clawd
 
 Preferred setup: run the onboarding wizard (`clawdbot onboard`). It walks through gateway, workspace, providers, and skills. The CLI wizard is the recommended path and works on **macOS, Windows, and Linux**.
 

docs/docs.json

@@ -27,11 +27,19 @@
         "pages": [
           "index",
           "onboarding",
-          "wizard",
           "clawd",
           "faq"
         ]
       },
+      {
+        "group": "Installation",
+        "pages": [
+          "wizard",
+          "nix",
+          "docker",
+          "setup"
+        ]
+      },
       {
         "group": "Core Concepts",
         "pages": [

docs/nix.md

@@ -1,26 +1,64 @@
 ---
-summary: "Running Clawdbot under Nix (config, state, and packaging expectations)"
+summary: "Install Clawdbot declaratively with Nix"
 read_when:
-  - Building Clawdbot with Nix
+  - You want reproducible, rollback-able installs
-  - Debugging Nix-mode behavior
+  - You're already using Nix/NixOS/Home Manager
+  - You want everything pinned and managed declaratively
 ---
-# Nix mode
+
+# Nix Installation
+
+The recommended way to run Clawdbot with Nix is via **[nix-clawdbot](https://github.com/clawdbot/nix-clawdbot)** — a batteries-included Home Manager module.
+
+## Quick Start
+
+Paste this to your AI agent (Claude, Cursor, etc.):
+
+```text
+I want to set up nix-clawdbot on my Mac.
+Repository: github:clawdbot/nix-clawdbot
+
+What I need you to do:
+1. Check if Determinate Nix is installed (if not, install it)
+2. Create a local flake at ~/code/clawdbot-local using templates/agent-first/flake.nix
+3. Help me create a Telegram bot (@BotFather) and get my chat ID (@userinfobot)
+4. Set up secrets (bot token, Anthropic key) - plain files at ~/.secrets/ is fine
+5. Fill in the template placeholders and run home-manager switch
+6. Verify: launchd running, bot responds to messages
+
+Reference the nix-clawdbot README for module options.
+```
+
+Or see the full guide: **[github.com/clawdbot/nix-clawdbot](https://github.com/clawdbot/nix-clawdbot)**
+
+## What you get
+
+- Gateway + macOS app + tools (whisper, spotify, cameras) — all pinned
+- Launchd service that survives reboots
+- Plugin system with declarative config
+- Instant rollback: `home-manager switch --rollback`
+
+---
+
+## Nix Mode Runtime Behavior
+
+When `CLAWDBOT_NIX_MODE=1` is set (automatic with nix-clawdbot):
 
 Clawdbot supports a **Nix mode** that makes configuration deterministic and disables auto-install flows.
 Enable it by exporting:
 
-```
+```bash
 CLAWDBOT_NIX_MODE=1
 ```
 
 On macOS, the GUI app does not automatically inherit shell env vars. You can
 also enable Nix mode via defaults:
 
-```
+```bash
 defaults write com.clawdbot.mac clawdbot.nixMode -bool true
 ```
 
-## Config + state paths
+### Config + state paths
 
 Clawdbot reads JSON5 config from `CLAWDBOT_CONFIG_PATH` and stores mutable data in `CLAWDBOT_STATE_DIR`.
 
@@ -30,11 +68,11 @@ Clawdbot reads JSON5 config from `CLAWDBOT_CONFIG_PATH` and stores mutable data
 When running under Nix, set these explicitly to Nix-managed locations so runtime state and config
 stay out of the immutable store.
 
-## Runtime behavior in Nix mode
+### Runtime behavior in Nix mode
 
-- Auto-install and self-mutation flows should be disabled.
+- Auto-install and self-mutation flows are disabled
-- Missing dependencies should surface Nix-specific remediation messages.
+- Missing dependencies surface Nix-specific remediation messages
-- UI surfaces a read-only Nix mode banner when present.
+- UI surfaces a read-only Nix mode banner when present
 
 ## Packaging note (macOS)
 
@@ -47,3 +85,9 @@ apps/macos/Sources/Clawdbot/Resources/Info.plist
 `scripts/package-mac-app.sh` copies this template into the app bundle and patches dynamic fields
 (bundle ID, version/build, Git SHA, Sparkle keys). This keeps the plist deterministic for SwiftPM
 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.md) — non-Nix CLI setup
+- [Docker](./docker.md) — containerized setup