docs: clarify safe-output tool names, add incident dedup patterns, expand visual-regression guidance

.github/aw/create-agentic-workflow.md

@@ -90,7 +90,35 @@ Compact scenario examples:
 - **Deployment incident triage**: use `deployment_status` for external provider failures and `workflow_run` for GitHub Actions failures, publish incident reports via `create-issue`, call `noop` when a failure self-recovers or is duplicate noise.
 - **Product/stakeholder digest**: use fuzzy `schedule` plus optional `workflow_dispatch`, publish digest with `create-issue`, call `noop` when there are no updates in the date window.
 
-### 2a. Backend review compact guidance
+### 2a. Incident workflow duplicate-detection guidance
+
+For `deployment_status` and `workflow_run` triggered incident workflows that create issues, prevent duplicate noise with these patterns:
+
+**Title-based deduplication** (simplest — skip when an open issue with the same title already exists):
+
+```yaml
+safe-outputs:
+  create-issue:
+    title-prefix: "[incident] "
+    deduplicate-by-title: true   # skip if open issue with same title exists (case-insensitive, full-title match including prefix; use integer N for fuzzy edit-distance matching)
+    expires: 3                   # auto-close after 3 days
+```
+
+**Rolling incident tracker** (replace previous open issue with each new failure):
+
+```yaml
+safe-outputs:
+  create-issue:
+    title-prefix: "[incident] "
+    close-older-issues: true     # close previous open issues from the same workflow before creating a new one
+    expires: 7
+```
+
+**Prompt-side deduplication check**: In the workflow prompt, tell the agent to search for open issues with the same title prefix before calling `create_issue`, and call `noop` referencing the existing issue number if a duplicate is found.
+
+> **When to use which**: `deduplicate-by-title: true` is a zero-token-cost guardrail. The prompt-side check is more flexible but consumes agent tokens. Combine both for defense-in-depth on high-volume triggers.
+
+### 2b. Backend review compact guidance
 
 For backend-focused PR automation (schema migrations and API compatibility):
 

.github/aw/safe-outputs-content.md

@@ -4,6 +4,35 @@ description: Safe-output reference for issue, discussion, comment, and pull requ
 
 # Safe Outputs: GitHub Content
 
+## Tool Naming Convention
+
+YAML configuration keys use **kebab-case**; the MCP tool names the agent calls use **snake_case**.
+
+| YAML key (`safe-outputs:`) | MCP tool name (agent calls) |
+|---|---|
+| `create-issue:` | `create_issue` |
+| `add-comment:` | `add_comment` |
+| `create-pull-request:` | `create_pull_request` |
+| `close-issue:` | `close_issue` |
+| `create-discussion:` | `create_discussion` |
+| `update-issue:` | `update_issue` |
+| `add-labels:` | `add_labels` |
+| `upload-artifact:` | `upload_artifact` |
+| `upload-asset:` | `upload_asset` |
+
+Custom `jobs:` and `actions:` entries follow the same rule: the key `send-notification:` becomes the MCP tool `send_notification`.
+
+## Comment vs Issue Pattern
+
+| Scenario | Use |
+|---|---|
+| Inline finding on the triggering PR or issue (e.g., PR review, per-run status) | `add-comment` |
+| Scheduled or incident report that needs follow-up and tracking across runs | `create-issue` |
+| Ephemeral status that should update in place (not accumulate) | `add-comment` + `hide-older-comments: true` |
+| Recurring digest with a single rolling thread | `create-issue` + `group-by-day: true` (or `create-discussion`) |
+
+Pair `create-issue` with `deduplicate-by-title: true` or `close-older-issues: true` to prevent stacking duplicate issues across runs.
+
 - `create-issue:` - Safe GitHub issue creation (bugs, features)
 
   ```yaml

.github/aw/visual-regression.md

@@ -36,6 +36,11 @@ tools:
 safe-outputs:
   add-comment:
     max: 1
+  upload-artifact:
+    max-uploads: 5
+    retention-days: 14
+    allowed-paths:
+      - "visual-regression-diffs/**"
 timeout-minutes: 30
 ---
 
@@ -46,16 +51,32 @@ Use filesystem-safe timestamps (no colons — colons break artifact uploads):
 
 If `/tmp/gh-aw/cache-memory/baselines/manifest.json` does not exist, copy screenshots there as new baselines and post: "Baselines initialized — N pages captured."
 
-Otherwise compare each screenshot to its baseline. Post a comment summarizing: pages unchanged / pages with diffs. If nothing changed, use the `noop` safe-output.
+Otherwise compare each screenshot to its baseline. Copy any diff images to `visual-regression-diffs/` (workspace-relative). Upload them using `upload_artifact` (name: `visual-regression-diffs-${{ github.run_id }}`). Post a comment summarizing: pages unchanged / pages with diffs, and link to the uploaded artifact when diffs exist. If nothing changed, use the `noop` safe-output.
 ```
 
+## Baseline Storage
+
+Baselines are stored in `cache-memory` under `/tmp/gh-aw/cache-memory/baselines/`. The key is scoped per base branch so `main` and `develop` maintain independent baseline sets.
+
+### Updating Baselines
+
+Add a companion `workflow_dispatch` workflow that captures fresh screenshots and writes them to `cache-memory` — using the same `key` pattern but with the target branch as an input. Run it on `main` after merging any PR that intentionally changes the UI.
+
+## Artifact Retention
+
+- Set `retention-days` to match your PR review cadence (14 days covers most review cycles).
+- Pair the `upload_artifact` call with an `add-comment` that links the artifact URL: `${{ steps.process_safe_outputs.outputs.upload_artifact_url }}`.
+- Use `upload-asset` instead of `upload-artifact` when diff images need stable embeddable URLs in the comment body.
+
 ## Key Design Decisions
 
 - **`cache-memory` key per base branch** — scopes baselines to `main`, `develop`, etc.
 - **`allowed_domains: [localhost, 127.0.0.1]`** — prevents SSRF; serve app locally
 - **`retention-days: 30`** — beyond the default 7-day cache expiry
 - **Filesystem-safe timestamps** — `YYYY-MM-DD-HH-MM-SS`; colons break artifact filenames
 - **Minimal permissions** — all PR writes go through `safe-outputs`
+- **`upload-artifact` for diffs** — run-scoped; expires after `retention-days`; use for downloadable diff archives
+- **`upload-asset` for embedded images** — persists to orphaned branch; use when the comment body must inline diff images
 
 ## Network-Minimization Reminders