audit-docs-config

Metadata

Description

## Description
Audit for: profile system documentation completeness, secret backend documentation (keyring/keystore/plaintext/passthrough), endpoint registry, model spec format, deprecation status of legacy keys, examples using current canonical names.

## 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-docs-config

Required by

• done doc-sync-audit

Log

• 2026-04-30T02:05:06.595579419+00:00 Task paused
• 2026-04-30T02:09:05.537232865+00:00 Task published
• 2026-04-30T02:14:20.474646125+00:00 Spawned by coordinator --executor claude --model sonnet
• 2026-04-30T02:14:27.889456736+00:00 Starting audit of docs/config-ux-design.md — checking baseline commit and git history
• 2026-04-30T02:19:48.569148651+00:00 Baseline identified: a08033b9f (2026-04-27, human commit). Audit range: a08033b9f..HEAD. Key changes: named profile system (b0a8677e5, 3eee268de), secret backend (6f4c98d1c, e87d384f9). Compiling structured delta list.
• 2026-04-30T02:20:49.022849952+00:00 AUDIT FINDINGS: docs/config-ux-design.md === BASELINE === Commit: a08033b9f — 'docs: design canonical wg config UX (design-canonical-wg)' by Erik Garrison, 2026-04-27. Subsequent agent commits to this file: 7555800b4 (fix-codex-cli), 79bc86f82 (bump-codex-defaults). Audit range: a08033b9f..HEAD (2026-04-27 to 2026-04-29). === DELTA LIST === --- MISSING: Named Profile System (entire feature absent) --- Implemented in: b0a8677e5 (implement-named-profiles, 2026-04-28), 3eee268de (rename-wgnext-profile, 2026-04-28), design in docs/design-named-profiles.md. config-ux-design.md has zero mention of: - Storage: ~/.wg/profiles/<name>.toml (one file per named profile) - Active pointer: ~/.wg/active-profile (one-line file; absent = no profile active) - wg profile use <name> — canonical activation verb (hot-reloads daemon via IpcRequest::Reconfigure) - wg profile set <name> — deprecated alias for 'use' (label says so in CLI) - wg profile create / edit / delete / diff / init-starters — new command surface - Starter profiles: 'claude', 'codex', 'nex' (written by wg profile init-starters; baked into binary) - Legacy wgnext name: ~/wg/profiles/wgnext.toml auto-migrated to nex.toml on next init-starters run; still loads with deprecation hint - Profile allowlist: only agent.model, dispatcher.model, [tiers], [models.*], [[llm_endpoints.endpoints]], description allowed; unknown keys cause parse error - Resolution order: named profile overlay is applied AFTER global+local merge, but project-local config wins (profile only fills keys not set by either config file) - Section §1 scope table: no row for named profiles (G-only, never written by wg config init) - Section §2: no mention of profile as a new config resolution layer - Sections §4.4/§4.5 (wg setup wireframes): no mention of profile management or wg profile init-starters --- MISSING: Secret Backend System (entire feature absent) --- Implemented in: 6f4c98d1c (implement-wg-secret, 2026-04-28), e87d384f9 (fix-wg-secret, 2026-04-29). config-ux-design.md has zero mention of: - wg secret set/get/list/rm/check/backend — new credential management command - api_key_ref field in [[llm_endpoints.endpoints]] — new preferred field, replaces deprecated api_key_env - Backend types: keyring (OS native, default; falls back to keystore on headless Linux), keystore (~/.wg/keystore/, 0600 perms), plaintext (~/.wg/secrets/, requires allow_plaintext=true) - Passthrough URI schemes: op://<path> (1Password), pass:<path> (pass CLI), env:<VAR> (env forwarding), literal:<value> (test only, warns loudly) - [secrets] config section: allow_plaintext (bool, default false), default_backend (keyring/keystore/plaintext, default keyring) - wg secret backend show — shows which backends are active and reachable - wg secret backend set — sets the default backend for new 'wg secret set' calls - Section §1 scope table: no row for [secrets] (G-only; allow_plaintext + default_backend are per-user security preference) --- MISSING: wg migrate secrets command --- Implemented in: 6f4c98d1c. Not mentioned in §6 migration section. - wg migrate secrets [--global|--local] [--dry-run] [--no-copy] - Walks configs with api_key_env entries and migrates them to api_key_ref = 'keyring:<name>', prompting before each change - --dry-run: report what would change without writing - --no-copy: rewrite config refs but don't copy env var values into keyring --- STALE: §3.2 OpenRouter example uses deprecated api_key_env --- Currently (line 108): api_key_env = 'OPENROUTER_API_KEY' Should be: api_key_ref = 'keyring:openrouter-api-key' (preferred for new configs; api_key_env is now deprecated in favor of api_key_ref) Also: wg config init --route openrouter STILL generates api_key_env (src/commands/config_cmd.rs line 533) — this is a code/doc inconsistency. The doc says init output is byte-deterministic and matches §3.2 example (§5.2). Either code should be updated to generate api_key_ref, or example should be marked as 'pre-secret-backend canonical form'. --- STALE: §3.2 OpenRouter model strings out of date --- Line 97: model = 'openrouter:anthropic/claude-opus-4-6' → should be claude-opus-4-7 (src/config_defaults.rs:202) Line 100: fast = 'openrouter:anthropic/claude-haiku-4' → should be claude-haiku-4-5 (src/config_defaults.rs:200) Line 101: standard = 'openrouter:anthropic/claude-sonnet-4-6' — correct (src/config_defaults.rs:201) Line 102: premium = 'openrouter:anthropic/claude-opus-4-6' → should be claude-opus-4-7 Line 213 (TUI wireframe): 'openrouter:anthropic/claude-opus-4-6' → claude-opus-4-7 Note: §3.2b codex section was updated by agent-1030 and appears correct. --- INCONSISTENT: §5.2 claims init output byte-matches §3.2 but they diverge --- §5.2 says: 'For wg config init --global --route openrouter: §3.2 above. The output is byte-for-byte the example.' Actual wg config init --route openrouter generates: claude-opus-4-7, claude-haiku-4-5, api_key_env (not api_key_ref). §3.2 shows: claude-opus-4-6, claude-haiku-4, api_key_env. Cross-file note: Inconsistent with docs/design-named-profiles.md §7.2 which cross-checks against 'docs/config-ux-design.md §3.2b'. --- STALE: §2 item 2 — Config::global_dir() fix described as future work, but already shipped --- The doc says 'Fix Config::global_dir() to mirror main.rs::resolve_workgraph_dir' (§2 item 2) and 'Stale alert' in config-canonical.md §1. This was implemented (src/config.rs:3851-3865 now prefers ~/.wg over ~/.workgraph). The doc still frames this as pending work. --- STALE: §2 item 3 — serde(alias) described as needed, but already shipped --- The doc says to 'add serde(alias = chat_agent) on coordinator_agent, serde(alias = max_chats) on max_coordinators' (§2 item 3). This was implemented: src/config.rs:2994-2995, 3031-3032. The doc still frames this as pending implementation. --- INCONSISTENT: config-canonical.md §1 says 'there is NO chat_agent alias', but there is one now --- config-ux-design.md §2 item 3 cites audit §1 'Special merge rules — Unknown keys are silently dropped.' config-canonical.md §1 says 'NOTE: there is NO chat_agent alias.' The alias now exists (src/config.rs:2994). Note: config-canonical.md is a separate file from this audit scope, but config-ux-design.md cites it — the citing doc's statement 'add serde(alias) ... Reason: audit §3 ...' now describes completed work. === VALIDATION === - [x] Baseline commit identified: a08033b9f (2026-04-27, human-authored, no agent ID in message) - [x] Delta list posted via wg log with structured entries - [x] No source/doc modifications — audit only
• 2026-04-30T02:20:57.205015600+00:00 Task pending eval (agent reported done; awaiting `.evaluate-*` to score)
• 2026-04-30T02:23:26.415970778+00:00 PendingEval → Done (evaluator passed; downstream unblocks)