diff --git a/README.md b/README.md
index 1d85d516..5e783f62 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@ 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/
@@ -15,8 +15,8 @@ Full documentation lives at https://elastic.github.io/ai-github-actions/.
 
 ## 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
 
diff --git a/docs/index.md b/docs/index.md
index 7f359a9a..12f15aed 100644
--- a/docs/index.md
+++ b/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
 
diff --git a/docs/workflows/claude-workflows.md b/docs/workflows/claude-workflows.md
index 35cc932d..c2fb9156 100644
--- a/docs/workflows/claude-workflows.md
+++ b/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.
 
diff --git a/mkdocs.yml b/mkdocs.yml
index ae1e320b..04c57e87 100644
--- a/mkdocs.yml
+++ b/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