diff --git a/CLAUDE.md b/CLAUDE.md
index d20eaed..0b783a4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,7 +1,13 @@
 # composes
 
 Personal docker compose collection. One directory per service, each holding
-`compose.yml`, a committed `.env.example`, and a gitignored `.env`.
+`compose.yml`, its own `README.md`, a committed `.env.example`, and a
+gitignored `.env`.
+
+The root `README.md` is an index only — it covers the shared conventions and
+links out to each service. Per-service detail (variables, ports, storage)
+belongs in that service's README, not the root one. Adding a service means
+adding its README and a row to the root table.
 
 ## Deployment target
 
diff --git a/README.md b/README.md
index 42ac710..f5a679e 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,7 @@ plain `docker compose` means adding whatever your setup needs.
 ```
 <service>/
   compose.yml     # the service definition
+  README.md       # what it is, its variables, how it's wired
   .env.example    # required variables, committed
   .env            # real values, gitignored
 ```
@@ -48,25 +49,8 @@ Never commit it — the root `.gitignore` covers `.env`/`*.env` and re-includes
 
 ## Services
 
-### code-server
+Each links to its own README for variables, ports, and storage.
 
-[VS Code in the browser](https://github.com/linuxserver/docker-code-server),
-from the LinuxServer image, set up as a full remote dev box.
-
-Comes with Go, Node.js 24, Python 3, pnpm, and zsh via LinuxServer mods, plus
-`gh`, `git`, `ffmpeg`, `imagemagick`, and other CLI tools through
-`INSTALL_PACKAGES`. Git author/committer identity is injected from `.env`.
-
-Everything lives in the `code-server-config` named volume mounted at `/config`;
-the default workspace is `/config/workspace`. Removing the volume wipes your
-files, settings, and extensions.
-
-| Variable | Purpose |
+| Service | What it is |
 | --- | --- |
-| `PASSWORD` | Web UI login, also the in-container sudo password. **A blank value disables authentication entirely.** |
-| `GIT_NAME` / `GIT_EMAIL` | Git author and committer identity |
-| `CODEX_ACCESS_TOKEN` | OpenAI Codex CLI auth; leave blank if unused |
-
-Generate a password with `openssl rand -base64 24`.
-
-Listens on `8443` — point the domain at that port in Coolify or Dokploy.
+| [code-server](code-server/README.md) | VS Code in the browser, as a remote dev box |
diff --git a/code-server/README.md b/code-server/README.md
new file mode 100644
index 0000000..827a09e
--- /dev/null
+++ b/code-server/README.md
@@ -0,0 +1,28 @@
+# code-server
+
+[VS Code in the browser](https://github.com/linuxserver/docker-code-server),
+from the LinuxServer image, set up as a full remote dev box.
+
+Comes with Go, Node.js 24, Python 3, pnpm, and zsh via LinuxServer mods, plus
+`gh`, `git`, `ffmpeg`, `imagemagick`, and other CLI tools through
+`INSTALL_PACKAGES`. Git author/committer identity is injected from `.env`.
+
+## Environment
+
+| Variable | Purpose |
+| --- | --- |
+| `PASSWORD` | Web UI login, also the in-container sudo password. **A blank value disables authentication entirely.** |
+| `GIT_NAME` / `GIT_EMAIL` | Git author and committer identity |
+
+Generate a password with `openssl rand -base64 24`.
+
+## Networking
+
+Listens on `8443`. No ports are published — point the domain at that port in
+Coolify or Dokploy. See the [root README](../README.md) for why.
+
+## Storage
+
+Everything lives in the `code-server-config` named volume mounted at `/config`;
+the default workspace is `/config/workspace`. Removing the volume wipes your
+files, settings, and extensions.