chore: restructure docs following modern DX best practices

[Copilot]

Restructured /docs/src/content/docs/setup/cli.md and updated site navigation to follow modern CLI documentation patterns (VS Code, Stripe, Prisma, Docker, GitHub CLI) - improving discoverability, organization, and developer experience.

Changes

CLI Documentation Structure & Organization

• Overview - Added "what it does" and "who it's for" sections upfront
• Quick Start - Moved to top with one-command initialization (gh aw init)
• Use Cases Table - Maps 14 common scenarios to specific commands (e.g., "Test safely before deploying" → gh aw trial ./workflow.md)
• Command Reference - Restructured 16 commands with consistent format: description, usage, "what it does", options table, related links
• Examples - Added 4 runnable examples with expected outputs (lifecycle, verbose logging, debugging, log analysis)

Enhanced Reference Tables

• Command overview (16 commands)
• Global flags (-h, -v)
• Compilation options (6 flags with defaults)
• Log analysis options (5 filters)
• Trial mode options (8 flags)
• Exit codes (0, 1, 2 with meanings)
• Troubleshooting (7 common issues with symptom/cause/fix)

Navigation Updates

Top Navbar (docs/src/components/CustomHeader.astro):

• Replaced "Docs" with direct "Quick Start" link (prioritizes getting started)
• Changed "Setup" to "CLI" linking directly to /setup/cli/ (clearer and more concise)
• Added "Reference" linking to /reference/workflow-structure/ (better discoverability)
• New structure: Quick Start | CLI | Guides | Reference | Status

Sidebar (docs/astro.config.mjs):

• Reorganized "Setup" section into dedicated "CLI" group with 3 key items:
  • Commands (main CLI documentation)
  • VS Code Integration
  • MCP Server
• Renamed "Workflows" to "Workflow Reference" (more descriptive)
• Renamed "Applications" to "Examples" (clearer purpose)
• Added dedicated "Troubleshooting" section with Error Reference, Common Issues, and Validation Timing
• Promoted "Authoring" to top-level item (better visibility)

Cross-Linking

• 30+ cross-links between related documentation sections
• Organized "See Also" into 4 categories (Getting Started, Workflow Management, Advanced Topics, Setup & Integration)
• Deep-linked table of contents with 37 sections

Screenshot

CLI documentation expanded from 199 to 668 lines. Documentation builds successfully with all internal links validated. Navigation now provides clear, logical paths to all key sections.

Original prompt

Docs content restructuring

Goal

Restructure and optimize this documentation (in /docs) so developers can quickly understand, install, and use the CLI, following modern DX best-practices inspired by:

• VS Code (task-first, workflows, discoverability)
• Stripe (clear structure, runnable examples)
• Prisma / Supabase (clean navigation, consistency)
• Docker & GitHub CLI (concise reference tables)

Allowed

• Rewrite copy for clarity
• Change section order & improve hierarchy
• Add cross-links between related sections

NOT Allowed

• Change Markdown formatting / styling
• Modify visual layout of tables or code blocks
• Remove spacing, dividers, or theme choices

---

My CLI Tool

Overview

Explain what the CLI does and who it is for. Example:

• Automates tasks
• Standardizes workflows
• Saves time and removes manual steps

---

Quick Start (Recommended)

Get productive in one command.

mytool init

This scaffolds a project with recommended defaults.

---

Use Cases / Applications (Highly Important)

Real workflows showing when and why to use the tool.

Goal / Scenario	Command to use
Create a project from template	mytool init --template node
Process files or a directory	mytool run ./src
Debug or inspect execution	mytool run ./src --verbose
Run using a custom configuration	mytool run --config ./mytool.json

---

Example: Scaffold a new project

mytool init --template node

Output (expected)

✔ Project created successfully at ./example-project

Next: See Configuration to customize behavior.

---

Installation

npm install -g my-cli-tool

Alternative installs:

• npx my-cli-tool@latest
• Homebrew (if available)

---

Usage

Syntax

mytool [command] [options] <input>

Global Help

mytool --help
mytool <command> --help

---

Commands

Command	Description
init	Create a new project scaffold
run	Execute the tool against input

init

mytool init [options]

Creates a new project structure with defaults.

Related: See the Quick Start and Use Cases section.

---

run

mytool run <input> [options]

Processes files, applies rules, and generates output.

Related: See Options / Flags and Examples.

---

Options / Flags

Option	Description	Default	Required
-h, --help	Show help output	—	No
-v, --verbose	Enable verbose logging	false	No
--config <path>	Path to config file	auto	No

Command-specific flags belong in the command’s section.

---

Examples

Basic

mytool input.txt

Verbose

mytool run input.txt --verbose

Custom configuration

mytool run ./src --config ./mytool.json

---

Configuration

Supports config files and environment variables.

Sample mytool.json

{
  "outputDir": "./dist",
  "rules": { "example": true }
}

Environment variables

Variable	Purpose	Example
MYTOOL_CONFIG	Overrides config path	/etc/mytool.json
MYTOOL_LOGLEVEL	Logging level	debug

