[docs-audit] Weekly documentation audit — 2026-05-19

[github-actions]

Documentation Audit Report — 2026-05-19

Critical (documentation is wrong or references removed code)

• README.md and .devcontainer/README.md (recurring from #99, #96) — Both files instruct users to run cp Config/ai-config.local.env.example Config/ai-config.local.env, but Config/ai-config.local.env.example does not exist. The actual template is Config/ai-config.env.example.

  Fix: Replace ai-config.local.env.example with ai-config.env.example in README.md (line 170) and in .devcontainer/README.md (Quick Start section).

• docs/speed-profiles.md (recurring from #99, #96) — The "Environment Variable Overrides" table and all examples document CODEX_* variable names (e.g., CODEX_LOW_REASONING_EFFORT, CODEX_MAX_OUTPUT_TOKENS). Program.cs → OverrideSettingsFromEnvironment() reads AI_* names (AI_LOW_REASONING_EFFORT, AI_MAX_OUTPUT_TOKENS, etc.) and silently ignores CODEX_*. Simultaneously, doctor.sh → select_speed_profile() still exports CODEX_*, so the speed profile selection has no runtime effect.

  Fix: Update docs/speed-profiles.md to document AI_* variable names. Update doctor.sh → select_speed_profile() to export AI_* variables.

• docs/REVERSE_ENGINEERING_ARCHITECTURE.md (recurring from #99, #96) — The Detailed Architecture diagram contains SK[Semantic Kernel] as the AI service layer. The project migrated to Microsoft Agent Framework (Microsoft.Agents.AI.*) and no longer uses Semantic Kernel.

  Fix: Replace SK[Semantic Kernel] with AgentFW[Microsoft Agent Framework] in the Mermaid diagram and remove any remaining Semantic Kernel references.

Missing (undocumented user-facing features)

• docs/REVERSE_ENGINEERING_ARCHITECTURE.md (recurring from #99, #96) — The DependencyMapperAgent and its dependency mapping step are absent from all diagrams and the Agent Responsibilities section. This step produces dependency-map.json and dependency-diagram.md.

  Fix: Add DependencyMapperAgent to the Agent Responsibilities diagram and insert a Dependency Mapping step in the flow and sequence diagrams.

• README.md — GITHUB_HOST env var for GitHubCopilotSDK (recurring from #99, tracked in #98) — The Supported AI Providers table lists GitHubCopilotSDK but does not document the GITHUB_HOST environment variable for GitHub Data Residency host selection, which is present in doctor.sh (line 17).

  Fix: See #98 for details.

Stale (documentation references that may be outdated)

• docs/REVERSE_ENGINEERING_ARCHITECTURE.md (Last updated: 2026-02-23) (recurring from #99, #96) — Predates v2.5.0 (2026-03-05) and v3.0.0 (2026-03-17). Config snippets show a single-provider AISettings block and reference RateLimitSettings that does not match the current schema in appsettings.json.

  Fix: Update config snippets, diagrams, and descriptions against the current v3.x codebase. Update the "Last updated" date.

Structural (guideline compliance issues)

• docs/REVERSE_ENGINEERING_ARCHITECTURE.md (recurring from #99, #96) — Filename uses SCREAMING_SNAKE_CASE, inconsistent with the kebab-case convention used by all other files in docs/.

  Fix: Rename to reverse-engineering-architecture.md and update the reference in README.md.

---

Summary

	Count
Total documentation files audited	10
Critical issues	3
Missing documentation	2
Stale documentation	1
Structural issues	1
Previously reported issues resolved since last audit (#99, 2026-05-12)	0
New issues since last audit	0

All 7 issues are recurring — none have been addressed since first reported in #96.

Generated by Documentation Full Audit