docs: focus docs on gh-aw workflows; move Claude to legacy

README.md

@@ -7,16 +7,16 @@ AI-powered GitHub workflows for Elastic repositories.
 Full documentation lives at https://elastic.github.io/ai-github-actions/.
 
 - GitHub Agent Workflows (recommended): https://elastic.github.io/ai-github-actions/workflows/gh-agent-workflows/
-- Claude Composite Actions: https://elastic.github.io/ai-github-actions/workflows/claude-workflows/
+- Legacy Claude Composite Actions: https://elastic.github.io/ai-github-actions/workflows/claude-workflows/
 - Developing: https://elastic.github.io/ai-github-actions/developing/
 - Security: https://elastic.github.io/ai-github-actions/security/
 - Release process: https://elastic.github.io/ai-github-actions/release/
 - Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
 
 ## Overview
 
-- GitHub Agent Workflows provide safe-output guardrails with configurable engines (Copilot or Claude).
-- Claude Composite Actions provide direct Claude Code actions with RO/RWX/RWXP permission variants.
+- GitHub Agent Workflows are the primary/recommended path and provide safe-output guardrails with configurable engines.
+- Claude Composite Actions remain supported as a legacy option with RO/RWX/RWXP permission variants.
 
 ## Quick setup script
 

docs/index.md

@@ -4,21 +4,24 @@
 
 AI-powered GitHub workflows for Elastic repositories.
 
-## Choose an approach
+## Recommended approach
 
-| Feature | GitHub Agent Workflows | Claude Composite Actions |
-| --- | --- | --- |
-| Engine | Copilot (default) or Claude | Claude only |
-| Install | Copy trigger YAML (recommended) | Copy `example.yml` to `.github/workflows/` |
-| Guardrails | Safe-outputs framework (structured API outputs) | Read-only/RWX/RWXP variants via permissions |
-| Customization | `additional-instructions`, `setup-commands`, or full shim edit | Edit YAML directly, adjust composite action inputs |
+| Feature | GitHub Agent Workflows |
+| --- | --- |
+| Engine | Copilot (default) or Claude |
+| Install | Copy trigger YAML (recommended) |
+| Guardrails | Safe-outputs framework (structured API outputs) |
+| Customization | `additional-instructions`, `setup-commands`, or full shim edit |
 
-GitHub Agent Workflows are recommended for new deployments; Claude Composite Actions remain supported for legacy deployments.
+GitHub Agent Workflows are recommended for all new deployments and ongoing maintenance.
 
 ## Workflows
 
 - [GitHub Agent Workflows](workflows/gh-agent-workflows.md)
-- [Claude Composite Actions](workflows/claude-workflows.md)
+
+## Legacy
+
+- [Claude Composite Actions (legacy)](workflows/claude-workflows.md)
 
 ## More
 

docs/workflows/claude-workflows.md

@@ -1,6 +1,8 @@
-# Claude Composite Actions
+# Legacy: Claude Composite Actions
 
-Traditional GitHub Actions wrapping Claude Code. Consumed via `uses:` in standard workflows.
+This is the legacy workflow path. For new deployments, use [GitHub Agent Workflows](gh-agent-workflows.md).
+
+Traditional GitHub Actions wrapping Claude Code, consumed via `uses:` in standard workflows.
 
 > **Note:** This directory was renamed from `workflows/` to `claude-workflows/`. A symlink ensures backwards compatibility — existing `uses: elastic/ai-github-actions/claude-workflows/...@v0` references continue to work.
 

mkdocs.yml

@@ -44,7 +44,8 @@ nav:
               - Small Problem Fixer: workflows/gh-agent-workflows/small-problem-fixer.md
               - Stale Issues: workflows/gh-agent-workflows/stale-issues.md
               - Test Improvement: workflows/gh-agent-workflows/test-improvement.md
-      - Claude Composite Actions: workflows/claude-workflows.md
+      - Legacy:
+          - Claude Composite Actions: workflows/claude-workflows.md
   - Developing: developing.md
   - Security: security.md
   - Release: release.md