refactor(compile): consolidate reviewed bot improvements

docs/mcp-author.md

@@ -17,13 +17,13 @@ workflows.
 | --- | --- | --- |
 | `inspect_workflow` | Build and return the public `PipelineSummary`. | `{ "source_path": "agents/example.md" }` |
 | `graph_summary` | Return the resolved `GraphSummary`. | `{ "source_path": "agents/example.md" }` |
-| `graph_dump` | Render the graph as text or Graphviz DOT. | `{ "source_path": "...", "format": "text" \| "dot" }` |
+| `graph_dump` | Render the graph as text, structured `GraphSummary` JSON, or Graphviz DOT. | `{ "source_path": "...", "format": "text" \| "json" \| "dot" }` |
 | `step_dependencies` | Traverse dependencies for a step or job id. | `{ "source_path": "...", "step_id": "Agent", "direction": "upstream" \| "downstream" }` |
 | `step_outputs` | List declared outputs and consumers. | `{ "source_path": "...", "producer": null, "consumer": null }` |
 | `trace_failure` | Trace a build's failed-job chain using audit data plus any local IR graph. | `{ "build_id_or_url": "123", "step": null, "org": null, "project": null, "pat": null }` |
 | `whatif` | Classify downstream jobs if a step or job fails. | `{ "source_path": "...", "failing_id": "Agent" }` |
 | `lint_workflow` | Run structural lint checks. | `{ "source_path": "agents/example.md" }` |
-| `catalog` | List safe-outputs, runtimes, tools, engines, models, and pinned versions. | `{ "kind": "safe-outputs" }` |
+| `catalog` | List safe-outputs, runtimes, tools, engines, models, pinned versions, and the `ado-proxy` policy catalog. | `{ "kind": "safe-outputs" }` |
 | `audit_build` | Download and analyze a build; same shape as `ado-aw audit --json`. | `{ "build_id_or_url": "123", "org": null, "project": null, "pat": null, "artifacts": null, "no_cache": false }` |
 
 ## Trust model

docs/network.md

@@ -131,7 +131,7 @@ not found" failure mode.
   agent on that runner needs `az`) or to install `azure-cli` on the
   runner image.
 
-See [`docs/tools.md`](tools.md#built-in-clis) for the agent-facing
+See [`docs/tools.md`](tools.md#host-provided-clis) for the agent-facing
 contract (auth scope, available subcommands).
 
 ## Renewable Azure authentication for MCP servers

docs/parameters.md

@@ -43,3 +43,12 @@ When `tools.cache-memory` is configured, the compiler automatically injects a `c
 - Creates an empty memory directory so the agent starts fresh
 
 If you define your own `clearMemory` parameter in the front matter, the auto-injected one is suppressed — your definition takes precedence.
+
+### Reserved names on `target: job` / `target: stage`
+
+On these two targets the compiler auto-injects its own `dependsOn` and
+`condition` template parameters (see [`docs/targets.md`](targets.md)) so
+callers can wire in external ordering at the `template:` invocation site.
+Declaring a front-matter `parameters:` entry named `dependsOn` or `condition`
+on `target: job` or `target: stage` is therefore a **compile-time error** —
+rename the parameter or switch targets.

docs/safe-outputs.md

@@ -1175,7 +1175,7 @@ input to `create-pull-request`.
 - `work-items` - List of work item IDs to link
 - `fallback-record-branch` - When PR creation fails, record the pushed branch name and target branch in the failure response so operators can manually create the PR (default: true)
 - `max` - Maximum number of create-pull-request outputs allowed per run (default: 1)
-- `include-stats` - Whether to append agent execution stats (token usage, duration, model) to the PR description (default: true)
+- `include-stats` - Whether to append agent execution stats (AI credits when available, duration, model, tool calls) to the PR description (default: true)
 
 **Multi-repository support:**
 When `workspace: root` and multiple repositories are checked out, agents can create PRs for any allowed repository:

docs/targets.md

@@ -97,6 +97,9 @@ stages:
 - The `condition` parameter is ANDed into the agent job's existing internal
   condition (PR gate, pipeline gate, etc.). Empty default preserves ADO's
   native `succeeded()` behaviour.
+- `dependsOn` and `condition` are reserved parameter names on `target: job`.
+  Declaring a front-matter `parameters:` entry with either name is a
+  **compile-time error** — rename the parameter or drop `target: job`.
 - Triggers (`on:`) are ignored with a warning (the parent pipeline controls triggers).
 - If the agent declares additional repositories via `repos:`, add them to the
   parent pipeline's `resources:` block (documented in the generated file header).
@@ -136,6 +139,9 @@ stages:
   behaviour.
 - The `dependsOn` parameter is typed `object`, matching ADO's native
   `dependsOn:` semantics (accepts a single string or a list).
+- `dependsOn` and `condition` are reserved parameter names on `target: stage`,
+  same as `target: job` — a front-matter `parameters:` entry with either name
+  is a **compile-time error**.
 - Same 3-job chain, job-name prefixing, and pool handling as `target: job`.
 - Triggers (`on:`) are ignored with a warning.
 - If the agent declares additional repositories via `repos:`, add them to the

docs/tools.md

@@ -161,10 +161,10 @@ subcommands. When configured, use `tools.azure-devops` for authenticated ADO
 reads. Do not run `az login` or inject Azure credentials into the Agent
 sandbox; use SafeOutputs or request a supported tool instead.
 
-Detection, mounting, and prompt-advisory gating are covered by unit tests in
-`src/compile/extensions/azure_cli.rs` and `tests/compiler_tests.rs`; there is
-no dedicated agentic smoke pipeline exercising binary/subcommand availability
-end-to-end.
+A smoke pipeline at
+[`tests/smoke/ado-proxy.md`](../tests/smoke/ado-proxy.md)
+exercises the wrapped `az` path (`az devops`, `az rest`) against the
+credential-isolated proxy without claiming unauthenticated direct ADO access.
 
 ### GitHub CLI (`gh`)