docs(site): fix job/stage targets — dependsOn and condition must be parameters (#830)

Author: github-actions[bot]

site/src/content/docs/reference/targets.mdx

@@ -12,7 +12,7 @@ The `target` field in the front matter determines the output format and executio
 ### `standalone` (default)
 
 Generates a self-contained Azure DevOps pipeline with:
-- Full 3-job pipeline: `Agent` -> `Detection` -> `SafeOutputs`
+- Full 3-job pipeline: `Agent` → `Detection` → `SafeOutputs`
 - AWF (Agentic Workflow Firewall) L7 domain whitelisting via Squid proxy + Docker
 - MCP Gateway (MCPG) for MCP routing with SafeOutputs HTTP backend
 - Setup/teardown job support
@@ -25,7 +25,7 @@ This is the recommended target for maximum flexibility and security controls.
 Generates a pipeline that extends the 1ES Unofficial Pipeline Template:
 - Uses `templateContext.type: buildJob` with Copilot CLI + AWF + MCPG (same execution model as standalone)
 - Integrates with 1ES SDL scanning and compliance tools
-- Full 3-job pipeline: Agent -> Detection -> SafeOutputs
+- Full 3-job pipeline: Agent → Detection → SafeOutputs
 - Requires 1ES Pipeline Templates repository access
 
 Example:
@@ -38,14 +38,14 @@ When using `target: 1es`, the pipeline will extend `1es/1ES.Unofficial.PipelineT
 ### `job`
 
 Generates a **job-level ADO YAML template** with `jobs:` at root. This is a
-reusable template that can be included in an existing pipeline -- it does not
+reusable template that can be included in an existing pipeline — it does not
 generate a complete pipeline.
 
-The output contains the same 3-job chain (Agent -> Detection -> SafeOutputs) as
+The output contains the same 3-job chain (Agent → Detection → SafeOutputs) as
 `standalone`, with:
 - Job names prefixed with the agent name for uniqueness (e.g., `DailyReview_Agent`)
 - No triggers, pipeline name, or resource declarations (the parent pipeline owns those)
-- Pool baked in from the front matter `pool:` field
+- Pool baked in from the front matter `pool:` field (`vmImage` or `name`; defaults to `vmImage: ubuntu-22.04`)
 
 Example front matter:
 ```yaml
@@ -59,6 +59,9 @@ jobs:
   - job: Build
     steps: ...
   - template: agents/review.lock.yml
+    parameters:
+      dependsOn: [Build]              # list of upstream job names; omit for implicit dep on previous job
+      condition: succeeded('Build')   # optional; ANDed into the agent job's internal condition
 ```
 
 #### Usage inside a user-defined stage
@@ -73,6 +76,12 @@ stages:
       - template: agents/review.lock.yml
 ```
 
+#### Notes
+
+- ADO's [`jobs.template`](https://learn.microsoft.com/azure/devops/pipelines/yaml-schema/jobs-template) schema only allows `template:` and `parameters:` at the call site. `dependsOn:` and `condition:` as bare keys on the `- template:` line are rejected; the compiled template surfaces them as parameters and applies them to the agent job internally.
+- When the agent has a Setup job (e.g. PR or pipeline filters), the `dependsOn` parameter **must** be a YAML list — the template uses `${{ each }}` to merge `Setup` with the caller's deps, and `${{ each }}` requires an iterable. For agents without a Setup job, either a string or a list works.
+- The `condition` parameter is ANDed into the agent job's existing internal condition. Omit it to preserve ADO's native `succeeded()` behaviour.
+
 ### `stage`
 
 Generates a **stage-level ADO YAML template** with `stages:` at root. This
@@ -91,12 +100,16 @@ stages:
   - stage: Build
     jobs: ...
   - template: agents/review.lock.yml
-    dependsOn: Build
-    condition: succeeded()
+    parameters:
+      dependsOn: Build              # or [Build, Test]; omit for implicit dep on previous stage
+      condition: succeeded('Build') # optional; omit for ADO's default succeeded()
 ```
 
-ADO natively supports `dependsOn` and `condition` at the template call site --
-no template parameters are needed for stage ordering.
+#### Notes
+
+- ADO's [`stages.template`](https://learn.microsoft.com/azure/devops/pipelines/yaml-schema/stages-template) schema only allows `template:` and `parameters:` at the call site. `dependsOn:` and `condition:` as bare top-level keys on the `- template:` line are **rejected** by the YAML parser. The compiled template surfaces them as parameters and applies them to the inner stage block.
+- The `dependsOn` parameter accepts a single string or a list (matching ADO's native `dependsOn:` semantics).
+- Same 3-job chain, job-name prefixing, and pool handling as `target: job`.
 
 ---
 
@@ -109,3 +122,7 @@ If your agent declares additional repositories via `repos:`, you must manually a
 </Aside>
 
 Both `job` and `stage` targets produce templates with the same 3-job execution chain (Agent → Detection → SafeOutputs), job-name prefixing for uniqueness, and pool configuration baked in from the `pool:` front-matter field. The difference is only in the YAML wrapper: `jobs:` at root vs. `stages:` at root.
+
+<Aside type="caution" title="dependsOn and condition must be parameters">
+ADO's template call-site schema only allows `template:` and `parameters:` as top-level keys on a `- template:` entry. Bare `dependsOn:` and `condition:` keys on the `- template:` line are rejected by ADO. Always pass them through `parameters:` as shown in the usage examples above.
+</Aside>