docs: fix documentation drift — add inlined-imports field and runtime import guidance

README.md

@@ -251,9 +251,9 @@ the service connections. Approve the permissions and the pipeline is ready.
 | `post-steps` | list | — | Inline steps after agent runs |
 | `setup` | list | — | Separate job before agentic task |
 | `teardown` | list | — | Separate job after safe outputs |
-| `network` | object | — | Additional allowed/blocked hosts |
-| `inlined-imports` | boolean | `false` | When `true`, resolves all `{{#runtime-import …}}` markers at compile time; the generated YAML is self-contained but prompt-body edits require recompilation. See [runtime-imports.md](docs/runtime-imports.md). |
-| `env` | map | — | Workflow-level environment variables (reserved, not yet implemented) |
+| `network` | object | — | Additional allowed/blocked hosts |
+| `inlined-imports` | boolean | `false` | When `true`, resolves all `{{#runtime-import ...}}` markers at compile time; the generated YAML is self-contained but prompt-body edits require recompilation. See [runtime imports](docs/runtime-imports.md). |
+| `env` | map | — | Workflow-level environment variables (reserved, not yet implemented) |
 
 ### Markdown Body
 

prompts/create-ado-agentic-workflow.md

@@ -523,11 +523,12 @@ network:
   allowed:
     - "*.mycompany.com"
     - "api.external-service.com"
+    - python                    # ecosystem identifier — expands to all Python/PyPI domains
   blocked:
     - "evil.example.com"
 ```
 
-The built-in allowlist includes: Azure DevOps, GitHub, Microsoft identity, Azure services, Application Insights, and MCP-specific endpoints for each enabled server.
+`allowed` accepts raw domain patterns (wildcards supported) or ecosystem identifiers (`python`, `node`, `rust`, `dotnet`, `lean`) that expand to the full set of package registry domains for that ecosystem. The built-in allowlist includes: Azure DevOps, GitHub, Microsoft identity, Azure services, Application Insights, and MCP-specific endpoints for each enabled server.
 
 ### Step 15 — Parameters (optional)
 
@@ -563,16 +564,25 @@ Omit `parameters:` if no runtime configuration knobs are needed.
 
 ### Step 16 — Inlined Imports (advanced, optional)
 
-By default (`inlined-imports: false`), any `{{#runtime-import …}}` markers in the agent body — including the implicit marker that reloads the body itself — are resolved at **pipeline runtime**. This means editing the `.md` agent body does not require recompiling the `.lock.yml` pipeline.
+By default (`inlined-imports: false`), any `{{#runtime-import ...}}` markers in the agent body — including the implicit marker that reloads the body itself — are resolved at **pipeline runtime**. This means editing the `.md` agent body does not require recompiling the `.lock.yml` pipeline.
 
 Set `inlined-imports: true` only when you need a fully self-contained pipeline YAML (e.g., for auditing or air-gapped deployment):
 
 ```yaml
 inlined-imports: true
 ```
 
+**When to use each mode:**
+
+| Mode | Default | Prompt edits require recompile? | Use case |
+|------|---------|--------------------------------|----------|
+| `inlined-imports: false` | ✅ | No — edit and commit `.md` directly | Most workflows |
+| `inlined-imports: true` | | Yes — must run `ado-aw compile` | Immutable/audited prompts |
+
 **Trade-off**: with `inlined-imports: true`, every change to the agent instructions requires running `ado-aw compile` and committing the updated `.lock.yml`. Omit this field (or set it to `false`) for the typical edit-without-recompile workflow.
 
+You can also reference shared files from the agent body using `{{#runtime-import path/to/file.md}}` markers.
+
 ---
 
 ## Agent Instruction Body