Enhance documentation and CLI help text formatting

CLAUDE.md

@@ -192,6 +192,67 @@ mypy toady/
 
 This guide ensures elegant, maintainable, and well-tested development of toady-cli.
 
+## Click CLI Help Text Formatting Best Practices
+
+### Key Principles
+1. **Use `\b` for preserved formatting** - Prevents Click from rewrapping specific sections
+2. **Structure with clear sections** - Use consistent headings like "Examples:", "Options:", "Behavior:"
+3. **Provide concrete examples** - Show real command usage, not abstract descriptions
+4. **Use consistent indentation** - 2 spaces for section content, 4 spaces for nested items
+5. **Keep sections focused** - Each `\b` block should be a logical unit
+
+### Formatting Template
+```python
+@click.command()
+def example():
+    """Brief command description.
+
+    Longer explanation of what the command does and its purpose.
+
+    \b
+    Behavior:
+      • Key behavior point 1
+      • Key behavior point 2
+      • Key behavior point 3
+
+    \b
+    Examples:
+      Basic usage:
+        command --option value
+
+      Advanced usage:
+        command --option1 value1 --option2 value2
+
+    \b
+    Error codes:
+      • error_type_1: Description of when this occurs
+      • error_type_2: Description of when this occurs
+    """
+```
+
+### Key Formatting Rules
+- **Use `\b` before each major section** to preserve formatting
+- **Use bullet points (•)** for lists instead of dashes or asterisks
+- **Indent consistently**: 2 spaces for section headers, 4 spaces for content
+- **Separate code examples** with proper indentation (4-6 spaces)
+- **Use quotes consistently**: Single quotes for command names, double quotes for strings
+- **Keep lines under 80 characters** when possible for terminal compatibility
+
+### Section Order
+1. Brief description (1-2 sentences)
+2. Detailed explanation
+3. Behavior/Operation modes
+4. Examples (most important section)
+5. Agent usage patterns (for automation)
+6. Validation/Safety notes
+7. Error codes
+
+### Common Issues and Solutions
+- **Text wrapping problems**: Use `\b` before each section that needs preserved formatting
+- **Inconsistent indentation**: Use 2 spaces for headers, 4+ spaces for code blocks
+- **Poor readability**: Break large sections into smaller focused blocks with `\b`
+- **Example clarity**: Always show complete, runnable command examples
+
 ## Git Commit and PR Guidelines
 
 ### Commit Messages and PR Descriptions

README.md

@@ -87,6 +87,19 @@ toady resolve --thread-id abc123def --undo
 toady resolve --all --pr 123
 ```
 
+### Smart PR Detection
+
+```bash
+# Toady automatically detects your PR context:
+# - Single PR: fetches automatically
+# - Multiple PRs: shows interactive selection
+# - No PRs: displays helpful message
+toady fetch
+
+# Override auto-detection for specific PR
+toady fetch --pr 123
+```
+
 ### Schema Validation
 
 ```bash
