tweak docs

dsyme · dsyme · commit 3bea09139b53 · 2025-10-11T16:31:35.000+01:00
diff --git a/docs/src/content/docs/guides/mcps.md b/docs/src/content/docs/guides/mcps.md
@@ -1,5 +1,5 @@
 ---
-title: MCP Integration
+title: MCP Guide
 description: Learn how to use Model Context Protocol (MCP) servers with GitHub Agentic Workflows to connect AI agents to external tools, databases, and services.
 ---
 
diff --git a/docs/src/content/docs/guides/web-search.md b/docs/src/content/docs/guides/web-search.md
@@ -1,5 +1,5 @@
 ---
-title: Web Search with MCP
+title: Web Search Guide
 description: Learn how to add web search capabilities to GitHub Agentic Workflows using Tavily MCP server.
 ---
 
diff --git a/docs/src/content/docs/reference/cache-memory.md b/docs/src/content/docs/reference/cache-memory.md
@@ -1,6 +1,8 @@
 ---
 title: Cache Memory
 description: Complete guide to using cache-memory for persistent file storage across workflow runs using GitHub Actions cache and simple file operations.
+sidebar:
+  order: 1400
 ---
 
 The `cache-memory` feature enables agentic workflows to maintain persistent file storage across workflow runs using GitHub Actions cache infrastructure and simple file operations.
diff --git a/docs/src/content/docs/reference/command-triggers.md b/docs/src/content/docs/reference/command-triggers.md
@@ -2,7 +2,7 @@
 title: Command Triggers
 description: Learn about command triggers and context text functionality for agentic workflows, including special @mention triggers for interactive automation.
 sidebar:
-  order: 600
+  order: 500
 ---
 
 GitHub Agentic Workflows add the convenience `command:` trigger to create workflows that respond to `/my-bots` in issues and comments.
diff --git a/docs/src/content/docs/reference/concurrency.md b/docs/src/content/docs/reference/concurrency.md
@@ -2,81 +2,20 @@
 title: Concurrency Control
 description: Complete guide to concurrency control in GitHub Agentic Workflows, including agent job concurrency configuration and engine isolation.
 sidebar:
-  order: 600
+  order: 1300
 ---
 
-GitHub Agentic Workflows provides sophisticated concurrency control to manage how many AI-powered agent jobs can run simultaneously. This helps prevent resource exhaustion, control costs, and ensure predictable workflow execution.
+GitHub Agentic Workflows provides concurrency control to manage how many AI-powered agentic workflow runs can run simultaneously. This helps prevent resource exhaustion, control costs, and ensure predictable workflow execution.
 
-## Overview
+Concurrency control uses a dual-level approach:
+- **Workflow-level concurrency**: Limit based on workflow name and type (name, issue, PR, branch, etc.)
+- **Agent job concurrency**: Limit based on AI engine via the `engine.concurrency` field
 
-Concurrency control in GitHub Agentic Workflows uses a dual-level approach:
-- **Workflow-level concurrency**: Context-specific limiting based on workflow type (issue, PR, branch, etc.)
-- **Agent job concurrency**: Controls concurrent execution of agent jobs using the `engine.concurrency` field
+This provides both fine-grained control per workflow and flexible resource management for AI execution.
 
-This dual-level approach provides both fine-grained control per workflow and flexible resource management for AI execution.
+## Workflow-Level Concurrency
 
