From acf6a27e611a14079244adc8a07c0a6c7e12b28e Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Sat, 30 May 2026 20:52:59 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20fix=20documentation=20drift=20=E2=80=94?=
 =?UTF-8?q?=20env=20field=20status=20and=20export-gate-schema=20command?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixes identified in documentation freshness audit:

1. **docs/front-matter.md** — Removed incorrect RESERVED comment from
   env: field. The field is implemented (src/compile/types.rs:125-127)
   and has been available since early versions. Documentation incorrectly
   told users the feature was unavailable.

2. **docs/cli.md** — Documented export-gate-schema hidden build-time tool
   in a new 'Hidden Build-Time Tools' section. This command exists in
   src/main.rs:424-431 but was previously only mentioned in passing
   without proper introduction.

All other documentation checked and found accurate:
- CLI commands match src/main.rs Commands enum
- Template markers in docs/template-markers.md match all four template files
- Safe output tools are fully documented (24 tools in src/safeoutputs/)
- FrontMatter struct fields are documented across docs/front-matter.md
  and linked per-concept docs
- AGENTS.md architecture tree matches actual directory structure

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/cli.md          | 6 +++++-
 docs/front-matter.md | 4 ++--
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index 95c2f6c8..5b8dfbf5 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -117,7 +117,11 @@ Both flags route through `ado-aw`'s `discover_ado_aw_pipelines` machinery, which
   - `--timeout <secs>` - Hard cap on the polling loop when `--wait` is set (default 1800).
   - `--dry-run` - Print the planned `templateParameters` body without calling the ADO API.
 
-- `export-gate-schema` *(hidden; build-time tool)* - Export the gate spec JSON Schema used by the `scripts/ado-script` TypeScript workspace for type codegen. Outputs JSON to stdout or to a file.
+### Hidden Build-Time Tools
+
+These commands are not shown in `--help` but are available for contributors working on the ado-aw compiler itself:
+
+- `export-gate-schema` - Export the gate spec JSON Schema used by the `scripts/ado-script` TypeScript workspace for type codegen. Outputs JSON to stdout or to a file.
   - `--output, -o <path>` - Write the schema to a file instead of stdout. Parent directories are created automatically.
   - See [`docs/ado-script.md`](ado-script.md) for how this command fits into the ado-script build workflow (`cargo run -- export-gate-schema --output schema/gate-spec.schema.json`).
 
diff --git a/docs/front-matter.md b/docs/front-matter.md
index 8b63d634..e24e5081 100644
--- a/docs/front-matter.md
+++ b/docs/front-matter.md
@@ -57,8 +57,8 @@ runtimes:                      # optional runtime configuration (language enviro
   # dotnet:                    # Alternative object format (pin version, configure internal feed via nuget.config)
   #   version: "8.0.x"          # use "global.json" to pin from the repo's global.json
   #   feed-url: "https://pkgs.dev.azure.com/myorg/_packaging/myfeed/nuget/v3/index.json"
-# env:                          # RESERVED: workflow-level environment variables (not yet implemented)
-#   CUSTOM_VAR: "value"
+env:                          # workflow-level environment variables
+  CUSTOM_VAR: "value"
 # inlined-imports: false        # When true, resolve {{#runtime-import ...}} markers at compile time
 #                               # (default: false — markers are resolved at pipeline runtime, so
 #                               # prompt-body edits do not require recompilation).