From 7c3609f5e88452ac16a8b33e7429ea0cc25c197e Mon Sep 17 00:00:00 2001
From: Daily Documentation Updater
 <github-actions[bot]@users.noreply.github.com>
Date: Mon, 27 Oct 2025 06:09:26 +0000
Subject: [PATCH] Update CLI reference for features from Oct 26, 2025
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update documentation to reflect recent CLI changes:

- Document init command's new workflow creation guidance
- Clarify --validate flag behavior (disabled by default)
- Reorganize workflow creation section for better clarity

Changes based on:
- PR #2567: Init command now guides users to activate create-agentic-workflow prompt
- PR #2550: --validate flag now defaults to false for faster compilation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/src/content/docs/tools/cli.md | 26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)

diff --git a/docs/src/content/docs/tools/cli.md b/docs/src/content/docs/tools/cli.md
index 8acb07b36..76f14d5fd 100644
--- a/docs/src/content/docs/tools/cli.md
+++ b/docs/src/content/docs/tools/cli.md
@@ -76,11 +76,27 @@ Debug logs show:
 - Use `--verbose` for user-facing operational details
 - Debug logs are zero-overhead when disabled (no performance impact)
 
-## 📝 Workflow Creation and Management  
+## 📝 Workflow Creation and Management
 
 The `add` and `new` commands help you create and manage agentic workflows, from templates and samples to completely custom workflows.
 
-The `init` command prepares your repository for agentic workflows by configuring `.gitattributes` and creating GitHub Copilot custom instructions.
+### Repository Initialization
+
+The `init` command prepares your repository for agentic workflows by configuring `.gitattributes` and creating GitHub Copilot custom instructions:
+
+```bash
+gh aw init
+```
+
+After initialization, start a chat with an AI agent and use the following prompt to create a new workflow:
+
+```
+activate @.github/prompts/create-agentic-workflow.prompt.md
+```
+
+Alternatively, add pre-built workflows from the catalog using `gh aw add <workflow-name>`.
+
+### Workflow Management
 
 ```bash
 # Create new workflows
@@ -127,7 +143,7 @@ Transforms markdown workflow files into executable GitHub Actions YAML files:
 # Core compilation
 gh aw compile                              # Compile all workflows
 gh aw compile ci-doctor daily-plan         # Compile specific workflows
-gh aw compile --validate --no-emit         # Validate without generating files
+gh aw compile --validate --no-emit         # Validate schema and containers without generating files
 gh aw compile --strict --engine copilot    # Strict mode with custom engine
 gh aw compile --purge                      # Remove orphaned .lock.yml files
 
@@ -140,6 +156,10 @@ gh aw compile --dependabot                 # Generate dependency manifests
 gh aw compile --dependabot --force         # Force overwrite existing files
 ```
 
+**Validation:**
+
+The `--validate` flag enables GitHub Actions workflow schema validation and container image validation. By default, validation is disabled for faster compilation. Enable it when you need to verify workflow correctness or validate that container images exist and are accessible.
+
 **Strict Mode:**
 
 Enables enhanced security validation requiring timeouts, explicit network configuration, and blocking write permissions. Use `--strict` flag or `strict: true` in frontmatter.