Document interactive Claude handoff on setup failure

installation.mdx

@@ -15,7 +15,7 @@
     - macOS 12 (Monterey) or later
     - Intel or Apple Silicon (M1/M2/M3/M4)
     - 4 GB RAM minimum, 8 GB recommended
     - 4 GB free disk space (container image + node_modules)
   </Tab>
 
   <Tab title="Linux">
@@ -23,7 +23,7 @@
     - x86_64 or aarch64
     - 2 GB RAM minimum, 4 GB recommended
     - 4 GB free disk space
     - systemd (for the user service)
   </Tab>
 
   <Tab title="Windows (WSL2)">
@@ -45,16 +45,16 @@
 
 | Dependency | Scope | Installer handles it? |
 |---|---|---|
 | Node 22 | Host (orchestrator) | Yes — via nvm if missing |
 | pnpm 10 | Host (package manager) | Yes — via `corepack enable` |
 | Docker (or Apple Container) | Host (container runtime) | Partial — prompts you to install or start it if absent |
 | Build tools (gcc, python3) | Host (for `better-sqlite3` native compile) | No — install beforehand |
 | OneCLI Agent Vault | Host (credential injection) | Yes — installs locally or reuses an existing configured instance |
 | Bun 1.3.12 | Container (agent-runner runtime) | Yes — baked into the agent container image |
 
 ### Build tools
 
 `better-sqlite3` is the only host dependency that needs native compilation. Install the platform toolchain before running `nanoclaw.sh`:
 
 <Tabs>
   <Tab title="macOS">
@@ -65,16 +65,16 @@
 
   <Tab title="Linux">
     ```bash
     sudo apt-get update
     sudo apt-get install -y build-essential python3
     ```
   </Tab>
 
   <Tab title="Windows (WSL2)">
     Same as Linux, inside your WSL terminal:
     ```bash
     sudo apt-get update
     sudo apt-get install -y build-essential python3
     ```
   </Tab>
 </Tabs>
@@ -131,6 +131,8 @@
 | `NANOCLAW_AGENT_NAME` | Set the messaging-channel agent name; the CLI scratch agent remains `Terminal Agent` |
 | `SECRET_NAME` | OneCLI secret name for `setup/register-claude-token.sh` (default: `Anthropic`) |
 | `HOST_PATTERN` | OneCLI host pattern for `setup/register-claude-token.sh` (default: `api.anthropic.com`) |
+| `NANOCLAW_SETUP_ASSIST_MODE` | Set to `1` (or pass `--assist-mode`) to use the legacy non-interactive Claude assist on failure instead of the default interactive handoff |
+| `NANOCLAW_SKIP_CLAUDE_ASSIST` | Set to `1` to skip the Claude handoff/assist offer entirely when a step fails |
 
 If OneCLI is already installed and configured, setup asks whether to reuse it. For custom Anthropic-compatible model endpoints, set `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` in `.env`.
 
@@ -200,18 +202,18 @@
 |------|---------|
 | `~/.config/nanoclaw/mount-allowlist.json` | Which host directories agents can mount |
 | `~/.config/nanoclaw/sender-allowlist.json` | Optional per-channel sender access control |
 | `~/Library/LaunchAgents/com.nanoclaw-v2-<slug>.plist` (macOS) | launchd service definition |
 | `~/.config/systemd/user/nanoclaw-v2-<slug>.service` (Linux) | systemd user-service definition |
 
 ## Container image contents
 
 The agent container image is scoped per checkout, with a name like `nanoclaw-agent-v2-<slug>:latest`. It is built from `container/Dockerfile`:
 
 - **Base**: `node:22-slim`
 - **tini** as PID 1 — reaps Chromium zombies, forwards signals so `outbound.db` writes finalize on SIGTERM
 - **Bun 1.3.12** runs the agent-runner TypeScript directly (no `tsc` build step)
 - **Chromium** for browser automation via `agent-browser`
 - **Global Node CLIs (pnpm)**: `@anthropic-ai/claude-code`, `agent-browser`, `vercel`
 - **Non-root `node` user**, `/workspace/group` as working directory
 - **Source is never baked in** — `/app/src` is a read-only bind mount from the host, so code changes take effect without rebuilding
 
@@ -226,7 +228,7 @@
     ```bash
     # Start / stop
     # Replace <label> with com.nanoclaw-v2-<slug>
     launchctl load ~/Library/LaunchAgents/<label>.plist
     launchctl unload ~/Library/LaunchAgents/<label>.plist
 
     # Restart
@@ -261,7 +263,7 @@
   </Tab>
 
   <Tab title="WSL (without systemd)">
     If WSL doesn't have systemd enabled, the installer drops a wrapper script:
 
     ```bash
     bash start-nanoclaw.sh
@@ -318,7 +320,7 @@
 
 ### WSL: Docker integration
 
 If `docker` commands aren't found in WSL, enable WSL integration in Docker Desktop (Settings → Resources → WSL Integration → toggle your distro). Restart WSL from PowerShell if needed:
 
 ```powershell
 wsl --shutdown

quickstart.mdx

@@ -40,7 +40,9 @@
     - Pairing your first channel (Telegram, Discord, WhatsApp, Signal, Teams, Slack, iMessage, or the local CLI)
     - Installing a systemd or launchd service so NanoClaw starts with your machine
 
-    If any step fails, Claude Code is invoked automatically to diagnose and resume from where it broke. You don't have to debug the installer yourself.
+    If any step fails, the installer offers to hand off to an interactive Claude session preloaded with the failure context, the relevant source files, and the raw step log. You debug with full terminal access and type `/exit` (or press Ctrl-D) when you're ready to resume setup.
+
+    Set `NANOCLAW_SETUP_ASSIST_MODE=1` (or pass `--assist-mode`) to use the legacy non-interactive assist that proposes a single fix command instead. Set `NANOCLAW_SKIP_CLAUDE_ASSIST=1` to disable the handoff entirely.
   </Step>
 
   <Step title="Answer the setup prompts">
@@ -93,7 +95,7 @@
 
 <AccordionGroup>
   <Accordion title="Phase 1 — bootstrap (bash)">
     - Installs Node 22 via nvm, corepack-enables pnpm
     - Runs `pnpm install --frozen-lockfile`
     - Verifies `better-sqlite3` loads on your platform
     - Detects WSL, headless environments, and Apple Silicon
@@ -120,7 +122,7 @@
   </Accordion>
 
   <Accordion title="Service installation">
     - **macOS** — creates a launchd service named like `com.nanoclaw-v2-<slug>` in `~/Library/LaunchAgents/`
     - **Linux (systemd)** — user service named like `nanoclaw-v2-<slug>.service`; enables `loginctl linger` so the service survives SSH logout
     - **WSL without systemd** — creates a `start-nanoclaw.sh` wrapper; you run it manually on login or wire it to `.bashrc`
   </Accordion>
@@ -178,7 +180,7 @@
     Change the trigger word, tune timeouts, adjust engage modes
   </Card>
   <Card title="Security model" icon="shield" href="/concepts/security">
     Sender allowlists, user roles, unknown-sender policies
   </Card>
   <Card title="Troubleshooting" icon="life-ring" href="/advanced/troubleshooting">
     Common issues and how Claude Code helps you fix them