Troubleshooting diagnostics doc

CONTRIBUTING.md

@@ -9,23 +9,7 @@ We welcome pull requests for general contributions! If you have a larger new fea
 
 --- 
 
-## 🎉 Hacktoberfest 2025 🎉
-
-`goose` is a participating in Hacktoberfest 2025! We’re so excited for your contributions, and have created a wide variety of issues so that anyone can contribute. Whether you're a seasoned developer or a first-time open source contributor, there's something for everyone.
-
-### Here's how you can get started:
-
-1. Read the [code of conduct](https://github.com/block/.github/blob/main/CODE_OF_CONDUCT.md).
-2. Skim the quick AI contribution tips below (and see the [full Responsible AI-Assisted Coding Guide](./ai-assisted-coding-guide.md) for details).
-3. Choose a task from this project's Hacktoberfest issues in our [Project Hub](https://github.com/block/goose/issues/4705). Each issue has the 🏷️ `hacktoberfest` label.
-4. Comment ".take" on the corresponding issue to get assigned the task.
-5. Fork the repository and create a new branch for your work.
-6. Make your changes and submit a pull request.
-7. Wait for review and address any feedback.
-
----
-
-### 🤖 Quick Responsible AI Tips
+## 🤖 Quick Responsible AI Tips
 
 If you use Goose, Copilot, Claude, or other AI tools to help with your PRs:  
 
@@ -55,34 +39,6 @@ If you use Goose, Copilot, Claude, or other AI tools to help with your PRs:
 
 ---
 
-### 🏆 Leaderboard & Prizes
-
-Every hacktoberfest PR and contribution will earn you points on our [leaderboard](https://github.com/block/goose/issues/4775). Those who end up in the top 20 participants with the most points by the end of October will earn exclusive swag and LLM credits! As you have issues merged, here is a brief explanation on how our automatic points system works.
-
-#### Point System
-
-| Weight | Points Awarded | Description |
-|---------|-------------|-------------|
-| 🐭 **Small** | 5 points | For smaller tasks that take limited time to complete and/or don't require any product knowledge. |
-| 🐰 **Medium** | 10 points | For average tasks that take additional time to complete and/or require some product knowledge. |
-| 🐂 **Large** | 15 points | For heavy tasks that takes lots of time to complete and/or possibly require deep product knowledge. |
-
-#### Prizes You Can Win
-
-- **Top 5**: $100 gift card to our [brand new goose swag shop](https://www.gooseswag.xyz/) and $100 of LLM credits!
-- **Top 6-10**: $50 gift cards for goose swag shop and $50 of LLM credits!
-- **Top 11-20**: $25 of LLM credits!
-
-Keep an eye on your progress via our [Leaderboard](https://github.com/block/goose/issues/4775).
-
-### 👩‍ Need help?
-
-Need help or have questions? Feel free to reach out by connecting with us in our [Discord community](https://discord.gg/goose-oss) to get direct help from our team in the `#hacktoberfest` project channel.
-
-Happy contributing!
-
----
-
 ## Prerequisites
 
 goose includes rust binaries alongside an electron app for the GUI. To work

README.md

@@ -17,20 +17,6 @@ _a local, extensible, open source AI agent that automates engineering tasks_
 </p>
 </div>
 
-## 🎉 Hacktoberfest 2025 🎉
-
-`goose` is a participating project in Hacktoberfest 2025! We’re so excited for your contributions, and have created a wide variety of issues so that anyone can contribute. Whether you're a seasoned developer or a first-time open source contributor, there's something for everyone.
-
-### To get started:
-1. Read the [contributing guide](https://github.com/block/goose/blob/main/CONTRIBUTING.md).
-2. Read the [code of conduct](https://github.com/block/.github/blob/main/CODE_OF_CONDUCT.md).
-3. Read the [full Responsible AI-Assisted Coding Guide](./ai-assisted-coding-guide.md).
-4. Choose a task from this project's Hacktoberfest issues in our [Project Hub](https://github.com/block/goose/issues/4705) and follow the instructions. Each issue has the 🏷️ `hacktoberfest` label.
-
-Have questions? Connecting with us in our [Discord community](https://discord.gg/goose-oss) in the `#hacktoberfest` project channel.
-
----
-
 goose is your on-machine AI agent, capable of automating complex development tasks from start to finish. More than just code suggestions, goose can build entire projects from scratch, write and execute code, debug failures, orchestrate workflows, and interact with external APIs - _autonomously_.
 
 Whether you're prototyping an idea, refining existing code, or managing intricate engineering pipelines, goose adapts to your workflow and executes tasks with precision.
@@ -44,8 +30,13 @@ Designed for maximum flexibility, goose works with any LLM and supports multi-mo
 - [Installation](https://block.github.io/goose/docs/getting-started/installation)
 - [Tutorials](https://block.github.io/goose/docs/category/tutorials)
 - [Documentation](https://block.github.io/goose/docs/category/getting-started)
+- [Responsible AI-Assisted Coding Guide](https://github.com/block/goose/blob/main/ai-assisted-coding-guide.md)
 - [Governance](https://github.com/block/goose/blob/main/GOVERNANCE.md)
 
+## Need Help?
+- [Diagnostics & Reporting](https://block.github.io/goose/docs/troubleshooting/diagnostics-and-reporting)
+- [Known Issues](https://block.github.io/goose/docs/troubleshooting/known-issues)
+
 # a little goose humor 🦢
 
 > Why did the developer choose goose as their AI agent?

documentation/docs/getting-started/installation.md

@@ -44,7 +44,7 @@ import { PanelLeft } from 'lucide-react';
 
           Ensure the `~/.config` directory has read and write access.
 
-          Goose needs this access to create the log directory and file. Once permissions are granted, the app should load correctly. For steps on how to do this, refer to the  [Troubleshooting Guide](/docs/troubleshooting.md#macos-permission-issues)
+          Goose needs this access to create the log directory and file. Once permissions are granted, the app should load correctly. For steps on how to do this, refer to the  [Known Issues Guide](/docs/troubleshooting/known-issues#macos-permission-issues)
           :::
         </div>
       </TabItem>

documentation/docs/getting-started/using-extensions.md

@@ -12,7 +12,7 @@ Extensions are add-ons that provide a way to extend the functionality of Goose b
 Extensions are based on the [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol), so you can connect
 Goose to a wide ecosystem of capabilities.
 
-Goose automatically checks external extensions for known malware before activation. If a malicious package is detected, the [extension will be blocked](/docs/troubleshooting#malicious-package-detected) with a clear error message.
+Goose automatically checks external extensions for known malware before activation. If a malicious package is detected, the [extension will be blocked](/docs/troubleshooting/known-issues#malicious-package-detected) with a clear error message.
 
 :::tip Tutorials
 Check out the [step-by-step tutorials](/docs/category/mcp-servers) for adding and using several Goose Extensions
@@ -108,7 +108,7 @@ You can also add any other [MCP Server](#mcp-servers) as a Goose extension, even
 Extensions can be installed directly via the [extensions directory][extensions-directory], CLI, or UI.
 
 :::warning Airgapped Environments
-If you're in a corporate or airgapped environment and extensions fail to activate, see [Airgapped/Offline Environments](/docs/troubleshooting#airgappedoffline-environment-issues) for workarounds.
+If you're in a corporate or airgapped environment and extensions fail to activate, see [Airgapped/Offline Environments](/docs/troubleshooting/known-issues#airgappedoffline-environment-issues) for workarounds.
 :::
 
 ### MCP Servers

documentation/docs/guides/goose-cli-commands.md

@@ -207,6 +207,45 @@ goose session export --path ./my-session.jsonl --output exported.md
 
 ---
 
+#### session diagnostics [options]
+Generate a comprehensive diagnostics bundle for troubleshooting issues with a specific session.
+
+**Options:**
+- **`-i, --id <id>`**: Generate diagnostics for a specific session by ID
+- **`-n, --name <name>`**: Generate diagnostics for a specific session by name
+- **`-o, --output <file>`**: Save diagnostics bundle to a specific file path (default: `diagnostics_{session_id}.zip`)
+
+**What's included:**
+- **System Information**: App version, operating system, architecture, and timestamp
+- **Session Data**: Complete conversation messages and history for the specified session
+- **Configuration Files**: Your [configuration files](/docs/guides/config-files) (if they exist)
+- **Log Files**: Recent application logs for debugging
+
+**Usage:**
+```bash
+# Generate diagnostics for a specific session by ID
+goose session diagnostics --id 20250305_113223
+
+# Generate diagnostics for a session by name
+goose session diagnostics --name my-project-session
+
+# Save diagnostics to a custom location
+goose session diagnostics --id 20250305_113223 --output /path/to/my-diagnostics.zip
+
+# Interactive selection (prompts you to choose a session)
+goose session diagnostics
+```
+
+:::warning Privacy Notice
+Diagnostics bundles contain your session messages and system information. If your session includes sensitive data (API keys, personal information, proprietary code), review the contents before sharing publicly.
+:::
+
+:::tip
+Generate diagnostics before reporting bugs to provide technical details that help with faster resolution. The ZIP file can be attached to GitHub issues or shared with support.
+:::
+
+---
+
 ### Task Execution
 
 #### run [options]

documentation/docs/guides/security/prompt-injection-detection.md

@@ -78,7 +78,7 @@ When in doubt, deny.
 Beyond prompt injection detection, goose automatically:
 - Warns you before running new or updated recipes
 - Warns you when importing recipes that contain invisible Unicode Tag Block characters
-- [Checks for known malware](/docs/troubleshooting#malicious-package-detected) when installing extensions for locally-run MCP servers
+- [Checks for known malware](/docs/troubleshooting/known-issues#malicious-package-detected) when installing extensions for locally-run MCP servers
 :::
 
 ### Configuring Detection Threshold

documentation/docs/guides/sessions/session-management.md

@@ -263,7 +263,7 @@ Search allows you to find specific content within sessions or find specific sess
         ```
 
         :::tip
-        While you can resume sessions using the commands above, we recommend creating new sessions for new tasks to reduce the chance of [doom spiraling](/docs/troubleshooting#stuck-in-a-loop-or-unresponsive).
+        While you can resume sessions using the commands above, we recommend creating new sessions for new tasks to reduce the chance of [doom spiraling](/docs/troubleshooting/known-issues#stuck-in-a-loop-or-unresponsive).
         :::
     </TabItem>
 </Tabs>

documentation/docs/guides/tips.md

@@ -54,4 +54,4 @@ Use [lead/worker model](/docs/tutorials/lead-worker/) to have goose use a "lead"
 Write [recipes](/docs/guides/recipes/session-recipes) that check your current state before acting, so they can be run multiple times without causing any errors or duplication. 
 
 ### Add Logging to Recipes
-Inlcude informative log messages in your recipes for each major step to make debugging and troubleshooting easier should something fail.
+Include informative log messages in your recipes for each major step to make debugging and troubleshooting easier should something fail.

documentation/docs/troubleshooting/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Troubleshooting",
+  "position": 40,
+  "description": "Get help, report issues, and troubleshoot common problems with goose."
+}

documentation/docs/troubleshooting/diagnostics-and-reporting.md

@@ -0,0 +1,149 @@
+---
+title: Diagnostics and Reporting
+sidebar_label: Diagnostics and Reporting
+description: Use built-in diagnostics, report bugs, and request new features with goose's integrated support tools.
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import { PanelLeft, Bug, MessageSquarePlus, Download } from 'lucide-react';
+
+goose provides several built-in features to help you get support, report issues, and request new functionality. This guide covers the diagnostics system, bug reporting, and feature request tools.
+
+| Feature | Purpose | Location | Output |
+|---------|---------|----------|---------|
+| **Diagnostics** | Generate troubleshooting data | Chat input toolbar | ZIP file with system info, logs, and session data |
+| **Report a Bug** | Submit bug reports | Settings → Help & feedback | Opens GitHub issue template |
+| **Request a Feature** | Suggest new features | Settings → Help & feedback | Opens GitHub issue template |
+
+## Diagnostics System
+
+The diagnostics feature creates a comprehensive troubleshooting bundle that includes system information, session data, configuration files, and recent logs. This is invaluable for debugging issues or getting technical support.
+
+### Generating Diagnostics
+
+<Tabs groupId="interface">
+  <TabItem value="ui" label="goose Desktop" default>
+    1. In an active chat session, look for the <Bug className="inline" size={16} /> icon in the bottom toolbar
+    2. Click the diagnostics button
+    3. Review the information in the modal about what data will be collected
+    4. Click `Download` to generate and save the diagnostics bundle
+    5. The ZIP file will be saved as `diagnostics_{session_id}.zip`
+
+    :::tip
+    The diagnostics button is only available when you have an active session, as it needs a session ID to generate the bundle.
+    :::
+  </TabItem>
+  <TabItem value="cli" label="goose CLI">
+    Use the session diagnostics command to generate a troubleshooting bundle. For complete details and all available options, see the [CLI Commands guide](/docs/guides/goose-cli-commands#session-diagnostics-options).
+
+    ```sh
+    # Generate diagnostics for a specific session
+    goose session diagnostics --id <session_id>
+
+    # Interactive selection (prompts you to choose a session)
+    goose session diagnostics
+
+    # Save to a custom location
+    goose session diagnostics --id <session_id> --output /path/to/diagnostics.zip
+    ```
+
+    To find your session ID, first list available sessions:
+
+    ```sh
+    goose session list
+    ```
+
+    Example output:
+    ```
+    Available sessions:
+    abc123def - My coding session - 2024-01-15 14:30:22
+    xyz789ghi - Documentation work - 2024-01-15 10:15:45
+    ```
+  </TabItem>
+</Tabs>
+
+### Using Diagnostics Data
+
+The diagnostics ZIP file contains several folders:
+
+```
+diagnostics_abc123def.zip
+├── logs/
+│   ├── goose-2024-01-15.jsonl
+│   ├── goose-2024-01-14.jsonl
+│   └── ...
+├── session.json          # Your session messages
+├── config.yaml          # Configuration files (if they exist)
+└── system.txt           # System information
+```
+
+**When to generate diagnostics:**
+- Experiencing crashes or unexpected behavior
+- Getting error messages you don't understand
+- Performance issues or slow responses
+- Before reporting bugs to include technical details
+
+**What's included in diagnostics:**
+- **System Information**: App version, operating system, architecture, and timestamp
+- **Session Data**: Your current conversation messages and history
+- **Configuration Files**: Your [configuration files](/docs/guides/config-files) (if they exist)
+- **Log Files**: Recent application logs for debugging
+
+:::warning Privacy Notice
+Diagnostics bundles contain your session messages and system information. If your session includes sensitive data (API keys, personal information, proprietary code), review the contents before sharing publicly.
+:::
+
+## Bug Reports
+
+The bug report feature opens a structured GitHub issue template to help you provide all necessary information for effective bug reporting.
+
+### Creating Bug Reports
+
+<Tabs groupId="interface">
+  <TabItem value="ui" label="goose Desktop" default>
+    1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
+    2. Click `Settings` in the sidebar
+    3. Scroll down to the `Help & feedback` section
+    4. Click `Report a Bug`
+    5. This opens GitHub in your browser with a pre-filled bug report template
+  </TabItem>
+  <TabItem value="cli" label="goose CLI">
+    For CLI users, navigate directly to the GitHub repository:
+
+    ```
+    https://github.com/block/goose/issues/new?template=bug_report.md
+    ```
+  </TabItem>
+</Tabs>
+
+## Feature Requests
+
+The feature request system helps you suggest improvements and new functionality for goose.
+
+### Submitting Feature Requests
+
+<Tabs groupId="interface">
+  <TabItem value="ui" label="goose Desktop" default>
+    1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
+    2. Click `Settings` in the sidebar
+    3. Scroll down to the `Help & feedback` section
+    4. Click `Request a Feature`
+    5. This opens GitHub in your browser with a feature request template
+  </TabItem>
+  <TabItem value="cli" label="goose CLI">
+    Navigate directly to the GitHub repository:
+
+    ```
+    https://github.com/block/goose/issues/new?template=feature_request.md
+    ```
+  </TabItem>
+</Tabs>
+
+## Additional Debugging
+
+For issues not resolved by diagnostics:
+
+- **[Session and System Logs](/docs/guides/logs)**: View detailed logs for debugging individual sessions
+- **[Telemetry Export](/docs/guides/environment-variables#observability)**: Configure telemetry for performance analysis and production monitoring
+

documentation/docs/troubleshooting/index.mdx

@@ -0,0 +1,50 @@
+---
+title: Troubleshooting
+hide_title: true
+description: Get help, report issues, and troubleshoot common problems with goose.
+---
+
+import Card from '@site/src/components/Card';
+import styles from '@site/src/components/Card/styles.module.css';
+
+<h1 className={styles.pageTitle}>Troubleshooting</h1>
+<p className={styles.pageDescription}>
+  Get help when you need it, report bugs, request features, and find solutions to common issues. goose provides built-in diagnostics and direct links to our support channels.
+</p>
+
+<div className={styles.categorySection}>
+  <h2 className={styles.categoryTitle}>🛠️ Getting Help</h2>
+  <div className={styles.cardGrid}>
+    <Card 
+      title="Diagnostics and Reporting"
+      description="Use built-in diagnostics, report bugs, and request new features. Includes step-by-step guides for generating troubleshooting data."
+      link="/docs/troubleshooting/diagnostics-and-reporting"
+    />
+    <Card 
+      title="Known Issues"
+      description="Comprehensive troubleshooting guide covering common problems, error messages, and platform-specific issues with step-by-step solutions."
+      link="/docs/troubleshooting/known-issues"
+    />
+    <Card 
+      title="Logs"
+      description="Learn how to access and interpret goose session logs and system logs for debugging and troubleshooting purposes."
+      link="/docs/guides/logs"
+    />
+  </div>
+</div>
+
+<div className={styles.categorySection}>
+  <h2 className={styles.categoryTitle}>💬 Community Support</h2>
+  <div className={styles.cardGrid}>
+    <Card 
+      title="Discord Community"
+      description="Join our active Discord server for real-time help, discussions, and community support from goose users and maintainers."
+      link="https://discord.gg/goose-oss"
+    />
+    <Card 
+      title="GitHub Issues"
+      description="Browse existing issues, contribute to discussions, or create new bug reports and feature requests on our GitHub repository."
+      link="https://github.com/block/goose/issues"
+    />
+  </div>
+</div>