diff --git a/README.md b/README.md
index 173c489..a774607 100644
--- a/README.md
+++ b/README.md
@@ -26,18 +26,35 @@ Already have a clone? Just run it directly:
 ## Modules
 
 - `zsh/` — installs zsh + oh-my-zsh, drops a managed `~/.zshrc`
-  (robbyrussell theme, git plugin), and sets zsh as the login shell.
+  (robbyrussell theme, git plugin), and sets zsh as the login shell. The
+  managed rc sources `~/.zshrc.local` last for per-machine customizations
+  (see below).
 - `git/` — sets git `user.name`/`user.email` and configures
   `credential.helper store` (plaintext `~/.git-credentials`, 0600) for
   HTTPS auth.
-- `bin/` — installs userland devops CLIs (jq, kubectl, helm, k9s,
-  kubectx/kubens, stern, yq, OpenTofu, terragrunt, plus kind when rootless
-  Docker is available) as self-contained,
-  statically linked release binaries into `~/.local/bin`. No sudo, nothing
-  outside `$HOME`, so they persist across Kasm redeploys with no reinstall.
-  Idempotent: each tool records its version under `~/.local/bin/.versions`
-  and is skipped when the pinned version is already present. `zsh/zshrc`
-  puts `~/.local/bin` on `PATH`.
+- `docker/` — installs full (rootful) Docker Engine via get.docker.com,
+  enables the service (systemd hosts), and adds the invoking user to the
+  `docker` group (takes effect at next login). No-ops where a rootless
+  Docker daemon is already running (e.g. Kasm) so it never fights that
+  setup. Uses sudo.
+- `bin/` — installs userland devops CLIs as self-contained, statically
+  linked release binaries into `~/.local/bin`: jq, kubectl, helm, k9s,
+  kubectx/kubens, stern, yq, OpenTofu, terragrunt, task (go-task, the
+  Taskfile runner), the 1Password CLI `op` for secrets storage, and the
+  opencode coding agent. kind is installed
+  only when full (non-rootless) Docker is available — it doesn't work
+  against rootless Docker, so it is skipped on Kasm. No sudo, nothing
+  outside `$HOME`, so tools persist across Kasm redeploys with no
+  reinstall. Idempotent: each tool records its version under
+  `~/.local/bin/.versions` and is skipped when the pinned version is
+  already present. `zsh/zshrc` puts `~/.local/bin` on `PATH`.
+
+  opencode is configured by `mcp-config/`: it points at the covert-gpt
+  LiteLLM gateway (`https://llm.covert-gpt.com/v1` for models,
+  `https://llm.covert-gpt.com/mcp` for MCP tools). Run
+  `mcp-config/install.sh` once to store your LiteLLM key and enable
+  config sync — without it, opencode installs but can't reach the
+  gateway.
 - `ansible/` — installs Ansible into a virtualenv at `~/.local/opt/ansible`
   (it's Python, not a single binary) and symlinks its CLIs into
   `~/.local/bin`. Persists across redeploys; only rebuilt when the venv is
@@ -45,13 +62,37 @@ Already have a clone? Just run it directly:
   the system package manager (the one place this module uses sudo).
 - `docker-rootless-cgroup/` — on systemd-less hosts (e.g. Kasm), hand-delegates
   cgroup v2 controllers to the rootless Docker daemon so per-container cgroups
-  work and `kind` can create clusters (rootless Docker otherwise comes up with
+  work (rootless Docker otherwise comes up with
   `CgroupDriver=none`). Uses sudo for host cgroup writes and restarts the
   daemon; no-ops on systemd or non-rootless hosts. Re-run at each bootstrap
   (the cgroup layout resets on redeploy); its PATH shim lives in `$HOME`.
 - `mcp-config/` — shared MCP gateway config sync for laptops (LiteLLM /
   opencode). Independent of `bootstrap.sh`; see its own README.
 
+## Per-machine customizations and secrets
+
+`~/.zshrc` is managed — bootstrap overwrites it, so never hand-edit it.
+Per-machine settings and secrets go in `~/.zshrc.local`, which the managed
+rc sources last (so it can override anything) and bootstrap never touches:
+
+```sh
+cp zsh/zshrc.local.example ~/.zshrc.local && chmod 600 ~/.zshrc.local
+```
+
+Variables modules look for:
+
+- `GITEA_KEY` — personal access token for `git.nic-oconnor.com` (API/CLI
+  use; HTTPS git auth itself goes through `git/`'s credential helper).
+- `LITELLM_KEY` — covert-gpt gateway key used by opencode. Normally you
+  don't set this by hand: run `mcp-config/install.sh` once and its shell
+  hook exports it from `~/.config/mcp-sync/key`. Set it in `~/.zshrc.local`
+  only on a box without mcp-sync.
+- `OP_SERVICE_ACCOUNT_TOKEN` — 1Password service-account token for
+  non-interactive `op read` / `op run`.
+
+Secrets never go in this repo or in `zsh/zshrc` — that file is shared
+config applied to every box.
+
 `lib/os-detect.sh` provides shared package-manager detection (`dnf`/`yum`
 vs `apt`); `lib/fetch.sh` provides arch detection and binary-download
 helpers. Both are used by module install scripts.