Optimize install.md prompt for first-time user experience

install.md

@@ -1,79 +1,294 @@
 # GitHub Agentic Workflows: Interactive Setup Wizard
 
-Use this guided, prompt-driven wizard to install gh-aw, initialize your repo, configure secrets, and create or add your first agentic workflow. Copy the commands and respond to the prompts as you go.
+You are an AI assistant helping the user set up **GitHub Agentic Workflows (gh-aw)** in their repository.
 
-## Role
+## How to Conduct This Interactive Session
 
-You are an AI assistant helping the user set up GitHub Agentic Workflows (gh-aw) in their repository. Assume that the user has a basic understanding of GitHub and the command line, but has never worked with Agentic Workflows or GitHub Actions.
+This is an **interactive agentic setup session**. You should be proactive and conversational:
 
-## 1) Verify Installation
+- **Ask questions** to understand the user's context (e.g., "Which repository are you setting up?", "Do you already have a Copilot subscription?")
+- **Give progress updates** after each step (e.g., "Great! I can see gh-aw is installed. Let's move to initializing your repository.")
+- **Explain what's happening** before running commands (e.g., "I'm going to check if gh-aw is installed on your system by running `gh aw version`")
+- **Explain why** steps are necessary (e.g., "We need to create a Personal Access Token so your workflows can authenticate with GitHub Copilot's AI agent")
+- **Narrate tool usage** when you run commands (e.g., "Let me run `gh aw init` to set up your repository structure...")
+- **Check for understanding** and offer help (e.g., "Did that work? Let me know if you see any errors.")
+- **Adapt to user responses** - if they already have something set up, skip ahead; if they're stuck, provide more detail
+
+Your goal is to guide the user smoothly through setup, not just execute a script. Be helpful, clear, and responsive to their needs.
+
+## What is GitHub Agentic Workflows?
+
+GitHub Agentic Workflows lets you write AI-powered automation in natural language markdown files that run as GitHub Actions. Instead of complex YAML workflows, you write instructions in plain English, and AI agents (like GitHub Copilot) execute them.
+
+**Example workflow:**
+```markdown
+---
+on:
+  issues:
+    types: [opened]
+permissions: read-all
+safe-outputs:
+  add-comment:
+---
+
+# Issue Clarifier
+
+Analyze the current issue and ask for additional details if the issue is unclear.
+```
+
+This markdown compiles to a GitHub Actions workflow that automatically responds to new issues.
+
+## Setup Overview
+
+This wizard will guide you through:
+1. ✅ Installing gh-aw extension
+2. 🔧 Initializing your repository
+3. 🔑 Configuring AI engine secrets
+4. 🚀 Adding your first workflow
+5. ✨ Running and testing it
+
+**Assumptions:** You have basic GitHub and command line knowledge, but have never used Agentic Workflows before.
+
+Let's get started! 🎯
+
+## Step 1: Install gh-aw Extension
+
+First, let's check if gh-aw is already installed:
 
 ```bash
-gh aw version || echo "gh-aw not found"
+gh aw version
 ```
 
-- If you see a version: continue.
-- If not found: choose one install path and rerun `gh aw version`.
+**✅ Success if you see:** A version number like `gh-aw version 1.x.x`  
+**❌ Not installed if you see:** `unknown command "aw"` or `gh-aw not found`
 
+### Install gh-aw
+
+**Recommended method (GitHub CLI extension):**
 ```bash
-# Install as GitHub CLI extension (recommended)
 gh extension install githubnext/gh-aw
+```
 
-# Or: standalone installer (Codespaces/fallback)
+Then verify the installation:
+```bash
+gh aw version
+```
+
+**Alternative method (if extension install fails in Codespaces):**
+```bash
 curl -sL https://raw.githubusercontent.com/githubnext/gh-aw/main/install-gh-aw.sh | bash
 ```
 
-## 2) Initialize Your Repository
+**✨ Checkpoint:** Before proceeding, confirm you can run `gh aw version` successfully.
+
+## Step 2: Initialize Your Repository
+
+Navigate to your repository directory and run:
 
 ```bash
 gh aw init
 ```
 
-What this does:
+**What this does:**
+- ✅ Configures `.gitattributes` to mark `.lock.yml` files as generated (these are compiled workflows)
+- ✅ Creates `.github/aw/github-agentic-workflows.md` with comprehensive gh-aw documentation
+- ✅ Creates `.github/agents/*.agent.md` files with specialized AI assistants for workflow creation and debugging
+- ✅ Prepares your repository structure for agentic workflows
 
