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

## Documentation Audit Report — 2026-05-19

### Critical (documentation is wrong or references removed code)

- [ ] **`README.md` and `.devcontainer/README.md`** *(recurring from [#99](https://github.com/Azure-Samples/Legacy-Modernization-Agents/issues/99), [#96](https://github.com/Azure-Samples/Legacy-Modernization-Agents/issues/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](https://github.com/Azure-Samples/Legacy-Modernization-Agents/issues/99), [#96](https://github.com/Azure-Samples/Legacy-Modernization-Agents/issues/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](https://github.com/Azure-Samples/Legacy-Modernization-Agents/issues/99), [#96](https://github.com/Azure-Samples/Legacy-Modernization-Agents/issues/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](https://github.com/Azure-Samples/Legacy-Modernization-Agents/issues/99), [#96](https://github.com/Azure-Samples/Legacy-Modernization-Agents/issues/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](https://github.com/Azure-Samples/Legacy-Modernization-Agents/issues/99), tracked in [#98](https://github.com/Azure-Samples/Legacy-Modernization-Agents/issues/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](https://github.com/Azure-Samples/Legacy-Modernization-Agents/issues/98) for details.

### Stale (documentation references that may be outdated)

- [ ] **`docs/REVERSE_ENGINEERING_ARCHITECTURE.md`** (Last updated: 2026-02-23) *(recurring from [#99](https://github.com/Azure-Samples/Legacy-Modernization-Agents/issues/99), [#96](https://github.com/Azure-Samples/Legacy-Modernization-Agents/issues/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](https://github.com/Azure-Samples/Legacy-Modernization-Agents/issues/99), [#96](https://github.com/Azure-Samples/Legacy-Modernization-Agents/issues/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](https://github.com/Azure-Samples/Legacy-Modernization-Agents/issues/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](https://github.com/Azure-Samples/Legacy-Modernization-Agents/issues/96).

> Generated by [Documentation Full Audit](https://github.com/Azure-Samples/Legacy-Modernization-Agents/actions/runs/26114552137)

Start with README.md, .devcontainer/README.md, docs/speed-profiles.md, and docs/REVERSE_ENGINEERING_ARCHITECTURE.md, then compare the documented names and diagrams with Program.cs, doctor.sh, and appsettings.json. Update the seven reported documentation and structural issues, including the referenced GITHUB_HOST item, and verify that links, configuration examples, diagrams, and environment-variable names match the current codebase.

Written by the indexing model from the issue text.