audit-readme-md

Metadata

Description

## Description
README.md is the project's top-level pitch. Audit it for: feature completeness (all major capabilities mentioned), accurate command examples, no references to superseded names (local:, oai-compat:, wgnext, coordinator), updated install/quickstart steps.

## 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-readme-md

Required by

• done doc-sync-audit

Log

• 2026-04-30T02:05:06.277000173+00:00 Task paused
• 2026-04-30T02:06:29.361045684+00:00 Task published
• 2026-04-30T02:14:16.503650854+00:00 Spawned by coordinator --executor claude --model sonnet
• 2026-04-30T02:14:32.472404250+00:00 Starting audit of README.md - identifying baseline commit
• 2026-04-30T02:31:38.565688873+00:00 Completed analysis - identified baseline and enumerated deltas, posting findings
• 2026-04-30T02:31:49.744869863+00:00 BASELINE: Fallback 2026-04-12 (commit 85213202b, doc-sync-apr12 agent). All commits touching README.md since baseline are agent commits; the last non-agent-pattern commit was 3f69a2887 (tb-writeup, 2026-04-04), but 85213202b is the last README update before wave-1 agent work, matching the task's stated fallback date. Audit scope: 530+ commits since 2026-04-12.
• 2026-04-30T02:31:57.973460432+00:00 DELTA 1 - Missing: wg secret command. The wg secret command (implement-wg-secret, agent-1070) is entirely absent from README. This is a new top-level command for managing API keys in a credential store (keyring backend at ~/.wg/keystore/ or plaintext). Subcommands: set, get, list, rm, check, backend. README's API key section (lines 544-549) still documents wg key set/check/list only, while wg secret is the richer credential store interface. Both wg key and wg secret exist as separate commands.
• 2026-04-30T02:32:05.189996948+00:00 DELTA 2 - Missing: wg profile command. The wg profile command (implement-named-profiles agent-1018, rename-wgnext-profile agent-1060) is entirely absent from README. Manages provider profiles (model tier presets) stored in ~/.wg/profiles/. Subcommands: use, show, list, create, edit, delete, diff, init-starters, refresh. Profile init-starters now creates claude/codex/nex profiles (not wgnext - renamed). README mentions named routes but not the runtime profile management commands.
• 2026-04-30T02:32:14.327670368+00:00 DELTA 3 - Missing: wg html command. The wg html command (html-graph-view agent-919, wg-html-v2 agent-1049, wg-html-chat agent-1131) is absent from README. Renders workgraph as static HTML/CSS/JS viewer (TUI-parity). Outputs to ./public/ by default. Flags: --out, --public-only, --all, --chat, --since. README's Utilities section (lines 969-996) mentions wg viz --mermaid and wg viz --graph but not wg html.
• 2026-04-30T02:32:37.589712593+00:00 DELTA 4 - Missing: wg reap command. The wg reap command (impl-reap, 2026-04-13) is absent from README. Garbage-collects dead/done/failed agents from the registry. Flags: --dry-run, --older-than. README's agent management section (lines 459-499) only mentions wg dead-agents --remove and --purge but not wg reap.
• 2026-04-30T02:33:02.911308327+00:00 DELTA 5 - Stale: wg compact command. README line 974 shows 'wg compact # distill graph state into context.md' in the Utilities section. The wg compact command was REMOVED in commit 2422b05b4 (retire-compact-N, 2026-04-26). Running 'wg compact' now gives 'error: unrecognized subcommand compact'. Archival now runs natively in the dispatcher; there is a wg migrate compact-retire command for cleaning up old .compact-N tasks.
• 2026-04-30T02:33:11.001778710+00:00 DELTA 6 - Stale: wg service coordinator command names. README table (lines 445-449) lists: wg service create-coordinator, wg service stop-coordinator, wg service archive-coordinator, wg service delete-coordinator, wg service interrupt-coordinator. These were renamed: canonical names are now wg service create-chat, stop-chat, archive-chat, delete-chat, interrupt-chat. The old names are deprecated legacy aliases. Additionally, the preferred way to create a chat is now 'wg chat create' (wg service create-chat itself emits a deprecation warning: 'use wg chat create instead'). Also missing from table: wg service purge-chats (new bulk-purge command) and wg service set-executor (hot-swap executor/model).
• 2026-04-30T02:33:20.225793444+00:00 DELTA 7 - Missing/Incomplete: wg chat first-class entity. README section 'Communication' (lines 730-751) describes wg chat as only supporting: send, interactive REPL, attachment, coordinator target, history, clear. But wg chat is now a first-class graph entity (commit 47bd268d0) with full subcommands: create, list, show, attach, send, stop, resume, archive, delete. README does not mention wg chat create/list/show/attach/stop/resume/archive/delete.
• 2026-04-30T02:33:30.552528173+00:00 DELTA 8 - Stale/Inconsistent: wg kill missing --tree flag. README section 'Kill agents' (lines 472-478) shows wg kill agent-7, wg kill agent-7 --force, wg kill --all. Missing: wg kill --tree <task-id> (added in impl-kill-tree, 2026-04-13) which cascades kill+abandon through downstream tasks. Also missing: --dry-run and --no-abandon flags.
• 2026-04-30T02:33:41.530896183+00:00 DELTA 9 - Stale: TUI inspector panel tabs. README line 567 says: 'nine tabbed views accessible via Alt+Left/Alt+Right (with slide animation): Chat, Detail, Log, Messages, Agency, Config, Files, Coordinator Log, and Firehose.' Current tabs (from RightPanelTab enum) are: Chat(0), Detail(1), Agency(2), Config(3), Log(4), CoordLog(5), Dashboard(6), Messages(7), Settings(8). Files, Firehose, Output are dead/unused tabs. New tabs: Dashboard and Settings. Order differs from README. Firehose description in README is stale.
• 2026-04-30T02:38:58.266765213+00:00 DELTA 10 - Stale: wg tui --refresh-rate flag. README line 556 shows 'wg tui [--refresh-rate 2000] # default: 2000ms refresh'. This flag no longer exists in wg tui. Current wg tui flags: --no-mouse, --recording, --trace, --show-keys, --history-depth, --no-history. The --refresh-rate flag was removed.
• 2026-04-30T02:39:05.589127411+00:00 DELTA 11 - Stale: Global config path inconsistency. README line 418 shows 'wg config --global # show/set global config only (~/.workgraph/config.toml)' but the actual global config path is ~/.wg/config.toml (confirmed by ls -la ~/). Lines 47 and 57 correctly say ~/.wg/config.toml. Line 418 uses the old ~/.workgraph/ path which doesn't exist.
• 2026-04-30T02:39:14.949338312+00:00 DELTA 12 - Stale: Task status list missing 'incomplete' and 'failed-pending-eval'. README line 924 says tasks have status: open, in-progress, done, failed, abandoned, blocked, pending-validation, waiting. The actual CLI filter values ('wg list --status') show: open, in-progress, done, blocked, failed, abandoned, incomplete. 'incomplete' status is valid but missing from README status list. 'waiting' and 'pending-validation' are mentioned but not filterable. 'failed-pending-eval' exists in code (commit cae4cca54) as a new intermediate status.
• 2026-04-30T02:39:26.320650256+00:00 DELTA 13 - Stale: --verify flag promoted in README but now hidden/deprecated. README section 3 (line 129) and section 4 (line 157) show '--verify' as a first-class flag for wg add and wg edit. Section 7 (lines 192-208) has an entire 'Verification workflow' using --verify prominently. But --verify is now hidden (hide=true in cli.rs, commit d7a7cf18f remove-validation-cli) with doc comment 'DEPRECATED - put validation criteria in a ## Validation section of the task description'. The flag still works but is not shown in wg add --help. README should document ## Validation section pattern instead.
• 2026-04-30T02:39:31.955985233+00:00 DELTA 14 - Stale: codex-cli route default model. README line 62 (routes table) says codex-cli route has 'Default model spec: codex:gpt-5'. Actual codex profile template (src/profile/templates/codex.toml) uses codex:gpt-5.5 as the default/premium model and codex:gpt-5.4 for standard. Should be codex:gpt-5.5.
• 2026-04-30T02:40:10.790304993+00:00 DELTA 15 - Missing: wg config lint subcommand. README's Configuration section (lines 380-420) documents wg config flags but omits 'wg config lint' (added in implement-wg-config agent-831). 'wg config lint' is a read-only companion to wg migrate config that reports deprecated keys and stale model strings without making changes. Related: README shows wg config --merged flag but the actual flag added by endpoint-inheritance-opt (agent-152) is --merged for showing effective merged config.
• 2026-04-30T02:40:32.041678420+00:00 DELTA 16 - Missing: wg sweep --reap-targets flag. README line 975 shows 'wg sweep # detect and recover orphaned in-progress tasks'. But --reap-targets flag (worktree-target-dirs agent-816) was added that also removes cargo target/ build artifacts from dead-agent worktrees.
• 2026-04-30T02:40:37.023963878+00:00 DELTA 17 - Missing: wg session command. wg session (Manage nex chat sessions) is a top-level command entirely absent from README. Subcommands: list, attach, new, fork, alias, rm, release, status, check. Relevant to nex-based deployments where users may interact with chat sessions directly.
• 2026-04-30T02:40:48.369872721+00:00 DELTA 18 - Missing: wg add --priority, --cron, --subtask, --independent flags. README's 'Add some tasks' section (lines 106-147) demonstrates many wg add flags but omits: --priority (task priority with named levels: critical/high/normal/low/idle), --cron (recurring tasks with 6-field cron expression), --subtask (creates blocking child-parent relationship), --independent (suppress implicit --after on creating task).
• 2026-04-30T02:40:58.806287266+00:00 DELTA 19 - Inconsistent: wg skill install path. README line 219 says 'wg skill install # installs to ~/.claude/skills/ (all your projects)'. Actual install path is ~/.claude/skills/wg/ (a subdirectory), per wg skill install --help.
• 2026-04-30T02:41:18.124696291+00:00 DELTA 20 - Missing: wg retry --fresh and --preserve-session flags. README line 793 mentions 'wg retry stuck-task' (added in recommended flow) but doesn't document the command's flags in the Utilities or agent management sections. New flags added: --fresh (discard prior worktree and start from main), --preserve-session (keep stored Claude session ID), --reason.
• 2026-04-30T02:41:26.113604827+00:00 VALIDATION: Baseline=2026-04-12 (commit 85213202b, fallback applied — all README commits since then are agent-authored). Delta list posted with 20 structured entries. No source or doc file modifications made. Audit only.
• 2026-04-30T02:41:43.550798919+00:00 Task pending eval (agent reported done; awaiting `.evaluate-*` to score)
• 2026-04-30T02:43:42.801187309+00:00 PendingEval → Done (evaluator passed; downstream unblocks)