docs: add Web usage page (#8482)

6 files changed, 134 insertions, 2 deletions

diff --git a/packages/console/app/src/routes/index.tsx b/packages/console/app/src/routes/index.tsx
index d06c0dcf6..6bcf9dbb5 100644
--- a/packages/console/app/src/routes/index.tsx
+++ b/packages/console/app/src/routes/index.tsx
@@ -693,7 +693,7 @@ export default function Home() {
               <li>
                 <Faq question="Can I only use OpenCode in the terminal?">
                   Not anymore! OpenCode is now available as an app for your <a href="/download">desktop</a> and{" "}
-                  <a href="/docs/cli/#web">web</a>!
+                  <a href="/docs/web">web</a>!
                 </Faq>
               </li>
               <li>
diff --git a/packages/web/astro.config.mjs b/packages/web/astro.config.mjs
index dba43d02f..99a1c3bd8 100644
--- a/packages/web/astro.config.mjs
+++ b/packages/web/astro.config.mjs
@@ -60,7 +60,7 @@ export default defineConfig({
         "1-0",
         {
           label: "Usage",
-          items: ["tui", "cli", "ide", "zen", "share", "github", "gitlab"],
+          items: ["tui", "cli", "web", "ide", "zen", "share", "github", "gitlab"],
         },
 
         {
diff --git a/packages/web/src/assets/web/web-homepage-active-session.png b/packages/web/src/assets/web/web-homepage-active-session.png
new file mode 100644
index 000000000..5d1d7a78d
--- /dev/null
+++ b/packages/web/src/assets/web/web-homepage-active-session.png
diff --git a/packages/web/src/assets/web/web-homepage-new-session.png b/packages/web/src/assets/web/web-homepage-new-session.png
new file mode 100644
index 000000000..821793b2a
--- /dev/null
+++ b/packages/web/src/assets/web/web-homepage-new-session.png
diff --git a/packages/web/src/assets/web/web-homepage-see-servers.png b/packages/web/src/assets/web/web-homepage-see-servers.png
new file mode 100644
index 000000000..4480b9b8d
--- /dev/null
+++ b/packages/web/src/assets/web/web-homepage-see-servers.png
diff --git a/packages/web/src/content/docs/web.mdx b/packages/web/src/content/docs/web.mdx
new file mode 100644
index 000000000..fa3d07109
--- /dev/null
+++ b/packages/web/src/content/docs/web.mdx
@@ -0,0 +1,132 @@
+---
+title: Web
+description: Using OpenCode in your browser.
+---
+
+OpenCode can run as a web application in your browser, providing the same powerful AI coding experience without needing a terminal.
+
+![OpenCode Web - New Session](../../assets/web/web-homepage-new-session.png)
+
+## Getting Started
+
+Start the web interface by running:
+
+```bash
+opencode web
+```
+
+This starts a local server on `127.0.0.1` with a random available port and automatically opens OpenCode in your default browser.
+
+:::caution
+If `OPENCODE_SERVER_PASSWORD` is not set, the server will be unsecured. This is fine for local use but should be set for network access.
+:::
+
+---
+
+## Configuration
+
+You can configure the web server using command line flags or in your [config file](/docs/config).
+
+### Port
+
+By default, OpenCode picks an available port. You can specify a port:
+
+```bash
+opencode web --port 4096
+```
+
+### Hostname
+
+By default, the server binds to `127.0.0.1` (localhost only). To make OpenCode accessible on your network:
+
+```bash
+opencode web --hostname 0.0.0.0
+```
+
+When using `0.0.0.0`, OpenCode will display both local and network addresses:
+
+```
+  Local access:       http://localhost:4096
+  Network access:     http://192.168.1.100:4096
+```
+
+### mDNS Discovery
+
+Enable mDNS to make your server discoverable on the local network:
+
+```bash
+opencode web --mdns
+```
+
+This automatically sets the hostname to `0.0.0.0` and advertises the server as `opencode.local`.
+
+### CORS
+
+To allow additional domains for CORS (useful for custom frontends):
+
+```bash
+opencode web --cors https://example.com
+```
+
+### Authentication
+
+To protect access, set a password using the `OPENCODE_SERVER_PASSWORD` environment variable:
+
+```bash
+OPENCODE_SERVER_PASSWORD=secret opencode web
+```
+
+The username defaults to `opencode` but can be changed with `OPENCODE_SERVER_USERNAME`.
+
+---
+
+## Using the Web Interface
+
+Once started, the web interface provides access to your OpenCode sessions.
+
+### Sessions
+
+View and manage your sessions from the homepage. You can see active sessions and start new ones.
+
+![OpenCode Web - Active Session](../../assets/web/web-homepage-active-session.png)
+
+### Server Status
+
+Click "See Servers" to view connected servers and their status.
+
+![OpenCode Web - See Servers](../../assets/web/web-homepage-see-servers.png)
+
+---
+
+## Attaching a Terminal
+
+You can attach a terminal TUI to a running web server:
+
+```bash
+# Start the web server
+opencode web --port 4096
+
+# In another terminal, attach the TUI
+opencode attach http://localhost:4096
+```
+
+This allows you to use both the web interface and terminal simultaneously, sharing the same sessions and state.
+
+---
+
+## Config File
+
+You can also configure server settings in your `opencode.json` config file:
+
+```json
+{
+  "server": {
+    "port": 4096,
+    "hostname": "0.0.0.0",
+    "mdns": true,
+    "cors": ["https://example.com"]
+  }
+}
+```
+
+Command line flags take precedence over config file settings.