docs: enhance CLI help text with examples and context

Add comprehensive help text to major commands with:
- Real-world examples with actual command syntax
- Clear descriptions of what users will see
- Related commands and tools
- Setup instructions (for mcp)
- Storage structure explanation (for storage)

Commands Enhanced:
- dev github --help    Examples, related MCP tool info
- dev mcp --help       Setup steps, 9 available tools list
- dev stats --help     What statistics are shown
- dev storage --help   Storage location and structure

Impact:
- Improves discoverability without external docs
- Always available (no website needed)
- Context-aware help for each command
- Zero maintenance (lives with code)

Completes Option 1 from CLI documentation strategy.
Next: CLI Quickstart page (separate PR)

Author: prosdev

AGENTS.md

@@ -167,7 +167,7 @@ Command-line interface for repository indexing and MCP setup.
 - `dev mcp install [--cursor]` - Install MCP integration
 - `dev mcp uninstall [--cursor]` - Remove MCP integration
 - `dev mcp list [--cursor]` - List MCP servers
-- `dev gh index` - Index GitHub issues/PRs
+- `dev github index` - Index GitHub issues/PRs
 
 ### @lytics/dev-agent-subagents
 
@@ -391,7 +391,7 @@ pnpm dev                                  # Watch mode
 pnpm lint && pnpm typecheck              # Quality checks
 dev index .                              # Index repository
 dev mcp install --cursor                 # Install for Cursor
-dev gh index                             # Index GitHub
+dev github index                             # Index GitHub
 
 # Debugging
 dev mcp start --verbose                  # Verbose MCP server

CHANGELOG.md

@@ -50,7 +50,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 - Memory leaks from unbounded array growth
 - Zombie MCP server processes when Cursor closes
-- GitHub index not reloading after `dev gh index`
+- GitHub index not reloading after `dev github index`
 - STDIO transport not handling stdin closure properly
 
 ### Security
@@ -104,7 +104,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
    ```bash
    cd /path/to/repo
    dev index .
-   dev gh index  # If using GitHub integration
+   dev github index  # If using GitHub integration
    ```
 
 3. Reinstall MCP integration:

README.md

@@ -244,8 +244,8 @@ dev git search "authentication fix"   # Semantic search over commits
 dev git stats                         # Show indexed commit count
 
 # GitHub integration
-dev gh index                          # Index issues and PRs (also done by dev index)
-dev gh search "authentication bug"    # Semantic search
+dev github index                          # Index issues and PRs (also done by dev index)
+dev github search "authentication bug"    # Semantic search
 
 # View statistics
 dev stats

TROUBLESHOOTING.md

@@ -350,7 +350,7 @@ dev index .
 
 ## GitHub Integration
 
-### `dev gh index` fails
+### `dev github index` fails
 
 **Common causes:**
 
@@ -386,7 +386,7 @@ Failed to fetch issues: spawnSync /bin/sh ENOBUFS
    dev index --gh-limit 100
 
    # For dedicated GitHub indexing
-   dev gh index --limit 100
+   dev github index --limit 100
    ```
 
 2. **Adjust limit based on repository size:**
@@ -397,10 +397,10 @@ Failed to fetch issues: spawnSync /bin/sh ENOBUFS
 3. **Index in batches:**
    ```bash
    # Index open items only (usually smaller)
-   dev gh index --state open --limit 500
+   dev github index --state open --limit 500
 
    # Then index closed items with lower limit
-   dev gh index --state closed --limit 100
+   dev github index --state closed --limit 100
    ```
 
 **Technical details:**
@@ -424,10 +424,10 @@ Failed to fetch issues: spawnSync /bin/sh ENOBUFS
 
 3. **Re-index:**
    ```bash
-   dev gh index
+   dev github index
    ```
 
-**Note:** The `dev_gh` tool automatically reloads when you run `dev gh index` - no restart needed!
+**Note:** The `dev_gh` tool automatically reloads when you run `dev github index` - no restart needed!
 
 ### GitHub index is stale
 
@@ -438,13 +438,13 @@ Use dev_health tool - warns if GitHub index >24h old
 
 **Solution:**
 ```bash
-dev gh index
+dev github index
 ```
 
 **Automation (optional):**
 ```bash
 # Add to crontab for daily updates
-0 9 * * * cd /path/to/repo && dev gh index
+0 9 * * * cd /path/to/repo && dev github index
 ```
 
 ---
@@ -534,7 +534,7 @@ Use dev_health tool to check component status
 ```bash
 # Re-index everything
 dev index .
