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).