Merge branch 'main' into prune-campaign-docs

Author: mnkiefer

docs/astro.config.mjs

@@ -167,8 +167,6 @@ export default defineConfig({
 						{ label: 'GitHub Actions Primer', link: '/guides/github-actions-primer/' },
 						{ label: 'Packaging & Distribution', link: '/guides/packaging-imports/' },
 						{ label: 'Using MCPs', link: '/guides/mcps/' },
-						{ label: 'Custom Safe Outputs', link: '/guides/custom-safe-outputs/' },
-						{ label: 'Threat Detection', link: '/guides/threat-detection/' },
 						{ label: 'Web Search', link: '/guides/web-search/' },
 						{ label: 'Ephemerals', link: '/guides/ephemerals/' },
 					],
@@ -205,7 +203,8 @@ export default defineConfig({
 						{ label: 'Tools', link: '/reference/tools/' },
 						{ label: 'Safe Outputs', link: '/reference/safe-outputs/' },
 						{ label: 'Safe Inputs', link: '/reference/safe-inputs/' },
-						{ label: 'Custom Safe Outputs', link: '/guides/custom-safe-outputs/' },
+						{ label: 'Custom Safe Outputs', link: '/reference/custom-safe-outputs/' },
+						{ label: 'Threat Detection', link: '/reference/threat-detection/' },
 						{ label: 'Imports', link: '/reference/imports/' },
 						{ label: 'Templating', link: '/reference/templating/' },
 						{ label: 'Network Access', link: '/reference/network/' },

docs/src/content/docs/guides/deterministic-agentic-patterns.md

@@ -188,7 +188,7 @@ Reference in prompts: "Analyze issues in `/tmp/gh-aw/agent/issues.json` and PRs
 
 ## Related Documentation
 
-- [Custom Safe Outputs](/gh-aw/guides/custom-safe-outputs/) - Custom post-processing jobs
+- [Custom Safe Outputs](/gh-aw/reference/custom-safe-outputs/) - Custom post-processing jobs
 - [Frontmatter Reference](/gh-aw/reference/frontmatter/) - Configuration options
 - [Compilation Process](/gh-aw/reference/compilation-process/) - How jobs are orchestrated
 - [Imports](/gh-aw/reference/imports/) - Sharing configurations across workflows

docs/src/content/docs/guides/ephemerals.md

@@ -172,36 +172,6 @@ See [Safe Outputs Reference](/gh-aw/reference/safe-outputs/#hide-older-comments)
 
 Run agentic workflows from a separate "side" repository that targets your main codebase. This isolates AI-generated issues, comments, and workflow runs from your main repository, keeping automation infrastructure separate from production code.
 
-```yaml wrap
-safe-outputs:
-  github-token: ${{ secrets.MAIN_REPO_PAT }}
-  create-issue:
-    target-repo: "my-org/main-repo"
-    title-prefix: "[automation] "
-    labels: [automation, ai-generated]
-```
-
-**Key benefits**:
-- **Zero friction** - No changes needed to main repository
-- **Clean separation** - AI-generated issues stay separate from organic development
-- **Private workflows** - Store sensitive automation logic in private repository
-- **Safe experimentation** - Test workflows without affecting production
-- **Centralized automation** - Manage workflows for multiple repositories
-
-**Architecture**:
-```text
-┌─────────────────┐          ┌──────────────────┐
-│  Side Repo      │          │  Main Repo       │
-│  (workflows)    │ ────────>│  (target code)   │
-│                 │   Uses   │                  │
-│  - automation/  │   PAT    │  - src/          │
-│  - .github/     │          │  - tests/        │
-│    workflows/   │          │  - docs/         │
-└─────────────────┘          └──────────────────┘
-```
-
-The workflows run in GitHub Actions on the side repository but perform operations (create issues, PRs, comments) on the main repository using cross-repository authentication.
-
 See [SideRepoOps Guide](/gh-aw/guides/siderepoops/) for complete setup and usage documentation.
 
 ### Allowed GitHub References
@@ -216,6 +186,7 @@ safe-outputs:
 ```
 
 **Configuration options**:
+
 - `[]` — Escape all references (prevents all timeline items)
 - `["repo"]` — Allow only the target repository's references
 - `["repo", "owner/other-repo"]` — Allow specific repositories
@@ -224,12 +195,14 @@ safe-outputs:
 **How it works**: References like `#123` become `` `#123` `` and `other/repo#456` becomes `` `other/repo#456` ``, preventing timeline clutter while preserving the information.
 
 **Use cases**:
+
 - **SideRepoOps**: Prevent automation from cluttering main repository timeline
 - **Cross-repository operations**: Avoid unwanted cross-references
 - **Clean automation**: Maintain readable issue/PR timelines
 - **Reporting workflows**: Share information without creating link noise
 
 **Example with SideRepoOps**:
+
 ```yaml wrap
 safe-outputs:
   github-token: ${{ secrets.MAIN_REPO_PAT }}
@@ -266,6 +239,7 @@ safe-outputs:
 | **Timeline noise** | Can clutter project tracking | Separate from development work |
 
 **Use cases for ephemeral discussions**:
+
 - Weekly status reports
 - Periodic analysis results
 - Temporary announcements
@@ -274,6 +248,7 @@ safe-outputs:
 - Community updates
 
 **Combining features**:
+
 ```yaml wrap
 safe-outputs:
   create-discussion:
@@ -285,107 +260,12 @@ safe-outputs:
 ```
 
 This configuration ensures:
+
 1. Only the latest weekly status discussion is open
 2. Previous reports are closed when new ones are created
 3. All discussions auto-close after 14 days
 4. The "Status Updates" category stays clean and focused
 
-## Best Practices
-
-### Combining Expiration Features
-
-Use multiple expiration features together for comprehensive cleanup:
-
-```yaml wrap
-on: weekly on monday
-  stop-after: "+30d"  # Stop workflow after 30 days
-
-safe-outputs:
-  create-discussion:
-    title-prefix: "[experiment]"
-    expires: 7  # Close discussions after 7 days
-    close-older-discussions: true  # Close older when creating new
-  add-comment:
-    hide-older-comments: true  # Minimize old status updates
-```
-
-This ensures the workflow stops after 30 days, created discussions expire after 7 days, and older discussions/comments are cleaned up automatically.
-
-### Labeling Ephemeral Content
-
-Use consistent labels to identify and track ephemeral content:
-
-```yaml wrap
-safe-outputs:
-  create-issue:
-    expires: 7
-    labels: [ephemeral, automation, expires-7d]
-```
-
-This makes it easy to:
-- Identify ephemeral content at a glance
-- Filter by expiration timeframe
-- Audit what content will expire soon
-- Track automation-generated content
-
-### SideRepoOps with Reference Escaping
-
-When using SideRepoOps, always configure `allowed-github-references` to prevent timeline noise:
-
-```yaml wrap
-safe-outputs:
-  github-token: ${{ secrets.MAIN_REPO_PAT }}
-  allowed-github-references: []  # Escape all references
-  create-issue:
-    target-repo: "my-org/main-repo"
-    expires: 7  # Auto-close after 7 days
-    labels: [automation, ephemeral]
-```
-
-This combination ensures:
-- Issues are created in the main repo but tracked separately
-- No cross-references clutter the main repo timeline
-- Content auto-expires after 7 days
-- Clear labeling identifies automated content
-
-### Status Update Workflows
-
-For workflows that post repeated status updates, use comment hiding:
-
-```yaml wrap
-safe-outputs:
-  add-comment:
-    hide-older-comments: true
-    allowed-reasons: [outdated, resolved]
-```
-
-This ensures:
-- Only the latest status is prominently visible
-- Historical status updates are preserved but minimized
-- Timeline stays clean and focused
-- Multiple status reasons available (outdated, resolved)
-
-### Maintenance Workflow Monitoring
-
-The auto-generated `agentics-maintenance.yml` workflow handles expiration. Monitor its runs to ensure proper cleanup:
-
-```bash
-# View maintenance workflow runs
-gh run list --workflow=agentics-maintenance.yml
-
-# Check for failures
-gh run list --workflow=agentics-maintenance.yml --status=failure
-
-# View a specific run
-gh run view RUN_ID
-```
-
-If expiration isn't working as expected:
-- Verify the maintenance workflow is enabled
-- Check workflow permissions (needs `issues: write` or `discussions: write`)
-- Review failed runs for permission errors
-- Ensure PAT tokens have appropriate scopes for cross-repository operations
-
 ## Related Documentation
 
 - [Triggers Reference](/gh-aw/reference/triggers/) - Complete trigger configuration including `stop-after`

docs/src/content/docs/guides/memoryops.md

@@ -295,5 +295,5 @@ echo '{"user": "alice", "email": "alice@example.com"}' > users.json
 
 - [MCP Servers](/gh-aw/guides/mcps/) - Memory MCP server configuration
 - [Deterministic Patterns](/gh-aw/guides/deterministic-agentic-patterns/) - Data preprocessing
-- [Safe Outputs](/gh-aw/guides/custom-safe-outputs/) - Storing workflow outputs
+- [Safe Outputs](/gh-aw/reference/custom-safe-outputs/) - Storing workflow outputs
 - [Frontmatter Reference](/gh-aw/reference/frontmatter/) - Configuration options

docs/src/content/docs/introduction/architecture.mdx

@@ -785,7 +785,7 @@ gh aw status
 
 ## Related Documentation
 
-- [Threat Detection Guide](/gh-aw/guides/threat-detection/) - Configuring threat analysis
+- [Threat Detection Guide](/gh-aw/reference/threat-detection/) - Configuring threat analysis
 - [Network Permissions](/gh-aw/reference/network/) - Network access control
 - [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Output processing configuration
 - [AI Engines](/gh-aw/reference/engines/) - Engine-specific security features

…ntent/docs/guides/custom-safe-outputs.md …nt/docs/reference/custom-safe-outputs.mddocs/src/content/docs/guides/custom-safe-outputs.md renamed to docs/src/content/docs/reference/custom-safe-outputs.md docs/src/content/docs/guides/custom-safe-outputs.md renamed to docs/src/content/docs/reference/custom-safe-outputs.md

@@ -363,4 +363,4 @@ Tools provide secret isolation (only specified env vars), process isolation (sep
 - [Imports](/gh-aw/reference/imports/) - Importing shared workflows
 - [Safe Outputs](/gh-aw/reference/safe-outputs/) - Automated post-workflow actions
 - [MCPs](/gh-aw/guides/mcps/) - External MCP server integration
-- [Custom Safe Output Jobs](/gh-aw/guides/custom-safe-outputs/) - Post-workflow custom jobs
+- [Custom Safe Output Jobs](/gh-aw/reference/custom-safe-outputs/) - Post-workflow custom jobs

docs/src/content/docs/reference/safe-inputs.md

@@ -75,11 +75,11 @@ The agent requests issue creation; a separate job with `issues: write` creates i
 - [**Missing Data**](#missing-data-reporting-missing-data) (`missing-data`) — Report missing data required to achieve goals (max: unlimited, same-repo only)
 
 > [!TIP]
-> Custom safe output types: [Custom Safe Output Jobs](/gh-aw/guides/custom-safe-outputs/). See [Deterministic & Agentic Patterns](/gh-aw/guides/deterministic-agentic-patterns/) for combining computation and AI reasoning.
+> Custom safe output types: [Custom Safe Output Jobs](/gh-aw/reference/custom-safe-outputs/). See [Deterministic & Agentic Patterns](/gh-aw/guides/deterministic-agentic-patterns/) for combining computation and AI reasoning.
 
 ### Custom Safe Output Jobs (`jobs:`)
 
-Create custom post-processing jobs registered as Model Context Protocol (MCP) tools. Support standard GitHub Actions properties and auto-access agent output via `$GH_AW_AGENT_OUTPUT`. See [Custom Safe Output Jobs](/gh-aw/guides/custom-safe-outputs/).
+Create custom post-processing jobs registered as Model Context Protocol (MCP) tools. Support standard GitHub Actions properties and auto-access agent output via `$GH_AW_AGENT_OUTPUT`. See [Custom Safe Output Jobs](/gh-aw/reference/custom-safe-outputs/).
 
 > [!NOTE]
 > **Internal Implementation**: Custom safe output jobs are internally referred to as "safe-jobs" in the compiler code (`pkg/workflow/safe_jobs.go`), but they are user-facing only through the `safe-outputs.jobs:` configuration. The top-level `safe-jobs:` key is deprecated and not supported.
@@ -1316,7 +1316,7 @@ Specify custom runner for safe output jobs (default: `ubuntu-slim`): `runs-on: u
 
 ## Threat Detection
 
-Auto-enabled. Analyzes output for prompt injection, secret leaks, malicious patches. See [Threat Detection Guide](/gh-aw/guides/threat-detection/).
+Auto-enabled. Analyzes output for prompt injection, secret leaks, malicious patches. See [Threat Detection Guide](/gh-aw/reference/threat-detection/).
 
 ## Projects, Monitoring, and Orchestration Patterns
 
@@ -1352,7 +1352,7 @@ safe-outputs:
 
 ## Related Documentation
 
-- [Threat Detection Guide](/gh-aw/guides/threat-detection/) - Complete threat detection documentation and examples
+- [Threat Detection Guide](/gh-aw/reference/threat-detection/) - Complete threat detection documentation and examples
 - [Frontmatter](/gh-aw/reference/frontmatter/) - All configuration options for workflows
 - [Workflow Structure](/gh-aw/reference/workflow-structure/) - Directory layout and organization
 - [Command Triggers](/gh-aw/reference/command-triggers/) - Special /my-bot triggers and context text

docs/src/content/docs/reference/safe-outputs.md

@@ -2,7 +2,7 @@
 title: Threat Detection
 description: Configure automated threat detection to analyze agent output and code changes for security issues before they are applied.
 sidebar:
-  order: 14
+  order: 40
 ---
 
 GitHub Agentic Workflows includes automatic threat detection to analyze agent output and code changes for potential security issues before they are applied. When safe outputs are configured, a threat detection job automatically runs to identify prompt injection attempts, secret leaks, and malicious code patches.
@@ -308,5 +308,5 @@ If the detection process itself fails (e.g., network issues, tool errors), the w
 
 - [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Complete safe outputs configuration
 - [Security Guide](/gh-aw/introduction/architecture/) - Overall security best practices
-- [Custom Safe Outputs](/gh-aw/guides/custom-safe-outputs/) - Creating custom output types
+- [Custom Safe Outputs](/gh-aw/reference/custom-safe-outputs/) - Creating custom output types
 - [Frontmatter Reference](/gh-aw/reference/frontmatter/) - All configuration options