diff --git a/doc/LLM-PROVIDER-HARNESS.md b/doc/LLM-PROVIDER-HARNESS.md
index 291435a2..4391500f 100644
--- a/doc/LLM-PROVIDER-HARNESS.md
+++ b/doc/LLM-PROVIDER-HARNESS.md
@@ -87,3 +87,49 @@ When a key needs rotation:
 2. Update `~/.pi/agent/auth.json` or your shell profile.
 3. Re-run the smoke to confirm.
 4. Delete the old key at the provider dashboard.
+
+---
+
+## Platform × Harness Matrix
+
+Level 1 is the **platform** (FreeBSD main, Linux auxiliary).
+Level 2 is the **harness** — which agent runtime lives where and which
+LLM providers each can reach.
+
+### Level 1: Platform
+
+| Platform              | Role                          | Primary harness | Herdr | Notes                      |
+| --------------------- | ----------------------------- | --------------- | ----- | -------------------------- |
+| **FreeBSD (main)**    | ISO build, live USB, validate | pi + codex      | no    | Authoritative build host   |
+| **Linux (auxiliary)** | Review, deploy, Colibri, UX   | pi + herdr      | yes   | Opencode + Claude sessions |
+
+### Level 2: Harness × LLM Provider Combos
+
+Each cell shows: agent / provider / model / smoke status.
+
+| Harness / Agent | DeepSeek v4                       | GLM-4.7 (z.ai)             | Claude (Anthropic)        | Gemini (Google)        | Codex (OpenAI)  |
+| --------------- | --------------------------------- | -------------------------- | ------------------------- | ---------------------- | --------------- |
+| **pi**          | `deepseek/deepseek-v4-flash` PASS | `zai/<tbd>` TRANSPORT OK   | `anthropic/claude-*` TODO | `google/gemini-*` TODO | n/a (codex pkg) |
+| **codex**       | n/a                               | n/a                        | n/a                       | n/a                    | built-in OpenAI |
+| **claude-code** | DeepSeek via OpenAI compat TODO   | n/a                        | native PASS               | n/a                    | n/a             |
+| **opencode**    | n/a (no DeepSeek config yet)      | native PASS (this session) | n/a                       | n/a                    | n/a             |
+| **gemini-cli**  | n/a                               | n/a                        | n/a                       | native TODO            | n/a             |
+
+### What populates the matrix
+
+- **FreeBSD live USB**: ships `pi` + `codex` only (per live CLI policy)
+- **Linux with herdr**: runs `pi`, `claude-code`, `codex`, `gemini-cli`,
+  and `opencode` — all visible in herdr panes
+- **Opencode** (this session): currently GLM-4.7 via z.ai; other
+  providers can be wired via opencode's config
+- **pi**: supports all providers via `--provider` flag; key in env or
+  `auth.json`
+
+### How to add a combo
+
+1. Pick an empty cell above.
+2. Configure the agent for that provider (key, model).
+3. Run the smoke (see Quick Start).
+4. Update the cell with the exact `provider/model` string and PASS/FAIL.
+5. Create a smoke doc if one doesn't exist.
+6. Commit and push.