-## Agent Job Concurrency Configuration
-
-The `concurrency` field under the `engine` section controls concurrency for the agent job. It uses GitHub Actions concurrency syntax:
-
-```yaml
-engine:
-  id: claude
-  concurrency:
-    group: "my-group-${{ github.workflow }}"
-    cancel-in-progress: true
-```
-
-### Default Behavior
-
-**Default:** Single job per engine across all workflows
-
-When no `engine.concurrency` is specified, the default pattern is:
-```yaml
-concurrency:
-  group: "gh-aw-{engine-id}"
-```
-
-This ensures only one agent job runs at a time for each engine across all workflows and refs, preventing resource exhaustion.
-
-### Configuration Examples
-
-**Default (single job per engine):**
-```yaml
-engine:
-  id: claude
-  # No concurrency specified - uses gh-aw-claude
-```
-
-**Per-workflow concurrency:**
-```yaml
-engine:
-  id: claude
-  concurrency:
-    group: "gh-aw-claude-${{ github.workflow }}"
-```
-
-**Per-branch concurrency with cancellation:**
-```yaml
-engine:
-  id: copilot
-  concurrency:
-    group: "gh-aw-copilot-${{ github.ref }}"
-    cancel-in-progress: true
-```
-
-**Simple string format:**
-```yaml
-engine:
-  id: claude
-  concurrency: "custom-group-${{ github.workflow }}"
-```
-
-## How It Works
-
-### Workflow-Level Concurrency
-
-The workflow-level concurrency uses context-specific keys based on the trigger type:
+By default, the workflow-level concurrency uses context-specific keys based on workflow name and the trigger type:
 
 **For issue workflows:**
 ```yaml
@@ -126,20 +65,18 @@ jobs:
       cancel-in-progress: true
 ```
 
-This controls concurrent execution of agent jobs across all workflows, preventing resource exhaustion from too many concurrent AI executions.
+This controls concurrent execution of agentic workflow runs across all workflows, preventing resource exhaustion from too many concurrent AI executions.
 
 ### Complete Example
 
-Here's how both levels work together in a generated workflow:
+Here's how both levels work together in a workflow:
 
 ```yaml
 name: "Issue Responder"
 on:
   issues:
     types: [opened]
 
-permissions: {}
-
 # Workflow-level: Context-specific concurrency
 concurrency:
   group: "gh-aw-${{ github.workflow }}-${{ github.event.issue.number }}"
@@ -156,13 +93,6 @@ jobs:
         ...
 ```
 
-### Dual-Level Application
-
-The dual-level concurrency provides complementary control:
-
-1. **Workflow-level**: Prevents conflicts between runs of the same workflow on different contexts (e.g., different issues or PRs)
-2. **Agent job concurrency**: Controls concurrent execution of agent jobs based on configured pattern
-
 **Example scenario:**
 - 5 different issues trigger the same workflow
 - Workflow-level concurrency allows all 5 to start (different issue numbers)
@@ -224,8 +154,8 @@ engine:
   # Default: gh-aw-claude
 ```
 
-- Copilot agent jobs use the `gh-aw-copilot` concurrency group
-- Claude agent jobs use the `gh-aw-claude` concurrency group
+- Copilot agentic workflow runs use the `gh-aw-copilot` concurrency group
+- Claude agentic workflow runs use the `gh-aw-claude` concurrency group
 - Both can run simultaneously without conflict
 
 ## Cancellation Behavior
@@ -244,28 +174,6 @@ concurrency:
   cancel-in-progress: true
 ```
 
-## Benefits
-
-### Cost Control
-- **Prevents runaway costs**: Controls concurrent AI job execution
-- **Predictable resource usage**: Known concurrency patterns
-- **Flexible configuration**: Customize per workflow or engine
-
-### Resource Management
-- **Prevents resource exhaustion**: Ensures system stability with default single-job-per-engine pattern
-- **Fair resource distribution**: Agent jobs queue when concurrency limit is reached
-- **Maintains throughput**: Activation and other jobs continue running
-
-### Engine Isolation
-- **Independent limits**: Each engine has its own default concurrency group
-- **No cross-engine interference**: Copilot agent jobs don't block Claude agent jobs
-- **Flexible configuration**: Customize concurrency per engine
-
-### Simplicity
-- **Default global lock**: Single job per engine by default
-- **Standard GitHub Actions syntax**: Familiar concurrency configuration
-- **Consistent behavior**: Predictable execution patterns
-
 ## Custom Concurrency
 
 You can override the automatic concurrency generation by specifying your own `concurrency` section in the frontmatter (for workflow-level concurrency):
