docs: edit troubleshooting

5 files changed, 56 insertions, 39 deletions

diff --git a/README.md b/README.md
index cf2aa6fe2..aba1879f6 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@
 </p>
 <p align="center">AI coding agent, built for the terminal.</p>
 <p align="center">
-  <a href="https://discord.gg/opencode"><img alt="Discord" src="https://img.shields.io/discord/1391832426048651334?style=flat-square&label=discord" /></a>
+  <a href="https://opencode.ai/discord"><img alt="Discord" src="https://img.shields.io/discord/1391832426048651334?style=flat-square&label=discord" /></a>
   <a href="https://www.npmjs.com/package/opencode-ai"><img alt="npm" src="https://img.shields.io/npm/v/opencode-ai?style=flat-square" /></a>
   <a href="https://github.com/sst/opencode/actions/workflows/publish.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/sst/opencode/publish.yml?style=flat-square&branch=dev" /></a>
 </p>
diff --git a/packages/web/astro.config.mjs b/packages/web/astro.config.mjs
index 4263be7ae..713e09a11 100644
--- a/packages/web/astro.config.mjs
+++ b/packages/web/astro.config.mjs
@@ -84,7 +84,7 @@ export default defineConfig({
     }),
   ],
   redirects: {
-    "/discord": "https://discord.com/invite/opencode",
+    "/discord": "https://discord.gg/opencode",
   },
 })
 
diff --git a/packages/web/config.mjs b/packages/web/config.mjs
index 5e4c571d2..bb1ec003b 100644
--- a/packages/web/config.mjs
+++ b/packages/web/config.mjs
@@ -6,7 +6,7 @@ export default {
     : `https://${stage}.opencode.ai`,
   socialCard: "https://social-cards.sst.dev",
   github: "https://github.com/sst/opencode",
-  discord: "https://discord.gg/opencode",
+  discord: "https://opencode.ai/discord",
   headerLinks: [
     { name: "Home", url: "/" },
     { name: "Docs", url: "/docs/" },
diff --git a/packages/web/src/content/docs/docs/config.mdx b/packages/web/src/content/docs/docs/config.mdx
index 78552d415..a01589be6 100644
--- a/packages/web/src/content/docs/docs/config.mdx
+++ b/packages/web/src/content/docs/docs/config.mdx
@@ -63,55 +63,63 @@ You can configure the theme you want to use in your opencode config through the
 
 ---
 
-### Keybinds
+### Logging
 
-You can customize your keybinds through the `keybinds` option.
+Logs are written to:
+
+- **macOS/Linux**: `~/.local/share/opencode/log/`
+- **Windows**: `%APPDATA%\opencode\log\`
+
+You can configure the minimum log level through the `log_level` option.
 
 ```json title="opencode.json"
 {
   "$schema": "https://opencode.ai/config.json",
-  "keybinds": {}
+  "log_level": "INFO"
 }
 ```
 
-[Learn more here](/docs/keybinds).
+With the following options:
+
+| Level | Description |
+| ----- | ----------- |
+| `DEBUG` | All messages including debug information |
+| `INFO` | Informational messages and above |
+| `WARN` | Warnings and errors only |
+| `ERROR` | Errors only |
+
+The **default** log level is `INFO`. If you are running opencode locally in
+development mode it's set to `DEBUG`.
 
 ---
 
-### MCP servers
+### Keybinds
 
-You can configure MCP servers you want to use through the `mcp` option.
+You can customize your keybinds through the `keybinds` option.
 
 ```json title="opencode.json"
 {
   "$schema": "https://opencode.ai/config.json",
-  "mcp": {}
+  "keybinds": {}
 }
 ```
 
-[Learn more here](/docs/mcp-servers).
+[Learn more here](/docs/keybinds).
 
 ---
 
-### Logging
+### MCP servers
 
-You can configure the minimum log level through the `log_level` option. This controls which log messages are written to the log files.
+You can configure MCP servers you want to use through the `mcp` option.
 
 ```json title="opencode.json"
 {
   "$schema": "https://opencode.ai/config.json",
-  "log_level": "INFO"
+  "mcp": {}
 }
 ```
 
-Available log levels are:
-
-- `DEBUG` - All messages including debug information
-- `INFO` - Informational messages and above (default)
-- `WARN` - Warnings and errors only
-- `ERROR` - Errors only
-
-The default log level is `INFO` in production and `DEBUG` in development mode.
+[Learn more here](/docs/mcp-servers).
 
 ---
 
diff --git a/packages/web/src/content/docs/docs/troubleshooting.mdx b/packages/web/src/content/docs/docs/troubleshooting.mdx
index 1640d6343..3ab6144ae 100644
--- a/packages/web/src/content/docs/docs/troubleshooting.mdx
+++ b/packages/web/src/content/docs/docs/troubleshooting.mdx
@@ -3,9 +3,14 @@ title: Troubleshooting
 description: Common issues and how to resolve them.
 ---
 
-## Logs
+To debug any issues with opencode, you can check the logs or the session data
+that it stores locally.
 
-opencode writes detailed logs that can help diagnose issues. Log files are stored in:
+---
+
+### Logs
+
+Log files are written to:
 
 - **macOS/Linux**: `~/.local/share/opencode/log/`
 - **Windows**: `%APPDATA%\opencode\log\`
@@ -16,7 +21,7 @@ You can configure the log level in your [config file](/docs/config#logging) to g
 
 ---
 
-## Storage
+### Storage
 
 opencode stores session data and other application data on disk at:
 
@@ -25,9 +30,11 @@ opencode stores session data and other application data on disk at:
 
 This directory contains:
 
-- `auth.json` - Authentication data (e.g., API keys, OAuth tokens)
+- `auth.json` - Authentication data like API keys, OAuth tokens
 - `log/` - Application logs
-- `project/` - Project-specific data (e.g., session and message data)
+- `project/` - Project-specific data like session and message data
+  - If the project is within a Git repo, it is stored in `./<project-slug>/storage/`
+  - If it is not a Git repo, it is stored in `./global/storage/`
 
 ---
 
@@ -35,26 +42,28 @@ This directory contains:
 
 If you're experiencing issues with opencode:
 
-### Report issues on GitHub
-
-The best way to report bugs or request features is through our GitHub repository:
-
-[**github.com/sst/opencode/issues**](https://github.com/sst/opencode/issues)
+1. **Report issues on GitHub**
+   
+   The best way to report bugs or request features is through our GitHub repository:
+   
+   [**github.com/sst/opencode/issues**](https://github.com/sst/opencode/issues)
+   
+   Before creating a new issue, search existing issues to see if your problem has already been reported.
 
-Before creating a new issue, please search existing issues to see if your problem has already been reported.
+2. **Join our Discord**
 
-### Join our Discord
+   For real-time help and community discussion, join our Discord server:
+   
+   [**opencode.ai/discord**](https://opencode.ai/discord)
 
-For real-time help and community discussion, join our Discord server:
+---
 
-[**opencode.ai/discord**](https://opencode.ai/discord)
+## Common issues
 
-Our community and team are happy to help with questions and troubleshooting.
+Here are some common issues and how to resolve them.
 
 ---
 
-## Common issues
-
 ### opencode won't start
 
 1. Check the logs for error messages