From d07315a772244fad31ffffcf4ef6c9faa60f2ebf Mon Sep 17 00:00:00 2001
From: Levi Neely <lkn@darkstar.example.net>
Date: Thu, 19 Feb 2026 23:42:04 +0100
Subject: [PATCH] Reorganize README for logical flow

New section order:
1. Architecture/Requirements/Installation/Usage (getting started)
2. Configuration (env vars, templates) - before backends
3. Backends & Sandboxing (references Configuration templates)
4. 9P Filesystem (understand backend first, then filesystem)
5. Workflows (uses 9P concepts)
6. MCP Integration (alternative integration method)
7. Troubleshooting (end)

Improves flow: config before use, concepts before advanced features
---
 README.md | 96 +++++++++++++++++++++++++++----------------------------
 1 file changed, 48 insertions(+), 48 deletions(-)

diff --git a/README.md b/README.md
index 4c7b453..1faf4b7 100644
--- a/README.md
+++ b/README.md
@@ -69,6 +69,54 @@ NAMESPACE=/tmp/ns.$USER.:1 Assist          # connect
 | `Daemon` | Manage daemon |
 | `Inbox [id]` / `Archive [id]` | View messages |
 
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NAMESPACE` | `/tmp/ns.$USER.:0` | 9P namespace for server/client communication |
+| `ANVILLM_BEADS_PATH` | `~/.beads` | Beads database location (shared across namespaces) |
+| `ANVILLM_TERMINAL` | `foot` | Terminal command for tmux attach (Assist) |
+| `ANTHROPIC_API_KEY` | — | Claude API key (required for Claude backend) |
+| `CLAUDE_AGENT_NAME` | `anvillm-agent` | Claude agent configuration name |
+| `KIRO_API_KEY` | — | Kiro API key (required for Kiro backend) |
+
+### Sandbox Config Templates
+
+Available in sandbox YAML files (`~/.config/anvillm/`):
+
+| Template | Expands To | Description |
+|----------|------------|-------------|
+| `{CWD}` | Current working directory | Session's working directory |
+| `{HOME}` | User home directory | `$HOME` |
+| `{TMPDIR}` | Temp directory | `$TMPDIR` or `/tmp` |
+| `{XDG_CONFIG_HOME}` | XDG config | `$XDG_CONFIG_HOME` or `~/.config` |
+| `{XDG_DATA_HOME}` | XDG data | `$XDG_DATA_HOME` or `~/.local/share` |
+| `{XDG_CACHE_HOME}` | XDG cache | `$XDG_CACHE_HOME` or `~/.cache` |
+| `{XDG_STATE_HOME}` | XDG state | `$XDG_STATE_HOME` or `~/.local/state` |
+
+## Backends & Sandboxing
+
+**Backends:** Claude (`npm install -g @anthropic-ai/claude-code`), Kiro ([kiro.dev](https://kiro.dev)) — Sandboxed with network access
+
+**Add:** Implement `CommandHandler`/`StateInspector` in `internal/backends/yourbackend.go`, register in `main.go`
+
+**Sandbox:** [landrun](https://github.com/zouuup/landrun) (cannot disable) — Defaults: CWD/`/tmp`/config (rw), `/usr`/`/lib`/`/bin` (ro+exec), no network
+
+**Config** (`~/.config/anvillm/`): `global.yaml` → `backends/<name>.yaml` → `roles/<name>.yaml` (default: `roles/default.yaml`) → `tasks/<name>.yaml` — Most permissive wins
+
+```yaml
+network: {enabled: true, unrestricted: true}
+filesystem: {rw: ["{CWD}", "{HOME}/.npm"]}
+```
+
+Templates: `{CWD}`, `{HOME}`, `{TMPDIR}`, `{XDG_*}` (see Configuration) — Tip: Make `roles/default.yaml` permissive
+
+**Kernel:** 5.13+ (Landlock v1), 6.7+ (v4), 6.10+ (v5 network) — Best-effort: `best_effort: true` (⚠️ unsandboxed if no Landlock)
+
+**Self-healing:** Auto-restarts crashes every 5s (preserves context/alias/cwd) — Skips intentional stops
+
 ## 9P Filesystem
 
 `$NAMESPACE/agent`:
@@ -141,27 +189,6 @@ echo 'Hello' | 9p write agent/a3f2b9d1/in
 
 See `SECURITY.md`
 
-## Backends & Sandboxing
-
-**Backends:** Claude (`npm install -g @anthropic-ai/claude-code`), Kiro ([kiro.dev](https://kiro.dev)) — Sandboxed with network access
-
-**Add:** Implement `CommandHandler`/`StateInspector` in `internal/backends/yourbackend.go`, register in `main.go`
-
-**Sandbox:** [landrun](https://github.com/zouuup/landrun) (cannot disable) — Defaults: CWD/`/tmp`/config (rw), `/usr`/`/lib`/`/bin` (ro+exec), no network
-
-**Config** (`~/.config/anvillm/`): `global.yaml` → `backends/<name>.yaml` → `roles/<name>.yaml` (default: `roles/default.yaml`) → `tasks/<name>.yaml` — Most permissive wins
-
-```yaml
-network: {enabled: true, unrestricted: true}
-filesystem: {rw: ["{CWD}", "{HOME}/.npm"]}
-```
-
-Templates: `{CWD}`, `{HOME}`, `{TMPDIR}`, `{XDG_*}` (see Configuration) — Tip: Make `roles/default.yaml` permissive
-
-**Kernel:** 5.13+ (Landlock v1), 6.7+ (v4), 6.10+ (v5 network) — Best-effort: `best_effort: true` (⚠️ unsandboxed if no Landlock)
-
-**Self-healing:** Auto-restarts crashes every 5s (preserves context/alias/cwd) — Skips intentional stops
-
 ## Workflows
 
 **Skills:** `anvillm-skills list`, `anvillm-skills load anvillm-communication`
@@ -193,33 +220,6 @@ See `workflows/`, `kiro-cli/SKILLS_PROMPT.md`
 
 Enables LLM clients to control AnviLLM sessions and communicate with agents
 
-## Configuration
-
-### Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `NAMESPACE` | `/tmp/ns.$USER.:0` | 9P namespace for server/client communication |
-| `ANVILLM_BEADS_PATH` | `~/.beads` | Beads database location (shared across namespaces) |
-| `ANVILLM_TERMINAL` | `foot` | Terminal command for tmux attach (Assist) |
-| `ANTHROPIC_API_KEY` | — | Claude API key (required for Claude backend) |
-| `CLAUDE_AGENT_NAME` | `anvillm-agent` | Claude agent configuration name |
-| `KIRO_API_KEY` | — | Kiro API key (required for Kiro backend) |
-
-### Sandbox Config Templates
-
-Available in sandbox YAML files (`~/.config/anvillm/`):
-
-| Template | Expands To | Description |
-|----------|------------|-------------|
-| `{CWD}` | Current working directory | Session's working directory |
-| `{HOME}` | User home directory | `$HOME` |
-| `{TMPDIR}` | Temp directory | `$TMPDIR` or `/tmp` |
-| `{XDG_CONFIG_HOME}` | XDG config | `$XDG_CONFIG_HOME` or `~/.config` |
-| `{XDG_DATA_HOME}` | XDG data | `$XDG_DATA_HOME` or `~/.local/share` |
-| `{XDG_CACHE_HOME}` | XDG cache | `$XDG_CACHE_HOME` or `~/.cache` |
-| `{XDG_STATE_HOME}` | XDG state | `$XDG_STATE_HOME` or `~/.local/state` |
-
 ## Troubleshooting
 
 | Problem | Solution |