@@ -333,45 +241,6 @@ engine:
     group: "gh-aw-copilot-${{ github.workflow }}"  # Per-workflow concurrency
 ```
 
-### Monitoring and Adjustment
-
-1. **Monitor workflow execution**: Use GitHub Actions insights
-2. **Track costs**: Review AI model usage and expenses
-3. **Adjust patterns**: Change concurrency groups based on needs
-4. **Test changes**: Validate new patterns with test workflows
-
-## Troubleshooting
-
-### Agent Jobs Queuing
-
-**Symptom**: Agent jobs wait in queue instead of running
-
-**Cause**: Concurrency group is blocking (e.g., default single-job-per-engine pattern)
-
-**Solution**: 
-- Customize `engine.concurrency` to allow more parallel execution
-- Use per-workflow or per-branch patterns if appropriate
-- Consider using different engines for different workflows
-
-### Too Many Concurrent Runs
-
-**Symptom**: High costs or resource usage from concurrent agent jobs
-
-**Cause**: Concurrency pattern allows too many parallel executions
-
-**Solution**:
-- Use more restrictive concurrency pattern (e.g., default `gh-aw-{engine-id}`)
-- Monitor usage patterns
-- Set appropriate patterns per engine
-
-### Workflows Not Canceling
-
-**Symptom**: Old pull request workflows continue running after new commits
-
-**Cause**: Custom concurrency without `cancel-in-progress`
-
-**Solution**: Ensure pull request workflows have `cancel-in-progress: true` in custom concurrency configuration
-
 ## Related Documentation
 
 - [AI Engines](/gh-aw/reference/engines/) - Engine configuration and capabilities
diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md
@@ -474,7 +474,7 @@ engine:
 
 ### Agent Job Concurrency
 
-The `concurrency` field in the engine configuration controls how many agent jobs can run concurrently. It uses GitHub Actions concurrency syntax:
+The `concurrency` field in the engine configuration controls how many agentic workflow runs can run concurrently. It uses GitHub Actions concurrency syntax:
 
 ```yaml
 engine:
diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md
@@ -2,7 +2,7 @@
 title: Safe Output Processing
 description: Learn about safe output processing features that enable creating GitHub issues, comments, and pull requests without giving workflows write permissions.
 sidebar:
-  order: 500
+  order: 650
 ---
 
 One of the primary security features of GitHub Agentic Workflows is "safe output processing", enabling the creation of GitHub issues, comments, pull requests, and other outputs without giving the agentic portion of the workflow write permissions.
diff --git a/docs/src/content/docs/reference/tools.md b/docs/src/content/docs/reference/tools.md
@@ -2,7 +2,7 @@
 title: Tools Configuration
 description: Configure GitHub API tools, browser automation, and AI capabilities available to your agentic workflows, including GitHub tools, Playwright, and custom MCP servers.
 sidebar:
-  order: 500
+  order: 600
 ---
 
 This guide covers the available tools that can be configured in agentic workflows, including GitHub tools, Playwright browser automation, custom MCP servers, and engine-specific tools.
diff --git a/docs/src/content/docs/tools/mcp-server.md b/docs/src/content/docs/tools/mcp-server.md
diff --git a/pkg/parser/schemas/main_workflow_schema.json b/pkg/parser/schemas/main_workflow_schema.json
@@ -2852,15 +2852,15 @@
                 },
                 {
                   "type": "object",
-                  "description": "GitHub Actions concurrency configuration for the agent job. Controls how many agent jobs can run concurrently.",
+                  "description": "GitHub Actions concurrency configuration for the agent job. Controls how many agentic workflow runs can run concurrently.",
                   "properties": {
                     "group": {
                       "type": "string",
                       "description": "Concurrency group identifier. Use GitHub Actions expressions like ${{ github.workflow }} or ${{ github.ref }}. Defaults to 'gh-aw-{engine-id}' if not specified."
                     },
                     "cancel-in-progress": {
                       "type": "boolean",
-                      "description": "Whether to cancel in-progress runs of the same concurrency group. Defaults to false for agent jobs."
+                      "description": "Whether to cancel in-progress runs of the same concurrency group. Defaults to false for agentic workflow runs."
                     }
                   },
                   "required": ["group"],
diff --git a/pkg/workflow/concurrency_test.go b/pkg/workflow/concurrency_test.go
@@ -307,7 +307,7 @@ func TestGenerateConcurrencyConfig(t *testing.T) {
 	}
 }
 
-// TestGenerateJobConcurrencyConfig tests the job-level concurrency configuration for agent jobs
+// TestGenerateJobConcurrencyConfig tests the job-level concurrency configuration for agentic workflow runs
 func TestGenerateJobConcurrencyConfig(t *testing.T) {
 	tests := []struct {
 		name         string
