audit-wg-quickstart

Metadata

Description

## Description
The text emitted by `wg quickstart` and `wg setup` (likely in src/commands/quickstart.rs and src/commands/setup.rs as include_str! sources or similar). Audit for current commands referenced, current flag examples, model spec examples (nex: not local:), tmux dependency mention.

## Baseline

Determine baseline = last commit that touched this file by a human (heuristic: commits NOT authored by an agent — agent commits have agent IDs in commit messages; human commits do not). If unclear, fall back to 2026-04-12 (date of prior doc-sync-audit doc).

Audit scope = ALL changes to wg behavior / commands / config / state-machine / etc. SINCE that baseline. Not just today. Look at git log between baseline and HEAD.

## Output (no source/doc changes)
Post findings via \`wg log <this-task-id>\` as a structured list of deltas. Each delta = one specific update needed in the audited file. Format:

  - **Section X:** <what is currently said vs what should be said, with citation>
  - **Missing:** <feature/command/concept not mentioned>
  - **Stale:** <reference to removed or superseded thing>
  - **Inconsistent:** <conflicts with another doc — note which>

The synthesis task (doc-sync-audit) reads all audit logs and applies updates. This task DOES NOT MODIFY FILES.

## Validation
- [ ] Baseline commit identified (cite SHA or fall back to 2026-04-12 with reasoning)
- [ ] Delta list posted via wg log with structured entries
- [ ] No source / doc modifications — audit only

Depends on

• done quality-pass-doc
• done .assign-audit-wg-quickstart

Required by

• done doc-sync-audit

Log

• 2026-04-30T02:05:06.507015917+00:00 Task paused
• 2026-04-30T02:09:03.455078529+00:00 Task published
• 2026-04-30T02:09:36.235008768+00:00 Lightweight assignment: agent=Default Evaluator (31847164), exec_mode=light, context_scope=full, reason=Evaluator role specializes in assessment and audit tasks; high score (0.86) and 377 completed tasks demonstrate strong capability for thorough documentation review and discrepancy identification.
• 2026-04-30T02:14:13.202792995+00:00 Spawned by coordinator --executor claude --model sonnet
• 2026-04-30T02:14:21.859970666+00:00 Starting audit of wg quickstart and wg setup text
• 2026-04-30T02:17:23.272318595+00:00 Completed source analysis. Baseline: c4fd5f6ee (doc-sync-apr12, 2026-04-12). Found ~8 deltas. Posting findings.
• 2026-04-30T02:18:07.928631295+00:00 AUDIT FINDINGS — wg quickstart text + wg setup wizard ## Baseline Commit c4fd5f6ee (docs: update quickstart to match current CLI and features, doc-sync-apr12, ~2026-04-12). This is the last human-authored commit to src/commands/quickstart.rs. All deltas below are changes to wg behavior since that commit. --- ## Deltas for src/commands/quickstart.rs ### Stale: EXECUTORS & MODELS — deprecated --coordinator-executor pattern - **Currently says:** 'wg config --coordinator-executor amplifier' (line 444) - **Should say:** Use model spec prefix to select handler: 'wg config --model openrouter:model-id' (routes through nex). The --coordinator-executor / --dispatcher-executor flag is deprecated and emits a warning at runtime: 'derives handler from model spec prefix now' - **Citation:** src/dispatch/handler_for_model.rs (comment block); CLAUDE.md 'The legacy --executor / -x flag ... are deprecated'; confirmed via live 'wg config --coordinator-executor amplifier --dry-run' which outputs deprecation warning - **Note:** The flag still works (legacy), but quickstart should teach the model-spec pattern, not the deprecated executor flag ### Stale: EXECUTORS & MODELS — 'anthropic:claude-sonnet-4-6' is an unknown prefix - **Currently says:** 'wg service start --model anthropic:claude-sonnet-4-6' (line 448) and in JSON - **Should say:** 'wg service start --model claude:sonnet-4-6' or 'wg service start --model openrouter:anthropic/claude-sonnet-4-6' - **Citation:** handler_for_model.rs mapping table shows supported prefixes: claude:, codex:, nex:, openrouter:, ollama:, vllm:, llamacpp:, gemini:, native:. There is NO 'anthropic:' prefix — this would fall through to the bare/default handler (claude CLI) but the model string would be passed as-is. - **Inconsistent with:** CLAUDE.md which shows 'claude:opus' and 'nex:qwen3-coder' as correct examples ### Missing: JSON multi_coordinator section uses old coordinator subcommand names - **Currently says (JSON only):** 'wg service create-coordinator', 'wg service stop-coordinator', 'wg service archive-coordinator', 'wg service delete-coordinator' (lines 868-871) - **Should say:** 'wg service create-chat', 'wg service stop-chat', 'wg service archive-chat', 'wg service delete-chat' (the create-coordinator etc. are now legacy aliases) - **Citation:** 'wg service --help' shows: 'create-chat — Create a new chat agent session (legacy alias: create-coordinator)', wg-chat-as merge commit 47bd268d0 renamed these - **Note:** The TEXT portion of quickstart is correct (uses create-chat); only the JSON section is stale. Also the JSON key is 'multi_coordinator' but should be 'multi_chat'. ### Missing: wg service set-executor, interrupt-chat, purge-chats not documented - **Currently says:** SERVICE MODE lists create-chat, stop-chat, archive-chat, delete-chat (line 104-110) - **Should add:** - wg service set-executor # Hot-swap chat executor/model (SIGTERM + respawn) - wg service interrupt-chat # Send SIGINT to interrupt current generation - wg service purge-chats # Bulk-purge all chat agents (archive all, kill all, prevent respawn) - **Citation:** 'wg service --help' lists all three; added by wg-chat-as merge (47bd268d0) and implement-tmux-wrapped (ce6ca245a) ### Missing: tmux as dependency for chat persistence and wg server - **Currently says:** quickstart mentions 'wg server' (line 125) and wg service with chat sessions but does NOT mention tmux - **Should add:** Note in SKILL & BUNDLE SETUP or SERVICE MODE that tmux is required for chat persistence and wg server (optional dependency). The wg setup wizard now detects and reports tmux status: '✓ tmux — ready for chat persistence + wg server!' or '· tmux — not installed (needed for chat persistence + wg server)' - **Citation:** src/commands/setup.rs lines 2051-2162 (tmux detection added in ce6ca245a implement-tmux-wrapped) - **Note:** Only relevant for the wg server / multi-chat use case. Add a one-line note near wg server or in GETTING STARTED ### Missing: New commands not in quickstart (all added since c4fd5f6ee) Five new commands are not documented anywhere in wg quickstart text: a) 'wg secret' — manage secrets/API keys in credential store (6f4c98d1c, 2026-04-28) b) 'wg executors' — list executors wg knows about and which are usable on this system (862046c04) c) 'wg rescue <target> --description X' — insert first-class replacement for failed task, rewires successors (3b4c0d4fb) d) 'wg insert <position> <target> --title X' — graph-surgery primitive (bbbf37b75) e) 'wg reap' — garbage-collect dead/done/failed agents from registry (fa3220148) f) 'wg kill --tree' — cascade kill agent + abandon all downstream tasks (eb36a061c) Where to add: (a) under API KEYS section, (b) under EXECUTORS & MODELS, (c-d) under RECOVERY or new GRAPH SURGERY section, (e) under DEAD AGENT DETECTION or HOUSEKEEPING, (f) under SERVICE MODE kill commands ### Missing: failed-pending-eval task state not documented - **Currently says:** TASK STATE COMMANDS lists done, fail, retry, abandon, pause, wait, resume, unclaim, incomplete, requeue. Does NOT mention failed-pending-eval. - **Should add:** failed-pending-eval — intermediate status when agent exits non-zero with auto_evaluate=true; awaiting evaluator verdict before becoming terminal failed. 'wg fail <id>' on a failed-pending-eval task forces terminal status. - **Citation:** cae4cca54 (implement-failed-pending, 2026-04-29); src/graph.rs Status::FailedPendingEval; visible in wg list output ### Section: GETTING STARTED — wg setup comment is underspecified - **Currently says:** 'wg setup # Interactive config wizard (executor, model, agency)' (line 11) - **Should say:** 'wg setup # Interactive config wizard (5 routes: claude-cli, openrouter, codex-cli, local, nex-custom)' or add a note that --route flag enables non-interactive setup: 'wg setup --route claude-cli --yes' - **Citation:** wg-setup-5-smooth-2 (4e85dc8aa); wg setup --help shows all 5 routes and --yes flag; the comment 'executor, model, agency' predates the route-driven approach --- ## Notes on scope / what is NOT stale - Model prefix nex: vs local: — quickstart does NOT mention local: (good), and does not need to list deprecated aliases - The --verify flag is correctly absent (test at line 1390 verifies this) - The VALIDATION section correctly describes the ## Validation section approach (not the removed CLI flag) - The wg setup --scope flag and --route flag are NOT described in quickstart — this is fine since quickstart covers wg setup only as a getting-started step - The 'wg config --coordinator-executor' flag note should be a Stale/replace, not just a Missing
• 2026-04-30T02:18:44.695810958+00:00 Validated: baseline commit c4fd5f6ee identified (human commit, doc-sync-apr12). Delta list posted via wg log with 8 structured entries. No source/doc modifications made.
• 2026-04-30T02:18:46.816228851+00:00 Task pending eval (agent reported done; awaiting `.evaluate-*` to score)
• 2026-04-30T02:21:35.434870432+00:00 PendingEval → Done (evaluator passed; downstream unblocks)