-dev gh index
+dev github index
 
 # Restart MCP server
 ```
@@ -689,7 +689,7 @@ rm -rf ~/.dev-agent/indexes/*
 # Re-index your repositories
 cd /path/to/your/repo
 dev index .
-dev gh index
+dev github index
 
 # Reinstall MCP
 dev mcp install --cursor  # or without --cursor for Claude Code
@@ -755,7 +755,7 @@ npm update -g dev-agent
 # Re-index repositories (recommended)
 cd /path/to/your/repo
 dev index .
-dev gh index
+dev github index
 
 # Restart AI tool
 ```
@@ -944,7 +944,7 @@ dev index .
 
 **GitHub Index Stale:**
 ```bash
-dev gh index
+dev github index
 ```
 
 **Repository Not Accessible:**

WORKFLOW.md

@@ -20,7 +20,7 @@ git checkout main
 git pull origin main
 
 # Use GitHub Context to find what to work on next
-dev gh search "state:open label:\"Epic: MCP Integration\"" --type issue
+dev github search "state:open label:\"Epic: MCP Integration\"" --type issue
 
 # Or use gh CLI directly
 gh issue list --milestone "Epic #3: MCP Integration" --state open

examples/README.md

@@ -195,7 +195,7 @@ dev_gh:
 
 **First, index GitHub:**
 ```bash
-dev gh index
+dev github index
 ```
 
 ---
@@ -339,7 +339,7 @@ dev_health:
 dev index .
 
 # After new issues/PRs
-dev gh index
+dev github index
 
 # Check health
 dev_health

packages/cli/CHANGELOG.md

@@ -98,7 +98,7 @@
 
   **Indexer Logging**
 
-  - Add `--verbose` flag to `dev index`, `dev git index`, `dev gh index`
+  - Add `--verbose` flag to `dev index`, `dev git index`, `dev github index`
   - Progress spinner shows actual counts: `Embedding 4480/49151 documents (9%)`
   - Structured logging with kero logger
 

packages/cli/src/cli.ts

@@ -6,8 +6,8 @@ import { cleanCommand } from './commands/clean.js';
 import { compactCommand } from './commands/compact.js';
 import { dashboardCommand } from './commands/dashboard.js';
 import { exploreCommand } from './commands/explore.js';
-import { ghCommand } from './commands/gh.js';
 import { gitCommand } from './commands/git.js';
+import { githubCommand } from './commands/github.js';
 import { indexCommand } from './commands/index.js';
 import { initCommand } from './commands/init.js';
 import { mcpCommand } from './commands/mcp.js';
@@ -35,7 +35,7 @@ program.addCommand(indexCommand);
 program.addCommand(searchCommand);
 program.addCommand(exploreCommand);
 program.addCommand(planCommand);
-program.addCommand(ghCommand);
+program.addCommand(githubCommand);
 program.addCommand(gitCommand);
 program.addCommand(updateCommand);
 program.addCommand(statsCommand);

packages/cli/src/commands/gh.ts packages/cli/src/commands/github.tspackages/cli/src/commands/gh.ts renamed to packages/cli/src/commands/github.ts

@@ -51,8 +51,21 @@ async function createGitHubIndexer(): Promise<GitHubIndexer> {
   });
 }
 
-export const ghCommand = new Command('gh')
-  .description('GitHub context commands (index issues/PRs, search, get context)')
+export const githubCommand = new Command('github')
+  .description('GitHub issues and pull requests')
+  .addHelpText(
+    'after',
+    `
+Examples:
+  $ dev github index                    Index all issues/PRs for semantic search
+  $ dev github search "auth bug"        Find issues by meaning, not keywords
+  $ dev github stats                    Show indexing statistics
+  $ dev github context 42               Get full details for issue #42
+
+Related:
+  dev_gh         MCP tool for AI assistants (same functionality)
+`
+  )
   .addCommand(
     new Command('index')
       .description('Index GitHub issues and PRs')

packages/cli/src/commands/mcp.ts

@@ -46,6 +46,25 @@ import {
 
 export const mcpCommand = new Command('mcp')
   .description('MCP (Model Context Protocol) server integration')
+  .addHelpText(
+    'after',
+    `
+Examples:
+  $ dev mcp install                     Install for Claude Code
+  $ dev mcp install --cursor            Install for Cursor IDE
+  $ dev mcp list --cursor               Show configured MCP servers
+  $ dev mcp start                       Start MCP server (usually automatic)
+
+Setup:
+  1. Index your repository first: dev index
+  2. Install MCP integration: dev mcp install --cursor
+  3. Restart Cursor to activate
+
+Available Tools (9):
+  dev_search, dev_status, dev_plan, dev_explore, dev_gh,
+  dev_health, dev_refs, dev_map, dev_history
+`
+  )
   .addCommand(
     new Command('start')
       .description('Start MCP server for current repository')