docs: fix permission docs

packages/web/src/content/docs/agents.mdx

@@ -362,42 +362,33 @@ Here are all the tools can be controlled through the agent config.
 
 ### Permissions
 
-Permissions control what actions an agent can take.
+You can configure permissions to manage what actions an agent can take. Currently, the permissions for the `edit`, `bash`, and `webfetch` tools can be configured to:
 
-- edit, bash, webfetch
-
-Each permission can be set to allow, ask, or deny.
-
-- allow, ask, deny
-
-Configure permissions globally in opencode.json.
+- `"ask"` — Prompt for approval before running the tool
+- `"allow"` — Allow all operations without approval
+- `"deny"` — Disable the tool
 
 ```json title="opencode.json"
 {
   "$schema": "https://opencode.ai/config.json",
   "permission": {
-    "edit": "ask",
-    "bash": "allow",
-    "webfetch": "deny"
+    "edit": "deny"
   }
 }
 ```
 
-You can override permissions per agent in JSON.
+You can override these permissions per agent.
 
-```json title="opencode.json" {7-18}
+```json title="opencode.json" {3-5,8-10}
 {
   "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "edit": "deny"
+  },
   "agent": {
     "build": {
       "permission": {
-        "edit": "allow",
-        "bash": {
-          "*": "allow",
-          "git push": "ask",
-          "terraform *": "deny"
-        },
-        "webfetch": "ask"
+        "edit": "ask"
       }
     }
   }
@@ -419,83 +410,60 @@ permission:
 Only analyze code and suggest changes.
 ```
 
-Bash permissions support granular patterns for fine-grained control.
-
-```json title="Allow most, ask for risky, deny terraform"
-{
-  "$schema": "https://opencode.ai/config.json",
-  "permission": {
-    "bash": {
-      "*": "allow",
-      "git push": "ask",
-      "terraform *": "deny"
-    }
-  }
-}
-```
-
-If you provide a granular bash map, the default becomes ask unless you set \* explicitly.
+You can set permissions for specific bash commands.
 
-```json title="Granular defaults to ask"
+```json title="opencode.json" {7}
 {
   "$schema": "https://opencode.ai/config.json",
-  "permission": {
-    "bash": {
-      "git status": "allow"
-    }
-  }
-}
-```
-
-Agent-level permissions merge over global settings.
-
-- Global sets defaults; agent overrides when specified
-
-Specific bash rules can override a global default.
-
-```json title="Global ask, agent allows safe commands"
-{
-  "$schema": "https://opencode.ai/config.json",
-  "permission": { "bash": "ask" },
   "agent": {
     "build": {
       "permission": {
-        "bash": { "git status": "allow", "*": "ask" }
+        "bash": {
+          "git push": "ask"
+        }
       }
     }
   }
 }
 ```
 
-Permissions affect tool availability and prompts differently.
-
-- deny hides tools (edit also hides write/patch); ask prompts; allow runs
-
-For quick reference, here are common setups.
+This can take a glob pattern.
 