@@ -243,6 +256,38 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 For more detailed documentation, visit our [GitHub Wiki](https://github.com/tonyblank/toady-cli/wiki).
 
+## 🛮️ Troubleshooting
+
+### Authentication Issues
+
+- **Run:** `gh auth login`
+- **Verify:** `gh auth status`
+- **Ensure repo scope:** `gh auth login --scopes repo`
+
+### Common Errors
+
+- **"authentication_required":** GitHub CLI not logged in
+- **"pr_not_found":** PR doesn't exist or no repository access
+- **"rate_limit_exceeded":** Too many API calls, wait and retry
+- **"thread_not_found":** Invalid thread ID or thread was deleted
+
+### Debug Mode
+
+- **Set TOADY_DEBUG=1** or use `--debug` flag for detailed error info
+- **Use `--format pretty`** for human-readable output during testing
+
+### ID Issues
+
+- **Always use thread IDs** from `toady fetch` output
+- **Use `toady reply --help-ids`** for complete ID documentation
+- **Thread IDs** (PRRT_, PRT_, RT_) are more reliable than comment IDs
+
+### Rate Limiting
+
+- **Use `--limit` option** to reduce API calls
+- **Add delays** between operations in scripts
+- **Check limits:** `gh api rate_limit`
+
 ## 🐛 Bug Reports
 
 Found a bug? Please [open an issue](https://github.com/tonyblank/toady-cli/issues/new) with a clear description and steps to reproduce.

src/toady/cli.py

@@ -24,66 +24,68 @@ def cli(ctx: click.Context, debug: bool) -> None:
     """Toady - GitHub PR review management tool.
 
     Efficiently manage GitHub pull request code reviews from the command line.
-    Integrates with GitHub CLI (`gh`) to fetch, reply to, and resolve review threads.
-
-    PREREQUISITES:
-        • GitHub CLI (`gh`) must be installed and authenticated
-        • Run `gh auth login` if not already authenticated
-        • Ensure you have access to the target repository
-
-    CORE WORKFLOW:
-        1. Fetch review threads: `toady fetch --pr 123`
-        2. Reply to comments: `toady reply --id <thread_id> --body "Fixed!"`
-        3. Resolve threads: `toady resolve --thread-id <thread_id>`
-
-    AGENT-FRIENDLY USAGE:
-        • All commands output JSON by default for easy parsing
-        • Use `--format pretty` for human-readable output
-        • Thread and comment IDs are consistently formatted
-        • Error responses include structured error codes
-
-    COMMON PATTERNS:
-        Interactive workflow:
-            toady fetch              # Select PR interactively
-            toady reply --id <id> --body "Response"
-            toady resolve --thread-id <id>
-
-        Automated workflow:
-            toady fetch --pr 123 --format json | jq '.[] | .thread_id'
-            toady reply --id <id> --body "Automated response"
-            toady resolve --all --pr 123 --yes
-
-    For detailed command help: toady <command> --help
-    For examples and patterns: see examples.md in project repository
-
-    TROUBLESHOOTING:
-
-    Authentication Issues:
+    Integrates with GitHub CLI (gh) to fetch, reply to, and resolve review threads.
+
+    \b
+    Prerequisites:
+      • GitHub CLI (gh) must be installed and authenticated
+      • Run 'gh auth login' if not already authenticated
+      • Ensure you have access to the target repository
+
+    \b
+    Core workflow:
+      1. Fetch review threads: toady fetch
+      2. Reply to comments: toady reply --id <thread_id> --body "Fixed!"
+      3. Resolve threads: toady resolve --thread-id <thread_id>
+
+    \b
+    Agent-friendly usage:
+      • All commands output JSON by default for easy parsing
+      • Use --format pretty for human-readable output
+      • Thread and comment IDs are consistently formatted
+      • Error responses include structured error codes
+
+    \b
+    Common patterns:
+    \b
+      Interactive workflow:
+        toady fetch                              # Auto-detect PR
+        toady reply --id <id> --body "Response"
+        toady resolve --thread-id <id>
+    \b
+      Automated workflow:
+        toady fetch | jq '.[] | .thread_id'
+        toady reply --id <id> --body "Automated response"
+        toady resolve --all --pr 123 --yes
+    \b
+    Troubleshooting:
+    \b
+      Authentication issues:
         • Run: gh auth login
         • Verify: gh auth status
         • Ensure repo scope: gh auth login --scopes repo
-
-    Common Errors:
+    \b
+      Common errors:
         • "authentication_required": GitHub CLI not logged in
         • "pr_not_found": PR doesn't exist or no repository access
         • "rate_limit_exceeded": Too many API calls, wait and retry
         • "thread_not_found": Invalid thread ID or thread was deleted
-
-    Debug Mode:
+    \b
+      Debug mode:
         • Set TOADY_DEBUG=1 or use --debug flag for detailed error info
         • Use --format pretty for human-readable output during testing
-
-    ID Issues:
-        • Always use thread IDs from `toady fetch` output
-        • Use `toady reply --help-ids` for complete ID documentation
+    \b
+      ID issues:
+        • Always use thread IDs from 'toady fetch' output
+        • Use 'toady reply --help-ids' for complete ID documentation
         • Thread IDs (PRRT_, PRT_, RT_) are more reliable than comment IDs
-
-    Rate Limiting:
+    \b
+      Rate limiting:
         • Use --limit option to reduce API calls
         • Add delays between operations in scripts
         • Check limits: gh api rate_limit
 
-    For comprehensive examples: see examples.md
+    For detailed command help: toady <command> --help
     """
     ctx.ensure_object(dict)
     ctx.obj["debug"] = debug

src/toady/commands/fetch.py

@@ -54,69 +54,73 @@ def fetch(
 ) -> None:
     """Fetch review threads from a GitHub pull request.
 
-    Retrieves review threads (comments that require responses) from GitHub PRs.
-    Returns structured data containing thread IDs, comment content, authors, and
-    metadata.
-
-    BEHAVIOR:
-        • Without --pr: Shows interactive PR selection menu
-        • With --pr: Fetches from specified pull request number
-        • Default: Only unresolved threads (threads needing responses)
-        • With --resolved: Includes both resolved and unresolved threads
-
-    OUTPUT STRUCTURE (JSON):
-        [
-          {
-            "thread_id": "PRRT_kwDOO3WQIc5Rv3_r",     # Use for replies/resolve
-            "comment_id": "IC_kwDOABcD12MAAAABcDE3fg", # Alternative ID
-            "body": "Please fix this issue",
-            "author": "reviewer-username",
-            "created_at": "2023-01-01T12:00:00Z",
-            "is_resolved": false,
-            "pr_number": 123,
-            "file_path": "src/main.py",
-            "line_number": 42
-          }
-        ]
-
-    AGENT USAGE PATTERNS:
-        # Get unresolved threads for processing
+    Automatically detects and fetches review threads from GitHub PRs. When run
+    without arguments, intelligently selects the appropriate PR or prompts for
+    selection when multiple PRs exist.
+
+    \b
+    Behavior:
+      • Default: Auto-detects PR (single PR: fetches automatically, multiple: prompts)
+      • With --pr: Fetches from specified pull request number
+      • Default: Only unresolved threads (threads needing responses)
+      • With --resolved: Includes both resolved and unresolved threads
+
+    \b
+    Output structure (JSON):
+      [
+        {
+          "thread_id": "PRRT_kwDOO3WQIc5Rv3_r",     # Use for replies/resolve
+          "comment_id": "IC_kwDOABcD12MAAAABcDE3fg", # Alternative ID
+          "body": "Please fix this issue",
+          "author": "reviewer-username",
+          "created_at": "2023-01-01T12:00:00Z",
+          "is_resolved": false,
+          "pr_number": 123,
+          "file_path": "src/main.py",
+          "line_number": 42
+        }
+      ]
+
+    \b
+    Examples:
+      Auto-detect PR (recommended):
+        toady fetch
+
+      Human-readable output:
+        toady fetch --format pretty
+
+      Specific PR:
         toady fetch --pr 123
 
-        # Get all thread IDs for bulk operations
-        toady fetch --pr 123 | jq '.[].thread_id'
+      Include resolved threads:
+        toady fetch --resolved
 
-        # Find threads by author
-        toady fetch --pr 123 | jq '.[] | select(.author == "reviewer")'
+      Limit results:
+        toady fetch --limit 50
 
-    INTERACTIVE USAGE:
-        toady fetch --format pretty  # Human-readable output with colors
+      Pipeline with other tools:
+        toady fetch | jq '.[].thread_id' | xargs -I {} toady resolve --thread-id {}
 
-    EXAMPLES:
-        Basic fetch (JSON output):
-            toady fetch --pr 123
+    \b
+    Agent usage patterns:
+      # Get unresolved threads for processing
+      toady fetch
 
-        Human-readable output:
-            toady fetch --pr 123 --format pretty
+      # Get all thread IDs for bulk operations
+      toady fetch | jq '.[].thread_id'
 
-        Include resolved threads:
-            toady fetch --pr 123 --resolved
+      # Find threads by author
+      toady fetch | jq '.[] | select(.author == "reviewer")'
 
-        Limit results:
-            toady fetch --pr 123 --limit 50
+      # Target specific PR when multiple exist
+      toady fetch --pr 123
 
-        Interactive PR selection:
-            toady fetch
-
-        Pipeline with other tools:
-            toady fetch --pr 123 | jq '.[].thread_id' | \\
-                xargs -I {} toady resolve --thread-id {}
-
-    ERROR CODES:
-        • authentication_required: GitHub CLI not authenticated
-        • pr_not_found: Pull request doesn't exist or no access
-        • no_threads_found: PR has no review threads
-        • api_rate_limit: GitHub API rate limit exceeded
+    \b
+    Error codes:
+      • authentication_required: GitHub CLI not authenticated
+      • pr_not_found: Pull request doesn't exist or no access
+      • no_threads_found: PR has no review threads
+      • api_rate_limit: GitHub API rate limit exceeded
     """
     # Validate input parameters
     if pr_number is not None: