[docs] Update documentation for features from 2025-11-26

docs/src/content/docs/reference/frontmatter.md

@@ -400,6 +400,32 @@ The agentic execution job automatically waits for all custom jobs to complete be
 
 Custom jobs can share data with the agentic execution through artifacts or job outputs.
 
+### Job Outputs
+
+Custom jobs can expose outputs that are accessible in the agentic execution prompt using `${{ needs.job-name.outputs.output-name }}` syntax:
+
+```yaml wrap
+jobs:
+  release:
+    needs: ["activation"]
+    runs-on: ubuntu-latest
+    outputs:
+      release_id: ${{ steps.get_release.outputs.release_id }}
+      version: ${{ steps.get_release.outputs.version }}
+    steps:
+      - id: get_release
+        run: |
+          echo "release_id=${{ github.event.release.id }}" >> $GITHUB_OUTPUT
+          echo "version=${{ github.event.release.tag_name }}" >> $GITHUB_OUTPUT
+---
+
+# Release Highlights Generator
+
+Generate release highlights for release ${{ needs.release.outputs.release_id }} (version ${{ needs.release.outputs.version }}).
+```
+
+Job outputs must be string values. Non-string outputs will trigger a warning during compilation.
+
 ## Cache Configuration (`cache:`)
 
 Cache configuration using standard GitHub Actions `actions/cache` syntax:

docs/src/content/docs/reference/imports.md

@@ -74,9 +74,9 @@ Only one agent file can be imported per workflow. See [Custom Agent Files](/gh-a
 
 ## Frontmatter Merging
 
-Imported files can only define `tools:`, `mcp-servers:`, and `services:` frontmatter (other fields trigger warnings). Agent files can also define `name` and `description`. These fields are merged with the main workflow's configuration.
+Imported files can define `tools:`, `mcp-servers:`, `services:`, and `safe-outputs:` frontmatter (other fields trigger warnings). Agent files can also define `name` and `description`. These fields are merged with the main workflow's configuration.
 
-### Example
+### Tools and MCP Servers
 
 ```aw wrap
 # Base workflow
@@ -100,6 +100,39 @@ mcp-servers:
 
 The imported MCP server configuration is merged into the final workflow, making it available to the AI engine.
 
+### Safe Outputs
+
+Safe output configurations (like `create-issue`, `add-comment`, etc.) and safe output jobs can be imported from shared workflows. If the same safe output type is defined in both the main workflow and an imported workflow, compilation fails with a conflict error.
+
+```aw wrap
+# shared-config.md
+---
+safe-outputs:
+  create-issue:
+    title-prefix: "[bot] "
+    labels: [automated]
+  allowed-domains:
+    - "api.example.com"
+  staged: true
+  jobs:
+    notify:
+      runs-on: ubuntu-latest
+      steps:
+        - run: echo "Notification sent"
+---
+```
+
+```aw wrap
+# main-workflow.md
+---
+on: issues
+imports:
+  - shared-config.md
+---
+```
+
+The main workflow inherits the `create-issue` configuration, allowed domains, staged setting, and the `notify` job from the imported file. Safe output meta fields (like `allowed-domains`, `staged`, `env`, `github-token`, `max-patch-size`, `runs-on`) from the main workflow take precedence over imported values.
+
 ## Related Documentation
 
 - [Packaging and Updating](/gh-aw/guides/packaging-imports/) - Complete guide to managing workflow imports

docs/src/content/docs/setup/cli.md

@@ -176,9 +176,13 @@ Show status of all workflows in the repository.
 
 ```bash wrap
 gh aw status                                # Show all workflow status
+gh aw status --ref main                     # Show status with latest run info for main branch
+gh aw status --json --ref feature-branch    # JSON output with run status for specific branch
 ```
 
-Lists all agentic workflows with their current state, enabled/disabled status, schedules, and configurations.
+Lists all agentic workflows with their current state, enabled/disabled status, schedules, and configurations. When `--ref` is specified, includes the latest run status and conclusion for each workflow on that branch or tag.
+
+**Options:** `--ref` (filter by branch or tag, shows latest run status and conclusion), `--json` (output in JSON format)
 
 #### `logs`
 
@@ -188,11 +192,12 @@ Download and analyze workflow execution logs. Downloads logs, analyzes tool usag
 gh aw logs                                 # Download logs for all workflows
 gh aw logs workflow-name                   # Download logs for specific workflow
 gh aw logs -c 10 --start-date -1w         # Filter by count and date
-gh aw logs --parse --json                 # Generate markdown + JSON output
+gh aw logs --ref main                      # Filter logs by branch or tag
+gh aw logs --ref v1.0.0 --parse --json    # Generate markdown + JSON output for specific tag
 gh aw logs workflow-name --repo owner/repo # Download logs from specific repository
 ```
 
-**Options:** `-c, --count N` (limit number of runs), `-e, --engine` (filter by AI engine like `-e copilot`), `--start-date` (filter runs from date like `--start-date -1w`), `--end-date` (filter runs until date like `--end-date -1d`), `--parse` (generate `log.md` and `firewall.md`), `--json` (output structured metrics), `--repo owner/repo` (download logs from specific repository)
+**Options:** `-c, --count N` (limit number of runs), `-e, --engine` (filter by AI engine like `-e copilot`), `--start-date` (filter runs from date like `--start-date -1w`), `--end-date` (filter runs until date like `--end-date -1d`), `--ref` (filter by branch or tag like `--ref main` or `--ref v1.0.0`), `--parse` (generate `log.md` and `firewall.md`), `--json` (output structured metrics), `--repo owner/repo` (download logs from specific repository)
 
 #### `audit`