-```json title="Read-only reviewer"
+```json title="opencode.json" {7}
 {
   "$schema": "https://opencode.ai/config.json",
   "agent": {
-    "review": {
-      "permission": { "edit": "deny", "bash": "deny", "webfetch": "allow" }
+    "build": {
+      "permission": {
+        "bash": {
+          "git *": "ask"
+        }
+      }
     }
   }
 }
 ```
 
-```json title="Planning agent that can browse but cannot change code"
+And you can also use the `*` wildcard to manage permissions for all commands.
+Where the specific rule can override the `*` wildcard.
+
+```json title="opencode.json" {8}
 {
   "$schema": "https://opencode.ai/config.json",
   "agent": {
-    "plan": {
-      "permission": { "edit": "deny", "bash": "deny", "webfetch": "ask" }
+    "build": {
+      "permission": {
+        "bash": {
+          "git status": "allow",
+          "*": "ask"
+        }
+      }
     }
   }
 }
 ```
 
-See the full [permissions guide](/docs/permissions) for more patterns.
+[Learn more about permissions](/docs/permissions).
 
 ---
 

packages/web/src/content/docs/config.mdx

@@ -249,7 +249,9 @@ You can configure code formatters through the `formatter` option.
 
 ### Permissions
 
-You can configure permissions to control what AI agents can do in your codebase through the `permission` option.
+By default, opencode **allows all operations** without requiring explicit approval. You can change this using the `permission` option.
+
+For example, to ensure that the `edit` and `bash` tools require user approval:
 
 ```json title="opencode.json"
 {
@@ -261,11 +263,6 @@ You can configure permissions to control what AI agents can do in your codebase
 }
 ```
 
-This allows you to configure explicit approval requirements for sensitive operations:
-
-- `edit` - Controls whether file editing operations require user approval (`"ask"` or `"allow"`)
-- `bash` - Controls whether bash commands require user approval (can be `"ask"`/`"allow"` or a pattern map)
-
 [Learn more about permissions here](/docs/permissions).
 
 ---

packages/web/src/content/docs/permissions.mdx

@@ -1,27 +1,32 @@
 ---
 title: Permissions
-description: Control what agents can do in your codebase.
+description: Control which actions require approval to run.
 ---
 
-By default, opencode **allows all operations** without requiring explicit approval.
+By default, OpenCode **allows all operations** without requiring explicit approval. You can configure this using the `permission` option.
 
-The permissions system provides granular control to restrict what actions AI agents can perform in your codebase, allowing you to configure explicit approval requirements for sensitive operations like file editing, bash commands, and more.
-
----
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "edit": "allow",
+    "bash": "ask",
+    "webfetch": "deny"
+  }
+}
+```
 
-## Configure
+This lets you configure granular controls for the `edit`, `bash`, and `webfetch` tools.
 
-Permissions are configured in your `opencode.json` file under the `permission` key. Here are the available options.
+- `"ask"` — Prompt for approval before running the tool
+- `"allow"` — Allow all operations without approval
+- `"deny"` — Disable the tool
 
-### Tool Permission Support
+---
 
-| Tool       | Description                     |
-| ---------- | ------------------------------- |
-| `edit`     | Control file editing operations |
-| `bash`     | Control bash command execution  |
-| `webfetch` | Control web content fetching    |
+## Tools
 
-They can also be configured per agent, see [Agent Configuration](/docs/agents#agent-configuration) for more details.
+Currently, the permissions for the `edit`, `bash`, and `webfetch` tools can be configured through the `permission` option.
 
 ---
 
@@ -29,10 +34,6 @@ They can also be configured per agent, see [Agent Configuration](/docs/agents#ag
 
 Use the `permission.edit` key to control whether file editing operations require user approval.
 
-- `"ask"` - Prompt for approval before editing files
-- `"allow"` - Allow all file editing operations without approval
-- `"deny"` - Make all file editing tools disabled and unavailable
-
 ```json title="opencode.json" {4}
 {
   "$schema": "https://opencode.ai/config.json",
@@ -46,88 +47,144 @@ Use the `permission.edit` key to control whether file editing operations require
 
 ### bash
 
-Controls whether bash commands require user approval.
+You can use the `permission.bash` key to control whether bash commands as a
+whole need user approval.
 
-:::tip
-You can specify which commands you want to have run without approval.
-:::
-
-This can be configured globally or with specific patterns. Setting this to `"ask"`, requiring approval for all bash commands.
-Setting this to `"deny"` is the strictest option, blocking LLM from running that command or command pattern.
-
-For example.
+```json title="opencode.json" {4}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "bash": "ask"
+  }
+}
+```
 
-- **Ask for approval for all commands**
+Or, you can target specific commands and set it to `allow`, `ask`, or `deny`.
 
-  ```json title="opencode.json"
-  {
-    "$schema": "https://opencode.ai/config.json",
-    "permission": {
-      "bash": "ask"
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "bash": {
+      "git push": "ask",
+      "git status": "allow",
+      "git diff": "allow",
+      "npm run build": "allow",
+      "ls": "allow",
+      "pwd": "allow"
     }
   }
-  ```
+}
+```
 
-- **Disable all Terraform commands**
+---
 
-  ```json title="opencode.json"
-  {
-    "$schema": "https://opencode.ai/config.json",
-    "permission": {
-      "bash": {
-        "terraform *": "deny"
-      }
+#### Wildcards
+
+You can also use wildcards to manage permissions for specific bash commands.
+
+:::tip
+You can use wildcards to manage permissions for specific bash commands.
+:::
+
+For example, **disable all** Terraform commands.
+
+```json title="opencode.json" {5}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "bash": {
+      "terraform *": "deny"
     }
   }
-  ```
-
-- **Approve specific commands**
-
-  ```json title="opencode.json"
-  {
-    "$schema": "https://opencode.ai/config.json",
-    "permission": {
-      "bash": {
-        "git status": "allow",
-        "git diff": "allow",
-        "npm run build": "allow",
-        "ls": "allow",
-        "pwd": "allow"
-      }
+}
+```
+
+You can also use the `*` wildcard to manage permissions for all commands. For
+example, **deny all commands** except a couple of specific ones.
+
+```json title="opencode.json" {5}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "bash": {
+      "*": "deny",
+      "pwd": "allow",
+      "git status": "ask"
     }
   }
-  ```
+}
+```
 
-- **Use wildcard patterns to restrict specific commands**
+Here a specific rule can override the `*` wildcard.
 
-  ```json title="opencode.json"
-  {
-    "$schema": "https://opencode.ai/config.json",
-    "permission": {
-      "bash": {
-        "git push": "ask",
-        "*": "allow"
-      }
-    }
+---
+
+##### Glob patterns
+
+The wildcard uses simple regex globbing patterns.
+
+- `*` matches zero or more of any character
+- `?` matches exactly one character
+- All other characters match literally
+
+---
+
+### webfetch
+
+Use the `permission.webfetch` key to control whether the LLM can fetch web pages.
+
+```json title="opencode.json" {4}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "webfetch": "ask"
   }
-  ```
-  This configuration allows all commands by default (`"*": "allow"`) but requires approval for `git push` commands.
+}
+```
 
-### Agents
+---
 
-Configure agent specific permissions 
+## Agents
 
-```json
+You can also configure permissions per agent. Where the agent specific config
+overrides the global config. [Learn more](/docs/agents#permissions) about agent permissions.
+
+```json title="opencode.json" {3-7,10-14}
 {
   "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "bash": {
+      "git push": "ask"
+    }
+  },
   "agent": {
-    "plan": {
+    "build": {
       "permission": {
         "bash": {
-          "echo *": "allow"
+          "git push": "allow"
         }
       }
     }
   }
 }
 ```
+
+For example, here the `build` agent overrides the global `bash` permission to
+allow `git push` commands.
+
+You can also configure permissions for agents in Markdown.
+
+```markdown title="~/.config/opencode/agent/review.md"
+---
+description: Code review without edits
+mode: subagent
+permission:
+  edit: deny
+  bash: ask
+  webfetch: deny
+---
+
+Only analyze code and suggest changes.
+```
+

packages/web/src/styles/custom.css

@@ -367,7 +367,7 @@ nav.sidebar ul.top-level > li > details > summary .group-label > span {
 }
 
 .expressive-code {
-  margin: 12px 0 56px 0 !important;
+  margin: 0.75rem 0 3rem 0 !important;
   border-radius: 6px;
 
 }