Precedence

1. CLI flags
2. Environment variables
3. Config file

---

Output

• Outputs logs and files to ./dist by default
• Use --verbose to print detailed runtime information
• Output paths configurable via config file or flags

---

Exit Codes

Code	Meaning
0	Success
1	Recoverable issue
2	Fatal error / stop

---

Troubleshooting

Symptom	Likely Cause	Fix
command not found	PATH not updated	Restart terminal or reinstall
Permission denied on output dir	Write privileges	Change folder or run with sudo
Unknown flag --something	Older version	Run mytool --version and update

---

Contributing

1. Fork repo
2. npm install
3. PRs welcome — follow commit style & coding standards

---

License

Add your license here.

---

See Also

Links to:

• Related CLI tools
• API documentation
• Advanced guides
  https://gh.io/customagents/config

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[mnkiefer]

@copilot
According to what you just refactored, adapt the top navbar and sidebars:

• You are allowed to update/change top navbar links accordingly
• You are allowed to change sidebar section order and breakdown

[Copilot]

@copilot
According to what you just refactored, adapt the top navbar and sidebars:

• You are allowed to update/change top navbar links accordingly
  ...

Updated top navbar and sidebar navigation in commit 0eeca3f.

Top Navbar Changes:

• Quick Start → CLI → Guides → Reference → Status
• Replaced "Docs" with direct "Quick Start" link for faster onboarding
• Changed "Setup" to "CLI" for clearer purpose
• Added "Reference" for better workflow documentation discovery

Sidebar Changes:

• Created dedicated "CLI" section grouping Commands, VS Code Integration, and MCP Server
• Renamed "Workflows" → "Workflow Reference" for clarity
• Renamed "Applications" → "Examples" for better understanding
• Added "Troubleshooting" as dedicated section
• Promoted "Authoring" to top-level for visibility

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: node /home/REDACTED/.npm/_npx/aa98e6899c6baff3/node_modules/.bin/astro build (dns block)
  • Triggering command: node ./node_modules/.bin/astro build (dns block)
  • Triggering command: node ./node_modules/.bin/astro preview (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[Copilot]

Pull Request Overview

This PR restructures the documentation site's navigation and organization, moving from a "Get Started" focused hierarchy to a more intuitive structure with "Introduction", "Setup", "Guides", "Examples", and "Reference" sections. The changes improve discoverability and user experience by:

• Reorganizing sidebar navigation with clearer category names
• Updating internal links to match new paths
• Adding CSS fixes for right sidebar overflow issues
• Renaming pages for better clarity (e.g., "About" → "Overview", "Concepts" → "How It Works")

Key Changes

1. Navigation restructure: Moved from /get-started/ to /introduction/ and /setup/ paths with clearer categorization
2. Documentation improvements: Expanded CLI command documentation with use cases, examples, and troubleshooting sections
3. CSS fixes: Added overflow handling and word-wrapping for right sidebar to prevent layout issues
4. Content updates: Corrected file references and improved page descriptions throughout

Reviewed Changes

Copilot reviewed 38 out of 38 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/tests/mobile-responsive.spec.ts	Updated test URLs from old paths to new /introduction/overview/ path
docs/test-all-form-factors.mjs	Updated test URLs to match new documentation structure
docs/src/styles/custom.css	Added overflow and word-wrap fixes for right sidebar to prevent horizontal scrolling
docs/src/content/docs/troubleshooting/errors.md	Updated example workflow links to new paths under /examples/
docs/src/content/docs/status.mdx	Fixed Super Linter workflow filename reference
docs/src/content/docs/setup/quick-start.md	Updated internal links and improved page ordering
docs/src/content/docs/setup/cli.md	Massively expanded with use cases, examples, troubleshooting, and better structure
docs/src/content/docs/setup/agentic-authoring.mdx	Renamed title and updated sidebar order
docs/src/content/docs/reference/*.md	Removed redundant "Overview" section headings from multiple reference pages
docs/src/content/docs/introduction/*.mdx	Renamed pages (About→Overview, Concepts→How It Works) with updated descriptions
docs/src/content/docs/index.mdx	Updated all internal links to new paths and reorganized feature cards
docs/src/content/docs/guides/*.md	Updated titles, descriptions, and sidebar ordering for better organization
docs/src/content/docs/examples/**/*.md	Added new category index pages and "When to Use" sections for all example workflows
docs/src/components/CustomHeader.astro	Updated header navigation links to new paths
docs/src/components/CustomHead.astro	Added favicon link
docs/astro.config.mjs	Restructured entire sidebar navigation with manual item definitions
README.md	Updated documentation links to new paths

Comments suppressed due to low confidence (1)

docs/src/content/docs/introduction/overview.mdx:12

• Duplicate content: The sentence "GitHub Agentic Workflows transforms natural language markdown files into GitHub Actions that are executed by AI agents. Here's a simple example:" appears twice consecutively (lines 10 and 12). Remove one occurrence.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.