docs(readme): fix accuracy drift and add documentation index#707
Merged
Conversation
Audit-driven README updates aligning the top-level README with the current codebase: - Quick Start agent example: align with the actual default Copilot model (claude-opus-4.7, see src/engine.rs::DEFAULT_COPILOT_MODEL) and the generic non-1ES default pool (�mImage: ubuntu-22.04, see src/compile/common.rs::DEFAULT_VM_IMAGE_POOL). The previous example showed a Microsoft-internal 1ES pool without `target: 1es`, which is confusing for a generic intro example. - Built-in Tools section: add �ash and �dit to the configuration example. They are listed in the front-matter table but were not exemplified, even though they are core tools in ToolsConfig. - Network Isolation: rewrite the `network.blocked` bullet to match actual behaviour from src/compile/common.rs (ecosystem identifiers *and* raw domain strings are both accepted; the exact-match note now applies specifically to raw domains). - CLI Reference: enumerate the three `secrets` subcommands (`set` / `list` / `delete`) and the project-scope discovery flags, matching the SecretsCmd enum in src/main.rs. - New `Documentation` section that indexes the per-concept reference pages under `docs/` (front-matter, engine, tools, runtimes, schedule-syntax, parameters, targets, safe-outputs, ado-aw-debug, cli, mcp, mcpg, network, template-markers, filter-ir, codemods, ado-script, extending, local-development). The previous README only linked to a single `docs/` page, making the rest of the documentation effectively invisible from the entry point. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Audit-driven README updates aligning the top-level
README.mdwith the current state of the codebase. No code changes — docs only.Findings & fixes
I diffed every concrete claim in the README against the codebase. The README is broadly accurate, but I found six issues worth correcting:
model: claude-sonnet-4.5claude-opus-4.7to match actual defaultsrc/engine.rs::DEFAULT_COPILOT_MODELpool: AZS-1ES-L-MMS-ubuntu-22.04(1ES pool) withouttarget: 1esvmImage: ubuntu-22.04to match the generic standalone defaultsrc/compile/common.rs::DEFAULT_VM_IMAGE_POOLbashandedit(they are in the front-matter table but never exemplified)src/compile/types.rs::ToolsConfignetwork.blockedbullet only describes wildcard exact-match behavioursrc/compile/common.rs:2757-2770,docs/network.md:96secretsas a single line; subcommands and project-scope flags are invisibleset/list/delete) and mention--all-repos/--sourcesrc/main.rs::SecretsCmddocs/reference is hidden — README only links to one docDocumentationindex section that mirrors the per-concept layout inAGENTS.mddocs/*.md(20 files)What I did not change
A few things looked suspicious initially but turned out to be correct or intentionally out of scope:
create-issueis debug-only (gated byado-aw-debug.create-issue) and intentionally absent from the public Safe Outputs table.env:in the front-matter table is still labelled "reserved, not yet implemented" — verified by grep: the field is parsed intoFrontMatterbut never read anywhere insrc/compile.configureis intentionally hidden in CLI--helpbut still mentioned in the README as deprecated; left as-is.export-gate-schema— that subcommand has#[command(hide = true)].Verification
main(commit2be2d2c8).docs/*.mdlinked in the new section exists.