From 15c08136555151c94d31c4b40e4ea1800a4383a4 Mon Sep 17 00:00:00 2001
From: Alex Newman <thedotmack@gmail.com>
Date: Sun, 14 Dec 2025 15:30:12 -0500
Subject: [PATCH] docs: add bug report tool instructions to README and issue
 template
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add comprehensive documentation for the automated bug report generator:

README.md:
- New "Bug Reports" section with usage instructions
- Plugin directory paths for all platforms (macOS/Linux/Windows)
- Feature highlights and command options
- Positioned between Troubleshooting and Contributing sections

.github/ISSUE_TEMPLATE/bug_report.md:
- Prominently feature automated bug report tool as recommended approach
- Include platform-specific plugin directory paths
- Add labels "bug, needs-triage" by default
- Provide fallback manual bug report template
- Document tool features and privacy options

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 .github/ISSUE_TEMPLATE/bug_report.md | 64 +++++++++++++++++++++++++---
 README.md                            | 31 ++++++++++++++
 2 files changed, 90 insertions(+), 5 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index 0ffb0ff4..2314b658 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -1,14 +1,68 @@
 ---
 name: Bug report
-about: Create a report to help us improve
+about: Use the automated bug report tool for best results
 title: ''
-labels: ''
+labels: 'bug, needs-triage'
 assignees: ''
 
 ---
 
-⏺ The worker logs are at:
+## ⚡ Quick Bug Report (Recommended)
 
-  ~/.claude-mem/logs/worker-YYYY-MM-DD.log
+**Use the automated bug report generator** for comprehensive diagnostics:
 
-  For example: ~/.claude-mem/logs/worker-2025-12-14.log
+```bash
+# Navigate to the plugin directory
+cd ~/.claude/plugins/marketplaces/thedotmack
+
+# Run the bug report tool
+npm run bug-report
+```
+
+**Plugin Paths:**
+- **macOS/Linux**: `~/.claude/plugins/marketplaces/thedotmack`
+- **Windows**: `%USERPROFILE%\.claude\plugins\marketplaces\thedotmack`
+
+**Features:**
+- 🌎 Auto-translates any language to English
+- 📊 Collects all diagnostics automatically
+- 🤖 AI-formatted professional issue
+- 🔒 Privacy-safe (paths sanitized, `--no-logs` option)
+- 🌐 Auto-opens GitHub with pre-filled issue
+
+---
+
+## 📝 Manual Bug Report
+
+If you prefer to file manually or can't access the plugin directory:
+
+### Bug Description
+A clear description of what the bug is.
+
+### Steps to Reproduce
+1. Go to '...'
+2. Click on '...'
+3. See error
+
+### Expected Behavior
+What you expected to happen.
+
+### Environment
+- **Claude-mem version**:
+- **Claude Code version**:
+- **OS**:
+- **Platform**:
+
+### Logs
+Worker logs are located at:
+- **Path**: `~/.claude-mem/logs/worker-YYYY-MM-DD.log`
+- **Example**: `~/.claude-mem/logs/worker-2025-12-14.log`
+
+Please paste relevant log entries (last 50 lines or error messages):
+
+```
+[Paste logs here]
+```
+
+### Additional Context
+Any other context about the problem.
diff --git a/README.md b/README.md
index 9e0fb589..6ac5cb9e 100644
--- a/README.md
+++ b/README.md
@@ -404,6 +404,37 @@ See [Troubleshooting Guide](https://docs.claude-mem.ai/troubleshooting) for comp
 
 ---
 
+## Bug Reports
+
+**Automated Bug Report Generator** - Create comprehensive bug reports with one command:
+
+```bash
+# From the plugin directory
+cd ~/.claude/plugins/marketplaces/thedotmack
+npm run bug-report
+```
+
+The bug report tool will:
+- 🌎 **Auto-translate** - Write in ANY language, automatically translates to English
+- 📊 **Collect diagnostics** - Gathers versions, platform info, worker status, logs, and configuration
+- 📝 **Interactive prompts** - Guides you through describing the issue with multiline support
+- 🤖 **AI formatting** - Uses Claude Agent SDK to generate professional GitHub issues
+- 🔒 **Privacy-safe** - Auto-sanitizes paths, optional `--no-logs` flag
+- 🌐 **Auto-submit** - Opens GitHub with pre-filled title and body
+
+**Plugin Directory Paths:**
+- **macOS/Linux**: `~/.claude/plugins/marketplaces/thedotmack`
+- **Windows**: `%USERPROFILE%\.claude\plugins\marketplaces\thedotmack`
+
+**Options:**
+```bash
+npm run bug-report --no-logs    # Skip logs for privacy
+npm run bug-report --verbose    # Show all diagnostics
+npm run bug-report --help       # Show help
+```
+
+---
+
 ## Contributing
 
 Contributions are welcome! Please: