-
Notifications
You must be signed in to change notification settings - Fork 45
Closed
Labels
ai-generateddocumentationImprovements or additions to documentationImprovements or additions to documentationplan
Description
Objective
Add verification commands after setup steps so users can confirm their configuration is working correctly, and provide troubleshooting context for common issues.
Problem
After adding the COPILOT_GITHUB_TOKEN secret, the guide says "Your repository is now configured!" but doesn't tell users:
- How to verify the setup worked
- What to do if something went wrong
- How to know if the token is valid
Additionally, the CLI commands page lacks context about when to use each command.
Approach
- Add verification step after token setup in Quick Start:
# Verify your setup
gh aw status
# Expected output:
# ✓ gh-aw extension: v0.x.x
# ✓ GitHub CLI: authenticated
# ✓ Repository: githubnext/gh-aw
# ✓ Copilot token: configured- Add "Common Workflows" section to CLI Commands page:
### Common Workflows for Beginners
**After creating a new workflow:**
```bash
gh aw compile my-workflow.md # Check for syntax errors
gh aw run my-workflow # Test it manually (if workflow_dispatch enabled)
gh aw logs my-workflow # See what happenedWhen something goes wrong:
gh aw status # Check configuration
gh aw logs my-workflow -f # Watch live logs
gh aw audit (run-id) # Analyze specific run (get run-id from Actions tab)- Improve Safe Outputs explanation with security context:
**Safe Outputs are a security feature.** Your AI agent runs with minimal permissions (read-only). When it wants to make changes (like creating an issue), it "requests" that action. A separate, permission-controlled job reviews and executes these requests. This prevents the AI from accidentally or maliciously making unauthorized changes.Files to Modify
docs/src/content/docs/setup/quick-start.mdx- Add verification commands after token setupdocs/src/content/docs/setup/cli.mdx- Add "Common Workflows" section with contextdocs/src/content/docs/index.mdxor relevant concept page - Improve Safe Outputs explanation
Acceptance Criteria
- Verification command added after token configuration step
- Expected output shown so users know what success looks like
- CLI Commands page includes usage context for beginners
- Run-id explained (where to find it)
- Safe Outputs explanation clarifies security model
- Users can self-diagnose basic setup issues
Reference
From noob test report: Critical Issue #3 (Token Creation), Confusing Areas #4 (Safe Outputs), #5 (CLI Commands)
Related to #6505
AI generated by Plan Command for discussion #6502
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
ai-generateddocumentationImprovements or additions to documentationImprovements or additions to documentationplan