From 5b240e8d958fbb4117e37f18a80909a13e2d7ee9 Mon Sep 17 00:00:00 2001
From: Niels V <niels.vandekeybus@redpencil.io>
Date: Mon, 6 Jul 2026 12:48:03 +0200
Subject: [PATCH] improve readme readability and add some tutorials

---
 README.md | 142 +++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 119 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index 8604520..d39b9de 100644
--- a/README.md
+++ b/README.md
@@ -1,39 +1,135 @@
-# app-opencode-experiment
+# app-opencode
 
-[opencode](https://opencode.ai/) in a Docker container, wired to [weave](https://weave.redpencil.io) as the model provider. Default model `weave/glm-5.2`. LSP baked in for TypeScript/JS and Python.
+[opencode](https://opencode.ai/) packaged in a Docker container and wired to
+[weave](https://weave.redpencil.io) as the model provider. It ships with an
+LSP for TypeScript/JavaScript and Python baked in, so opencode gets real
+type-aware navigation out of the box. The default model is `weave/glm-5.2`.
 
-## Setup
+The docs below are split into three parts: a **Getting started** walkthrough to
+run it the first time, **How-to guides** for specific tasks, and a **Reference**
+for the moving parts.
 
-Create a `docker-compose.override.yml` (gitignored) with your weave key and repo mount:
+## Getting started
 
-```yaml
-services:
-  opencode:
-    environment:
-      WEAVE_API_KEY: "..."
-    volumes:
-      - /path/to/your/repo:/workspace/repo
-```
+A first run from a clean checkout.
 
-Then:
+1. **Get a weave API key.** You need an account on
+   [weave.redpencil.io](https://weave.redpencil.io/ui/) and/or an API key (ask us!).
 
-```
-drc  up -d
-drc exec opencode opencode
-```
+2. **Create your local override.** `docker-compose.override.yml` is gitignored
+   and holds your key plus the repo you want opencode to work on. Create it with
+   your key and mount:
 
-## TUI
+   ```yaml
+   services:
+     opencode:
+       environment:
+         WEAVE_API_KEY: "your-key-here"
+       volumes:
+         - /path/to/your/repo:/workspace/repo
+   ```
 
-In the TUI, type `/models` to select a model from the registered weave models.
+3. **Start the container.**
 
-## Updating the config
+   ```
+   drc up -d
+   ```
 
-`opencode.json` is mounted into the container. After editing:
+4. **Open the TUI.**
+
+   ```
+   drc exec opencode opencode
+   ```
+
+You're now in opencode, talking to `weave/glm-5.2`. Type `/models` to switch
+models, or just start prompting.
+
+## How-to guides
+
+### Switch the model in a session
+
+In the TUI, type `/models` and pick from the registered weave models. This only
+changes the current session; to change the default for every session, edit
+`opencode.json` (see below).
+
+### Change the default model
+
+Edit `model` (and optionally `small_model`) in
+[`config/opencode/opencode.json`](config/opencode/opencode.json), then apply the
+change:
 
 ```
 drc restart opencode
 ```
 
-## Caveats
+`opencode.json` is mounted into the container, so a restart is all that's
+needed.
 
-- Copy from the TUI is weird over Docker: To copy text out of the opencode TUI running in a container, I have to do `Shift`+click to select the text, then `Ctrl`+`Shift`+`C` to copy. Plain `COPY` doesn't work.
+### Register a new weave model
+
+Add the model under `provider.weave.models` in `opencode.json`:
+
+```json
+"provider": {
+  "weave": {
+    "models": {
+      "my-new-model": { "tools": true }
+    }
+  }
+}
+```
+
+Then `drc restart opencode`. It will show up in the `/models` picker.
+See the [model list on weave](https://weave.redpencil.io/ui/models-and-endpoints/) for an overview of available models. Need another model, please let us know :)
+
+### Copy text out of the TUI
+
+Copying from the opencode TUI over Docker is fiddly: `Shift`+click to select the
+text, then `Ctrl`+`Shift`+`C` to copy. A plain copy doesn't work.
+
+### Connect opencode to a (backend) service
+
+To let opencode call a service over HTTP, e.g. a stack you've brought up in dev
+mode and want the agent to follow up against, have that stack join opencode's
+network instead of publishing ports or going via the host.
+
+opencode's stack creates a default network named `app-opencode_default`. Attach the
+dev-mode service to it as an external network:
+
+```yaml
+# the dev-mode app stack
+services:
+  app:
+    networks:
+      - default
+      - app-opencode_default
+
+networks:
+  app-opencode_default:
+    external: true
+```
+
+opencode can then reach it at `http://app:<port>`, where `app` is the **service
+name** from that stack's compose and `<port>` is the container's *internal* port.
+
+> Note: Bring the opencode stack up first, so `app-opencode_default` exists before adding to your app.
+
+## Reference
+
+### `opencode.json` keys
+
+- **`model` / `small_model`** — default model and the model used for lighter
+  tasks. Both default to `weave/glm-5.2`.
+- **`provider.weave`** — the weave provider, using the
+  `@ai-sdk/openai-compatible` adapter against `https://weave.redpencil.io/v1`
+  with the key from `WEAVE_API_KEY`.
+- **`provider.weave.models`** — the models offered in `/models`.
+- **`lsp`** — language servers baked into the image:
+  `typescript-language-server` for TS/JS and `pyright` for Python.
+- **`permission`** — set to `ask` for read, edit, bash, and external-directory
+  actions, so opencode prompts before acting.
+
+### Caveats
+
+- Copy from the TUI over Docker needs the `Shift`+click / `Ctrl`+`Shift`+`C`
+  dance described above.