githubnext · dsyme · Aug 13, 2025 · Aug 13, 2025 · Aug 13, 2025
diff --git a/DEVGUIDE.md b/DEVGUIDE.md
@@ -1,7 +1,7 @@
 # Developer Guide
 
-> [!CAUTION]
-> This extension is a research project from GitHub Next. It is in early development and may change significantly. It has not been thoroughly tested. Using agentic workflows in your repository requires careful supervision, and even then things can still go wrong. Use it with caution, and at your own risk.
+> [!WARNING]
+> This extension is a research demonstrator. It is in early development and may change significantly. It has not been thoroughly tested. Using agentic workflows in your repository requires careful supervision, and even then things can still go wrong. Use it with caution, and at your own risk.
 
 This guide provides comprehensive information for developers working on gh-aw, including setup, development workflow, testing, and contribution guidelines.
 

diff --git a/README.md b/README.md
@@ -1,9 +1,9 @@
 # 🤖 GitHub Agentic Workflows
 
-Write agentic workflows in natural language markdown, and run them in GitHub Actions. From [GitHub Next](https://githubnext.com/) 
+Write agentic workflows in natural language markdown, and run them in GitHub Actions. From [GitHub Next](https://githubnext.com/).
 
-> [!CAUTION]
-> This extension is a research project from GitHub Next. It is in early development and may change significantly. It has not been thoroughly tested. Using agentic workflows in your repository requires careful supervision, and even then things can still go wrong. Use it with caution, and at your own risk.
+> [!WARNING]
+> This extension is a research demonstrator. It is in early development and may change significantly. It has not been thoroughly tested. Using agentic workflows in your repository requires careful supervision, and even then things can still go wrong. Use it with caution, and at your own risk.
 
 ## ⚡ Quick Start (30 seconds)
 
@@ -21,11 +21,14 @@ gh aw add weekly-research -r githubnext/agentics --pr
 
 This command will create a PR to your repo adding several files including `.github/workflows/weekly-research.md` and `.github/workflows/weekly-research.lock.yml`.
 
-Your repository will also need a ANTHROPIC_API_KEY or OPENAI_API_KEY Actions secret set up to run workflows that use AI models. You can add this using one of the following commands:
+Your repository will also need an ANTHROPIC_API_KEY (for Claude) or OPENAI_API_KEY (for Codex) Actions secret set up to run workflows that use AI models. You can add this using one of the following commands:
 
 ```bash
+# For Claude engine (default)
 gh secret set ANTHROPIC_API_KEY -a actions --body <your-anthropic-api-key>
-#gh secret set OPENAI_API_KEY -a actions --body <your-openai-api-key>
+
+# For Codex engine (experimental)
+gh secret set OPENAI_API_KEY -a actions --body <your-openai-api-key>
 ```
 
 Once you've reviewed and merged the PR you're all set! Each week, the workflow will run automatically and create a research report issue in your repository. If you're in a hurry and would like to run the workflow immediately, you can do so using:
@@ -126,12 +129,17 @@ You will see the changes reflected in the `.lock.yml` file, which is the actual
 By default Claude Code is used as the agentic processor. You can configure the agentic processor by editing the frontmatter of the markdown workflow files.
 
 ```markdown
-engine: codex  # Optional: specify AI engine (claude, codex)
+engine: claude  # Default: Claude Code
+engine: codex   # Experimental: OpenAI Codex CLI with MCP support
 ```
 
 You can also specify this on the command line when adding or running workflows:
 
 ```bash
+# Use Claude (default)
+gh aw add weekly-research --engine claude
+
+# Use Codex (experimental)
 gh aw add weekly-research --engine codex
 ```
 

diff --git a/cmd/gh-aw/main.go b/cmd/gh-aw/main.go
@@ -287,6 +287,18 @@ func init() {
 	// Add global verbose flag to root command
 	rootCmd.PersistentFlags().BoolVarP(&verbose, "verbose", "v", false, "Enable verbose output showing detailed information")
 
+	// Override the help function to hide completion command
+	originalHelpFunc := rootCmd.HelpFunc()
+	rootCmd.SetHelpFunc(func(cmd *cobra.Command, args []string) {
+		// Hide completion command before displaying help
+		for _, subCmd := range cmd.Commands() {
+			if subCmd.Name() == "completion" {
+				subCmd.Hidden = true
+			}
+		}
+		originalHelpFunc(cmd, args)
+	})
+
 	// Add number flag to add command
 	addCmd.Flags().IntP("number", "c", 1, "Create multiple numbered copies")
 

diff --git a/docs/commands.md b/docs/commands.md
@@ -26,6 +26,15 @@ gh aw compile
 # Compile workflows with verbose output
 gh aw compile --verbose
 
+# Compile workflows with schema validation
+gh aw compile --validate
+
+# Compile workflows with engine override
+gh aw compile --engine codex
+
+# Generate GitHub Copilot instructions file
+gh aw compile --instructions
+
 # Compile workflows and generate auto-compile workflow for automatic compilation
 gh aw compile --auto-compile
 
@@ -194,6 +203,15 @@ gh aw list --packages
 
 # List only local packages
 gh aw list --packages --local
+
+# Uninstall a workflow package globally
+gh aw uninstall org/repo
+
+# Uninstall a workflow package locally
+gh aw uninstall org/repo --local
+
+# Show version information
+gh aw version
 ```
 
 **Package Management Features:**
@@ -210,7 +228,24 @@ gh aw list --packages --local
 - Network access to download from GitHub repositories
 - Target repository must have a `workflows/` directory containing `.md` files
 
-## 📝 Creating New Workflows
+## �️ Package Removal
+
+```bash
+# Uninstall workflow packages globally (default)
+gh aw uninstall org/repo
+
+# Uninstall packages locally from current project
+gh aw uninstall org/repo --local
+```
+
+**Package Removal Features:**
+
+- **Clean Uninstall**: Removes all downloaded workflow files and metadata
+- **Global vs Local**: Supports both global (`~/.aw/packages/`) and local (`.aw/packages/`) removal
+- **Safe Operation**: Only removes the specified package without affecting others
+- **Validation**: Confirms package exists before attempting removal
+
+## �📝 Creating New Workflows
 
 The `gh aw new` command creates a new workflow markdown file with comprehensive template content and examples.
 

diff --git a/docs/frontmatter.md b/docs/frontmatter.md
@@ -105,9 +105,9 @@ analyze and provide a helpful summary.
 The current context text is: "${{ needs.task.outputs.text }}"
 ```
 
-## Context Text Variable (`text`)
+## Context Text (`needs.task.outputs.text`)
 
-All workflows have access to a computed `text` output variable that provides context based on the triggering event:
+All workflows have access to a special computed `needs.task.outputs.text` value that provides context based on the triggering event:
 
 ```markdown
 # Analyze this content: "${{ needs.task.outputs.text }}"
@@ -148,16 +148,24 @@ If you specify any permission, unspecified ones are set to `none`.
 
 Specifies which AI engine to use. Defaults to `claude`.
 
+```yaml
+engine: claude  # Default: Claude Code
+engine: codex   # Experimental: OpenAI Codex CLI with MCP support
+```
+
+**Engine Override**:
+You can override the engine specified in frontmatter using CLI flags:
+```bash
+gh aw add weekly-research --engine codex
+gh aw compile --engine claude
+```
+
 ### Simple String Format
 
 ```yaml
 engine: claude  # or codex
 ```
 
-**Available engines:**
-- `claude` (default): Claude Code with full MCP tool support and allow-listing (see [MCP Guide](mcps.md))
-- `codex` (**experimental**): Codex with OpenAI endpoints   
-
 ### Extended Object Format
 
 ```yaml
@@ -170,7 +178,11 @@ engine:
 **Fields:**
 - **`id`** (required): Engine identifier (`claude`, `codex`)
 - **`version`** (optional): Action version (`beta`, `stable`)
-- **`model`** (optional): Specific LLM model
+- **`model`** (optional): Specific LLM model to use
+
+**Model Defaults:**
+- **Claude**: Uses the default model from the claude-code-base-action (typically latest Claude model)
+- **Codex**: Defaults to `o4-mini` when no model is specified
 
 ## Cost Control Options
 

diff --git a/docs/index.md b/docs/index.md
@@ -1,7 +1,7 @@
 # 📖 GitHub Agentic Workflows Documentation
 
-> [!CAUTION]
-> This extension is a research project from GitHub Next. It is in early development and may change significantly. It has not been thoroughly tested. Using agentic workflows in your repository requires careful supervision, and even then things can still go wrong. Use it with caution, and at your own risk.
+> [!WARNING]
+> This extension is a research demonstrator. It is in early development and may change significantly. It has not been thoroughly tested. Using agentic workflows in your repository requires careful supervision, and even then things can still go wrong. Use it with caution, and at your own risk.
 
 Complete documentation for creating and managing agentic workflows with GitHub Actions.
 

diff --git a/docs/mcps.md b/docs/mcps.md
@@ -40,10 +40,10 @@ tools:
 
 Different AI engines support different MCP features:
 
-- **Claude** (default): ✅ Full MCP support (stdio and HTTP)
-- **Codex**: ✅ Limited MCP support (stdio only)
-- **AI Inference**: ✅ GitHub MCP support
-- **Other engines**: Varies by engine
+- **Claude** (default): ✅ Full MCP support (stdio, Docker, HTTP)
+- **Codex** (experimental): ✅ Limited MCP support (stdio only, no HTTP)
+
+**Note**: When using Codex engine, HTTP MCP servers will be ignored and only stdio-based servers will be configured.
 
 ## MCP Server Types
 

diff --git a/docs/secrets.md b/docs/secrets.md
@@ -18,17 +18,88 @@ permissions:
 ```
 
 ## User-Defined Secrets
-You need to define custom secrets in your repository or organization settings to enable usage of your chosen agentic processor. These secrets will be referenced in generated workflows.
 
-### `ANTHROPIC_API_KEY`
+You need to define custom secrets in your repository or organization settings to enable usage of your chosen agentic processor and external services.
+
+### AI Engine Secrets
+
+#### `ANTHROPIC_API_KEY`
 - **Purpose**: Claude engine access
-- **Required for**: `engine: claude` workflows
+- **Required for**: `engine: claude` workflows (default)
 - **Setup**: Add to repository or organization secrets
+- **Usage**: Automatically used by Claude engine
 
-### `OPENAI_API_KEY`
+#### `OPENAI_API_KEY`
 - **Purpose**: Codex and OpenAI-based engines
-- **Required for**: `engine: codex` workflows
+- **Required for**: `engine: codex` workflows (experimental)
 - **Setup**: Add to repository or organization secrets
+- **Usage**: Automatically used by Codex engine
+
+### MCP Server Secrets
+
+Custom secrets for MCP servers are referenced using `${secrets.SECRET_NAME}` syntax:
+
+```yaml
+tools:
+  trello:
+    mcp:
+      type: stdio
+      command: "python"
+      args: ["-m", "trello_mcp"]
+      env:
+        TRELLO_TOKEN: "${secrets.TRELLO_TOKEN}"
+        TRELLO_KEY: "${secrets.TRELLO_KEY}"
+    allowed: ["list_boards", "create_card"]
+```
+
+### Custom Environment Variables
+
+You can define custom environment variables in the workflow frontmatter:
+
+```yaml
+env:
+  NODE_ENV: "production"
+  DEBUG: "false"
+  CUSTOM_CONFIG: "${secrets.MY_CONFIG}"
+```
+
+## Setting Up Secrets
+
+### Repository Secrets
+```bash
+# Set secrets for a specific repository
+gh secret set ANTHROPIC_API_KEY -a actions --body <your-api-key>
+gh secret set TRELLO_TOKEN -a actions --body <your-trello-token>
+```
+
+### Organization Secrets
+```bash
+# Set secrets for all repositories in an organization
+gh secret set ANTHROPIC_API_KEY -a actions --org <your-org> --body <your-api-key>
+```
+
+## Security Best Practices
+
+### Secret Access
+- Secrets are only accessible to workflows with appropriate permissions
+- Secrets are automatically masked in workflow logs
+- Use minimal scope secrets when possible
+
+### Secret Naming
+- Use UPPER_CASE names for secrets
+- Use descriptive names that indicate the service: `TRELLO_TOKEN`, `SLACK_WEBHOOK`
+- Avoid exposing secret values in frontmatter or markdown content
+
+### MCP Server Security
+```yaml
+# ✅ Good: Secret reference
+env:
+  API_KEY: "${secrets.MY_API_KEY}"
+
+# ❌ Bad: Hardcoded value
+env:
+  API_KEY: "sk-1234567890abcdef"
+```
 
 ## Related Documentation
 

diff --git a/docs/tools.md b/docs/tools.md
@@ -119,18 +119,6 @@ tools:
       Bash: ["echo", "ls", "git", "npm test"]
 ```
 
-## Engine Compatibility
-
-### Claude Engine
-- ✅ GitHub tools
-- ✅ Claude-specific tools
-- ✅ Custom MCP tools (see [MCP Guide](mcps.md))
-
-### Codex Engine
-- ✅ GitHub tools
-- ❌ Claude-specific tools (ignored)
-- ✅ Custom MCP tools (stdio only, see [MCP Guide](mcps.md))
-
 
 ## Security Considerations
 

diff --git a/pkg/cli/commands.go b/pkg/cli/commands.go
@@ -2824,9 +2824,9 @@ func listPackageWorkflows(verbose bool) error {
 		// Mark packages with their location
 		for i := range packages {
 			if local {
-				packages[i].Name = packages[i].Name + " (local)"
+				packages[i].Name = packages[i].Name + ", local"
 			} else {
-				packages[i].Name = packages[i].Name + " (global)"
+				packages[i].Name = packages[i].Name + ", global"
 			}
 		}
 
@@ -3063,7 +3063,7 @@ func RunWorkflowOnGitHub(workflowIdOrName string, verbose bool) error {
 	return nil
 }
 
-// IsRunnable checks if a workflow can be run locally (has schedule or workflow_dispatch trigger)
+// IsRunnable checks if a workflow can be run (has schedule or workflow_dispatch trigger)
 func IsRunnable(markdownPath string) (bool, error) {
 	// Read the file
 	contentBytes, err := os.ReadFile(markdownPath)