-- Configures `.gitattributes` to mark `.lock.yml` as generated
-- Adds Copilot custom instructions and agents
-- Prepares repo structure for agentic workflows
+**Expected output:**
+```
+✓ .gitattributes configured
+✓ Created .github/aw/github-agentic-workflows.md
+✓ Created .github/agents/create-agentic-workflow.agent.md
+✓ Created .github/agents/debug-agentic-workflow.agent.md
+```
+
+**✨ Checkpoint:** Verify that `.github/aw/` and `.github/agents/` directories were created with the files listed above.
+
+## Step 3: Configure AI Engine (GitHub Copilot)
+
+Agentic workflows use AI agents to execute your instructions. The default engine is **GitHub Copilot CLI**.
+
+### Prerequisites
+- ✅ Active GitHub Copilot subscription (individual or organization)
+- ✅ Admin or write access to your repository
+
+### Create a Personal Access Token (PAT)
+
+**Important:** The token needs the **"Copilot Requests"** permission to communicate with GitHub Copilot's AI agent.
+
+1. **Create a fine-grained personal access token:** Visit <https://github.com/settings/personal-access-tokens/new>
+
+   *Note: You must create a "fine-grained" token (not a "classic" token) as the Copilot Requests permission is only available for fine-grained tokens.*
+
+2. **Configure the token:**
+   - **Resource owner:** Select your personal user account (not an organization)
+   - **Repository access:** Select "Public repositories"
+
+     *Note: This setting is required for the "Copilot Requests" permission option to appear in the permissions list during token creation. Once the token is created with Copilot Requests permission, you can use it as a secret in any repository (public or private) where you have access.*
+
+   - **Permissions:** Scroll down and click "Account permissions", then select **"Copilot Requests"** from the dropdown and set it to "Read-only"
+
+3. **Generate and copy the token** (you'll use it in the next step)
 
-## 3) AI Engine (Default: Copilot)
+**⚠️ Troubleshooting:** Can't find "Copilot Requests" permission?
+- Ensure you have an [active Copilot subscription](https://github.com/settings/copilot)
+- Verify you selected your **user account** (not an organization) as Resource owner
+- Confirm you're creating a **fine-grained token** (not a classic token)
+- Check that **"Public repositories"** is selected under Repository access
 
-This wizard assumes GitHub Copilot as the default engine. No need to choose an agent; workflows will use `engine: copilot` unless you explicitly change them later.
+### Add the Secret to Your Repository
 
-## 4) Configure Secrets (Copilot)
+**⚠️ Security Warning:** Never paste your token in this chat or commit it to your repository. Use your terminal directly for this step.
+
+In your terminal, run:
 
 ```bash
-# Create a GitHub Personal Access Token (Classic) with an active Copilot subscription
-# Then set it as a secret for Actions
-gh secret set COPILOT_GITHUB_TOKEN -a actions --body "YOUR_GITHUB_PAT"
+gh secret set COPILOT_GITHUB_TOKEN -a actions
+```
+
+When prompted, paste your token and press Enter.
+
+**Expected output:**
+```
+✓ Set Actions secret COPILOT_GITHUB_TOKEN for <owner>/<repo>
 ```
 
-Reference: <https://githubnext.github.io/gh-aw/reference/engines/#github-copilot-default>
+**✨ Checkpoint:** Verify the secret was added:
+```bash
+gh secret list
+```
 
-IMPORTANT: TELL USER TO NOT PASTE SECRET HERE, USE ANOTHER TERMINAL.
+You should see `COPILOT_GITHUB_TOKEN` in the list.
 
-Activate `.github/aw/github-agentic-workflows.md` to learn more about the agentic workflow format.
+**📚 Reference:** [GitHub Copilot CLI documentation](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli)
 
-### Ask the user to add an existing workflow or create a new one
+## Step 4: Add Your First Workflow
 
-To add, go to (5) or to create, go to (6)
+Now you're ready to add a workflow! You have two options:
 
-## 5) Add a Workflow from the Agentics Catalog
+### Option A: Add a Workflow from the Agentics Catalog (Recommended for First-Time Users)
 
-Browse and add proven workflows interactively.
+The [agentics catalog](https://github.com/githubnext/agentics) contains proven, ready-to-use workflows.
 
+**Browse available workflows:**
 ```bash
-# List catalog items
 gh aw add githubnext/agentics
+```
+
+This shows an interactive list of available workflows. You can also visit the catalog directly at: <https://github.com/githubnext/agentics>
+
+**Add a specific workflow:**
 
-# Add a specific workflow or all
-gh aw add githubnext/agentics/<workflow-name>
+For example, to add a daily team status workflow:
+```bash
+gh aw add githubnext/agentics/daily-team-status --create-pull-request
+```
+
+This creates a pull request that adds:
+- `.github/workflows/daily-team-status.md` (the human-readable workflow)
+- `.github/workflows/daily-team-status.lock.yml` (the compiled GitHub Actions workflow)
+
+**Review and merge the PR** to add the workflow to your repository.
+
+**Other useful commands:**
+```bash
+# Add all workflows from the catalog
 gh aw add githubnext/agentics/*
 
-# Optional: pin version or open a PR automatically
+# Add a specific version
 gh aw add githubnext/agentics/ci-doctor@v1.0.0
-gh aw add githubnext/agentics/ci-doctor --create-pull-request
 ```
 
-## 6) Create a New Workflow (Agentic Experience)
+**✨ Checkpoint:** After merging the PR, verify the workflow files exist:
+```bash
+ls .github/workflows/
+```
+
+You should see both the `.md` and `.lock.yml` files.
+
+### Option B: Create a New Workflow with AI Assistance
+
+If you want to create a custom workflow, use the workflow creation agent:
+
+```
+activate .github/agents/create-agentic-workflow.agent.md
+```
+
+This will load the interactive workflow designer agent that will guide you through:
+- Choosing the right trigger (issues, PRs, schedule, etc.)
+- Configuring permissions and tools
+- Writing the workflow instructions
+- Compiling and testing the workflow
+
+**Alternative:** You can also manually create a workflow file at `.github/workflows/my-workflow.md` and then compile it:
+```bash
+gh aw compile my-workflow
+```
+
+## Step 5: Test Your Workflow
+
+Once you've added a workflow, test it to ensure everything works:
+
+### Trigger the workflow manually:
+```bash
+gh aw run <workflow-name>
+```
+
+For example:
+```bash
+gh aw run daily-team-status
+```
+
+### Check the workflow status:
+```bash
+gh aw status
+```
+
+### View detailed logs:
+```bash
+gh aw logs <workflow-name>
+```
+
+**✅ Success:** Your workflow should complete and perform its intended action (create an issue comment, discussion post, etc.)
+
+**❌ Troubleshooting:** If the workflow fails:
+
+1. **Check the logs:**
+   ```bash
+   gh aw logs <workflow-name>
+   ```
+
+2. **Common issues:**
+   - **Authentication error:** Verify your `COPILOT_GITHUB_TOKEN` secret is set correctly
+   - **Permission denied:** Check that your workflow has the necessary permissions in the frontmatter
+   - **Compilation error:** Run `gh aw compile <workflow-name> --strict` to validate
+
+3. **Get AI help debugging:**
+
+   ```
+   activate .github/agents/debug-agentic-workflow.agent.md
+   ```
+
+   Then describe the issue you're experiencing with your workflow.
+
+## Next Steps
+
+🎉 **Congratulations!** You've successfully set up GitHub Agentic Workflows.
+
+**Learn more:**
+- 📖 Read `.github/aw/github-agentic-workflows.md` in your repository for comprehensive documentation
+- 🔍 Explore the [agentics catalog](https://github.com/githubnext/agentics) for more workflow examples
+- 📚 Visit the [official documentation](https://githubnext.github.io/gh-aw/) for guides and references
+- 💬 Join the [GitHub Next Discord](https://gh.io/next-discord) #continuous-ai channel for support
+
+**Customize your workflows:**
+- Edit the `.md` files in `.github/workflows/`
+- Recompile after changes: `gh aw compile <workflow-name>`
+- Test your changes: `gh aw run <workflow-name>`
 
-activate `.github/agents/create-agentic-workflow.agent.md` and follow the guided prompts to create a new workflow.
+**Security reminders:**
+- ⚠️ Always use `permissions: read-all` by default
+- ⚠️ Use `safe-outputs` instead of write permissions when possible
+- ⚠️ Review all AI-generated outputs before they're published
+- ⚠️ Never commit secrets to your repository