codeaholicguy · Oct 18, 2026
diff --git a/README.md b/README.md
@@ -16,7 +16,15 @@ AI DevKit gives Claude Code, Codex CLI, Gemini CLI, opencode, Pi, Cursor, GitHub
 
 The future is many AI coding agents. AI DevKit is the layer that makes them manageable.
 
-Run `npx ai-devkit@latest init` and your project gets:
+Run machine setup once, then `init` in each project:
+
+```bash
+npx ai-devkit@latest setup
+cd your-project
+npx ai-devkit@latest init
+```
+
+`setup` installs built-in skills globally, session hooks, and the memory MCP wiring. `init` writes project-local config. Your project gets:
 
 | What you need | What AI DevKit installs |
 |---------------|-------------------------|
@@ -56,10 +64,14 @@ Before AI DevKit, your agents are powerful but scattered. After AI DevKit, they
 ## Start in 30 seconds
 
 ```bash
+npx ai-devkit@latest setup
+cd your-project
 npx ai-devkit@latest init
 ```
 
-One wizard. Pick your agents, install the control-plane pieces you need, and give every tool the same operating model. It writes project-local files you can review and commit. Re-run it whenever your agent list or workflow changes.
+Run `setup` once per machine, then `init` per project. Pick your agents, install the control-plane pieces you need, and give every tool the same operating model. Re-run `init` whenever your agent list or workflow changes.
+
+Multi-agent orchestration (lead plus workers): **[docs guide](https://ai-devkit.com/docs/17-multi-agent-orchestration/)**.
 
 Here's what lands in your repo:
 
@@ -68,7 +80,7 @@ your-project/
 ├── .ai-devkit.json              # single source of truth (re-run init anytime)
 ├── .claude/                     # or .cursor/, .codex/, etc. per agent you picked
 │   ├── skills/                  # dev-lifecycle, verify, memory, tdd, ...
-│   └── settings.json            # MCP servers wired up (incl. @ai-devkit/memory)
+│   └── …                        # Claude: project MCP in `.mcp.json`; memory MCP wired globally by `setup`
 └── docs/ai/
     ├── requirements/            # phase 1 — what to build, why
     ├── design/                  # phase 2 — how it'll be built
@@ -79,7 +91,7 @@ your-project/
 
 ## Operate agents like infrastructure
 
-AI DevKit ships a agent control plane for everyday multi-agent work:
+AI DevKit ships an agent control plane for everyday multi-agent work:
 
 ```bash
 # List running sessions across providers
@@ -171,7 +183,7 @@ Agent:  Audits the diff against the design doc — scope creep,
 
 ## What changes in agent behavior
 
-The flow above is powered by nine built-in skills, each addressing a failure mode developers see in real AI coding sessions:
+The flow above is powered by **24 built-in skills** (installed globally by `setup`), including these core workflow skills:
 
 | Failure mode | AI DevKit behavior |
 |--------------|--------------------|
@@ -183,39 +195,41 @@ The flow above is powered by nine built-in skills, each addressing a failure mod
 | Debugging becomes guess-and-patch | `structured-debug` makes it reproduce, hypothesize, fix, and verify |
 | Existing code is opaque | `document-code` maps entry points, dependencies, and behavior |
 | Implementation gets bloated | `simplify-implementation` reduces complexity before code ships |
-| Documentation is hard to follow | `technical-writer` audits docs for novice-user clarity |
+| Documentation is hard to follow | `document-code` maps code; add community `technical-writer` via `skill add` if needed |
 
-Need more? `ai-devkit skill add <registry> <skill>` pulls from 30+ publishers — Anthropic, Vercel, Supabase, Microsoft, Google.
+Need more? `ai-devkit skill add <registry> <skill>` pulls from 30+ publishers — Anthropic, Vercel, Supabase, Microsoft, Google. See the full built-in list in [Skills docs](https://ai-devkit.com/docs/7-skills/).
 
 ## Works across coding agents
 
 One `.ai-devkit.json` configures all of them. Add a new agent to your team without rewriting your rules.
 
-| Agent | Setup | Remote control |
+| Agent / environment | Project `init` setup | `agent start` / `send` control plane |
 |-------|-------|----------------|
-| [Claude Code](https://www.anthropic.com/claude-code) | yes | yes |
-| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | yes | yes |
-| [Codex CLI](https://github.com/openai/codex) | yes | yes |
-| [Grok Build CLI](https://x.ai/cli) | yes | yes |
-| [Junie](https://www.jetbrains.com/junie/) | yes | — |
-| [Cline](https://cline.bot/) | yes | — |
-| [Devin](https://devin.ai/) | yes | — |
-| [opencode](https://opencode.ai/) | yes | testing |
-| [Pi](https://pi.dev) | yes | yes |
-| [Kiro CLI](https://kiro.dev/cli/) | yes | yes |
+| [Claude Code](https://www.anthropic.com/claude-code) | yes | yes (`claude`) |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | yes | yes (`gemini_cli`) |
+| [Codex CLI](https://github.com/openai/codex) | yes | yes (`codex`) |
+| [Grok Build CLI](https://x.ai/cli) | yes | yes (`grok_cli`) |
+| [opencode](https://opencode.ai/) | yes | yes (`opencode`) |
+| [Pi](https://pi.dev) | yes | yes (`pi`) |
+| [GitHub Copilot](https://github.com/features/copilot) | yes | yes (`copilot`) |
+| [Kiro CLI](https://kiro.dev/cli/) | yes | yes (`kiro`) |
+| [Devin](https://devin.ai/) | yes | yes (`devin`) |
+| [Muse Code](https://dev.meta.ai/products/muse-code/) | yes | yes (`muse`) |
+| [Antigravity CLI](https://antigravity.google/) | yes | yes (`antigravity_cli`) |
 | [Cursor](https://cursor.sh/) | yes | — |
-| [GitHub Copilot](https://code.visualstudio.com/) | yes | — |
-| [Antigravity](https://antigravity.google/) | yes | yes |
-| [Amp](https://ampcode.com/) | yes | — |
-| [Kilo Code](https://github.com/Kilo-Org/kilocode) | yes | — |
-| [Roo Code](https://roocode.com/) | testing | — |
+| [Junie](https://www.jetbrains.com/junie/) | yes | setup/skills only |
+| [Cline](https://cline.bot/) | yes | setup/skills only |
+| [Antigravity IDE](https://antigravity.google/) | yes | setup/skills only |
+| [Amp](https://ampcode.com/) | yes | setup/skills only |
+| [Kilo Code](https://github.com/Kilo-Org/kilocode) | yes | setup/skills only |
+| [Roo Code](https://roocode.com/) | testing | setup/skills only |
 
-**Setup** — `ai-devkit init` writes the agent's config (rules, MCP servers, and skills) so it joins the same operating layer.
-**Remote control** — drive running sessions from `ai-devkit agent send` and route them through external channels.
+**Setup** — `ai-devkit setup` (machine) plus `ai-devkit init` (project) writes each agent's config (rules, MCP, skills).
+**Control plane** — `agent list`, `agent send`, and managed `agent start` target tmux-backed CLI sessions on **macOS/Linux** (experimental console; requires tmux). Use [channels](https://ai-devkit.com/docs/12-channel/) to message a running agent from Telegram or Slack. Not supported on Windows console.
 
 ## How is this different from `CLAUDE.md`, `.cursor/rules`, or `AGENTS.md`?
 
-Those files are static instructions the agent re-reads. AI DevKit gives agents a **operating layer**: generated setup, a control console, cross-agent messaging, local searchable memory, phase docs, skills loaded on demand, and verification gates. The rules still matter, but AI DevKit makes them operational across tools.
+Those files are static instructions the agent re-reads. AI DevKit gives agents an **operating layer**: generated setup, a control console, cross-agent messaging, local searchable memory, phase docs, skills loaded on demand, and verification gates. The rules still matter, but AI DevKit makes them operational across tools.
 
 | Static rules files | AI DevKit |
 |--------------------|-----------|
@@ -230,13 +244,13 @@ Those files are static instructions the agent re-reads. AI DevKit gives agents a
 - **Not a smarter LLM.** Bad models stay bad — this raises the floor on process, not on raw capability.
 - **Not a replacement for Claude Code, Codex, Cursor, Gemini CLI, or opencode.** AI DevKit configures, supervises, and coordinates the agents you already use.
 - **Not a magic "write the feature for me" button.** You still review the requirements doc, accept the design, and read the diff. The workflow makes that review possible because you have artifacts to point at instead of only chat scrollback.
-- **Not a hosted service.** Apache-2.0-licensed, runs locally, no telemetry. Memory is a SQLite file on your disk. The agent control plane talks to the agent SDKs you already use.
+- **Not a hosted service.** Apache-2.0-licensed, runs locally, no telemetry. Memory is a SQLite file on your disk. The control plane detects CLI sessions, types into tmux panes, and reads session files — it does not run a remote cloud agent for you.
 
 ## Documentation & community
 
 - Full guides, workflow patterns, skill authoring → **[ai-devkit.com/docs](https://ai-devkit.com/docs/)**
 - Release notes → **[CHANGELOG.md](./CHANGELOG.md)**
-- Contributing → **[CONTRIBUTING.md](./CONTRIBUTING.md)**
+- Contributing → open an issue or PR on **[GitHub](https://github.com/Codeaholicguy/ai-devkit)**
 
 ```bash
 git clone https://github.com/Codeaholicguy/ai-devkit.git

diff --git a/web/app/sitemap.ts b/web/app/sitemap.ts
@@ -50,7 +50,7 @@ export default function sitemap(): MetadataRoute.Sitemap {
 
   const docs = getAllDocPages();
   const docRoutes = docs.map((doc) => ({
-    url: `${baseUrl}/docs/${doc.metadata.slug}`,
+    url: `${baseUrl}/docs/${doc.metadata.slug}/`,
     lastModified: new Date(),
     changeFrequency: 'weekly' as const,
     priority: 0.7,

diff --git a/web/content/docs/0-what-is-ai-devkit.md b/web/content/docs/0-what-is-ai-devkit.md
@@ -79,7 +79,7 @@ The [Memory](/docs/6-memory) service gives your coding agents persistent, local
 
 ### Multi-Agent Support
 
-AI DevKit isn't tied to a single tool. It supports [many AI coding environments](/docs/2-supported-agents) and sets up the right configuration files, skills, and instructions for each one. Switch between agents or use multiple at the same time. Your workflows, memory, skills, and operating model carry across supported environments.
+AI DevKit isn't tied to a single tool. It supports [many AI coding environments](/docs/2-supported-agents) and sets up the right configuration files, skills, and instructions for each one. Switch between agents or use multiple at the same time. Your workflows, memory, skills, and operating model carry across supported environments. Managed `agent start` and `agent send` apply to the CLI harness types listed in [Agent Management](/docs/8-agent-management).
 
 ### Observe And Operate
 

diff --git a/web/content/docs/1-getting-started.md b/web/content/docs/1-getting-started.md
@@ -21,8 +21,16 @@ Before you begin, make sure you have:
 - **Node.js 20.20.0 or newer**
 - **npm** or **npx**, which comes with Node.js
 - **tmux** for interactive managed agents (provisional compatibility floor: tmux 2.6+; setup reports but does not reject older versions)
+- **`lsof` on Linux** for reliable agent session detection (strongly recommended; see [Agent Management](/docs/8-agent-management#linux-session-detection))
 - At least one [supported AI coding agent or environment](/docs/2-supported-agents)
 
+### Node.js and native modules
+
+The CLI bundles native SQLite support (`better-sqlite3`) compiled for the **Node version used when you installed** `ai-devkit`. If agents run under a different Node (common when tmux inherits another `PATH`), memory and related commands can fail with a `NODE_MODULE_VERSION` error.
+
+- Reinstall `ai-devkit` with the same Node your agents use, or align the tmux server environment: `tmux set-environment -g PATH '/path/to/node/bin:…'`.
+- Pin one Node version for `npm test` and for agent shells so verification matches CI.
+
 Install and launch your coding agent at least once before running `setup`. AI DevKit detects an agent from its home directory, so a newly installed agent that has never started may be reported as skipped.
 
 ## Choose How to Run AI DevKit
@@ -174,9 +182,11 @@ The installed workflow skills guide requirements, design, planning, implementati
 1. [Check environment-specific project support](/docs/2-supported-agents)
 2. [Learn how project init and install work](/docs/9-agent-setup)
 3. [Operate running agents](/docs/13-agent-console)
-4. [Give agents long-term memory](/docs/6-memory)
-5. [Manage skills](/docs/7-skills)
-6. [Install plugins](/docs/14-plugins)
+4. [Multi-agent orchestration](/docs/17-multi-agent-orchestration) (lead plus workers)
+5. [Give agents long-term memory](/docs/6-memory)
+6. [Manage skills](/docs/7-skills)
+7. [Install plugins](/docs/14-plugins)
+8. [Troubleshooting agents](/docs/18-troubleshooting-agents)
 
 ## Need Help?
 

diff --git a/web/content/docs/15-capacity.md b/web/content/docs/15-capacity.md
@@ -17,7 +17,9 @@ ai-devkit status
 ai-devkit status --json
 ```
 
-The report covers the CLI version (and whether npm has a newer one), the project config, per-agent readiness (executable found, authentication, skills installed), tmux, skill registries, channels, and per-agent memory MCP wiring. Run it first when something feels off — it is the fastest way to tell a missing login from a missing binary.
+The report covers the CLI version (and whether npm has a newer one), the project config, per-agent readiness (executable found, authentication, skills installed), tmux, skill registries, channels, and per-agent memory MCP wiring. Run it first when something feels off.
+
+Treat auth and readiness rows as hints: some harnesses show `ready` without a successful login probe, and others show `auth fail` when a login-free model path still works. For orchestration, prefer a real `agent start` plus `send` handshake (see [Multi-agent orchestration](/docs/17-multi-agent-orchestration)).
 
 ## Capacity
 

diff --git a/web/content/docs/16-runtime.md b/web/content/docs/16-runtime.md
@@ -24,19 +24,28 @@ ai-devkit daemon install    # install a systemd --user unit for boot persistence
 
 `daemon install` writes a `systemd --user` unit so the daemon survives logout and reboot; it is available on Linux only. To remove persistence, disable the unit with `systemctl --user` and run `ai-devkit daemon stop`.
 
+### Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `DEVKITD_BIN` | Path to a custom `devkitd` binary (documented above) |
+| `AI_DEVKIT_NO_DAEMON` | When set, skip auto-spawning `devkitd` and use in-process behavior (useful when debugging stale daemon issues) |
+
 ## Troubleshooting
 
 - **"binary not found"**: the daemon binary is resolved from `DEVKITD_BIN`, the platform package, or a cargo build — set `DEVKITD_BIN` to a valid `devkitd` binary if you run from a source checkout.
 - **Stale socket**: if the daemon crashed, delete `~/.ai-devkit/daemon.sock` and let the next command respawn it.
-- **Logs**: `ai-devkit daemon logs -n 200` shows recent daemon activity, including auto-spawn failures.
+- **Logs**: `ai-devkit daemon logs -n 200` (or `daemon logs --lines 200`) shows recent daemon activity, including auto-spawn failures.
+- **Stale daemon after upgrade**: an old `devkitd` can keep serving until you run `ai-devkit daemon stop`, then retry your command. Use `AI_DEVKIT_NO_DAEMON=1` to compare behavior without the daemon.
 
-## Upgrading to 0.69
+## Upgrading to 0.69+
 
 0.69 is the first release that distributes a platform binary and runs the daemon. On upgrade:
 
-1. No manual step is needed — the daemon auto-spawns on the next `ai-devkit agent` command.
-2. Everything lives under `~/.ai-devkit/` (`daemon.sock`, `daemon.log`); nothing is written to your project.
-3. To stop it entirely, run `ai-devkit daemon stop`. To keep it running across reboots, run `ai-devkit daemon install` on Linux.
+1. Run `ai-devkit daemon stop` after upgrading the CLI so a new `devkitd` binary is not mixed with an old long-running process.
+2. The next `ai-devkit agent` command auto-spawns the daemon if needed.
+3. Everything lives under `~/.ai-devkit/` (`daemon.sock`, `daemon.log`); nothing is written to your project.
+4. To stop it entirely, run `ai-devkit daemon stop`. To keep it running across reboots, run `ai-devkit daemon install` on Linux.
 
 ## Next Steps