docs: fix 0.70.1 audit gaps (orchestration, troubleshooting, README)

[codeaholicguy]

Summary

Documentation-only follow-up to the ai-devkit 0.70.1 Linux orchestration audit: docs site pages and README (no skill file changes).

Docs site build verified: cd web && npm ci && npm run build.

Changes by audit ID

Accuracy (A#)

ID	Change
A1	README + getting-started alignment: setup then init (README quickstart).
A2	README tree: Claude MCP via .mcp.json; memory MCP from global setup.
A3	README: 24 built-in skills; removed non-built-in technical-writer row.
A4	README harness table: agent start / send column with CLI type names; Copilot/Devin/Muse; setup-only rows for Junie, Cline, Antigravity IDE, etc.
A5	README + supported-agents: removed broken CONTRIBUTING.md link → GitHub issues/PRs.
A6	8-agent-management + orchestration guide: --name race + no list during start.
A7	8-agent-management kill section + troubleshooting: Codex PID / tmux cleanup caveat.
A8	8-agent-management + G1: ready? before --wait on ≤0.70.1; note post-#401 behavior.
A9	8-agent-management send: --timeout (10m default), --group incompatibilities, partial --id.
A10	15-capacity: status auth/readiness caveats.
A11	8-agent-management + troubleshooting: busy-send / unsafe --wait in scripts.
A12	1-getting-started Node/native modules; 6-memory cross-link.
A13	8-agent-management Linux lsof + pwdx fallback note.
A14	Troubleshooting: Pi 3-minute window (workaround).
A15	0-what-is: clarify managed agent start / send apply to CLI harness types in Agent Management (no product-specific IDE callouts).
A16	8-agent-management + orchestration: console-only task/args vs CLI start.
A17	Permissions + orchestration: pointer to setup --agent scope (not full matrix).
A18	16-runtime: daemon stop after upgrade, AI_DEVKIT_NO_DAEMON.
A19	web/app/sitemap.ts: trailing slash on doc URLs (matches trailingSlash: true).

Gaps (G#)

ID	Change
G1	New /docs/17-multi-agent-orchestration/ — worktrees, lead template, start-then-assign, cross-review, version box.
G2	New /docs/18-troubleshooting-agents/ — symptom → cause → fix from bugs.md.
G3	New /docs/19-permissions/ — Claude, Codex, OpenCode, Gemini (demo-tested); others marked needs contribution.
G5	8-agent-management#known-limitations table.
G6	Partial: documented agent send flags/behaviors and daemon logs --lines; no generated full CLI reference page.
G7	1-getting-started#nodejs-and-native-modules.
G8	Not done (5-minute wow quickstart + GIF).
G4	Not done (full harness/OS feature matrix).
G9–G12	Not done (comparison page, recipes, upgrade notes, FAQ move).
G13	Partial: durable/tmux editorial fix in agent-management; README typos; not duplicate-section edits on doc pages 5/8.

Suggested follow-up

• Update built-in agent skills (agent-management, agent-communication, agent-orchestration) to match the new docs (separate PR per owner request).

Deliberately out of scope (needs product code or larger docs projects)

1. Ship release containing merged fix(agent): wait for session file in agent send --wait #401 (agent send --wait session polling).
2. --name wins over auto-discovered registry name — fix(agent): nested agent start loses assigned name — list/send fall back to folder-PID identity #402 / mergeEntry behavior.
3. Codex shallow PID — kill/name reliability.
4. pwdx output .trim() — Linux cwd without lsof.
5. Pi session matching — session start time beyond 3-minute birthtime window.
6. OpenCode boot-time send — harness readiness before typing.
7. send --queue / refuse when busy — script-safe messaging.
8. ai-devkit status honesty — auth probes, lsof, Node ABI check.
9. agent start --prompt / harness arg passthrough.
10. Full CLI reference generated from --help in CI (G6).
11. Harness × feature matrix (G4) and slug URLs without numeric prefixes (G13/SEO).
12. Demo GIF/MP4 on README and docs hub (GTM).
13. CONTRIBUTING.md at repo root.

Test plan

• cd web && npm ci && npm run build
• git diff origin/main | rg -i '^\+.*cursor' — no matches
• git diff origin/main -- skills/ — empty (skills unchanged vs main)