Add LLM provider harness table, rotate test key from docs (Opencode)

doc/DEEPSEEK-V4-SMOKE.md

@@ -95,8 +95,8 @@ DEEPSEEK_API_KEY="<your-key>" pi --model deepseek/deepseek-v4-flash -p --mode js
 
 ## Where to Replace the Test Key
 
-The test key `sk-cde3e3cb42f4453e822856435e28a18a` was used for the
-smoke only. To set up a permanent key, edit:
+The test key used for the initial smoke has been rotated. To set up a
+permanent key, edit:
 
 ```
 ~/.pi/agent/auth.json

doc/LLM-PROVIDER-HARNESS.md

@@ -0,0 +1,89 @@
+# LLM Provider Harness — Status & Instructions
+
+**Owner:** Opencode / Z.ai Integrator
+**Updated:** 2026-05-24
+
+Quick reference for every LLM provider lane that agents in this project
+can use. Each row links to its smoke doc with full setup commands.
+
+## Provider Status
+
+| Provider        | pi flag               | Smoke status | API docs                                                | Key env var        | Key file                | Model IDs                              | Notes                        |
+| --------------- | --------------------- | ------------ | ------------------------------------------------------- | ------------------ | ----------------------- | -------------------------------------- | ---------------------------- |
+| **DeepSeek v4** | `--provider deepseek` | PASS         | [api-docs.deepseek.com](https://api-docs.deepseek.com/) | `DEEPSEEK_API_KEY` | `~/.pi/agent/auth.json` | `deepseek-v4-flash`, `deepseek-v4-pro` | Direct API; Sam holds key    |
+| **GLM-4.7**     | `--provider zai`      | TRANSPORT OK | z.ai (internal)                                         | `ZAI_API_KEY`      | opencode config         | TBD (`--list-models` needed)           | Powers this Opencode session |
+
+## Quick Start for New Agents
+
+### 1. Install pi
+
+```sh
+npm install -g @earendil-works/pi-coding-agent
+pi --version
+```
+
+### 2. Set a provider key
+
+Pick one:
+
+```sh
+# Option A: environment variable (session-only)
+export DEEPSEEK_API_KEY="<your-key>"
+
+# Option B: pi auth store (persistent)
+pi --provider deepseek --api-key "<your-key>"
+
+# Option C: per-command (no persistence)
+pi --provider deepseek --api-key "<your-key>" -p "hello"
+```
+
+### 3. Verify
+
+```sh
+pi --provider deepseek --list-models
+pi --provider deepseek --model deepseek-v4-flash -p "reply with: ok"
+```
+
+### 4. JSONL mode (for Colibri / structured consumption)
+
+```sh
+pi --provider deepseek --model deepseek-v4-flash -p --mode json "hello" 2>&1 | tee tmp/smoke.jsonl
+```
+
+Output is newline-delimited JSON. Event types: `session`, `agent_start`,
+`turn_start`, `message_start`, `message_update`, `message_end`,
+`turn_end`, `agent_end`.
+
+### 5. Provider prefix shorthand
+
+Skip `--provider` by prefixing the model:
+
+```sh
+pi --model deepseek/deepseek-v4-flash -p "hello"
+```
+
+## Provider Deep Links
+
+| Provider    | Smoke doc                                      | API keys                                                                 | Pricing                                                           |
+| ----------- | ---------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------- |
+| DeepSeek v4 | [DEEPSEEK-V4-SMOKE.md](./DEEPSEEK-V4-SMOKE.md) | [platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys) | [Pricing page](https://api-docs.deepseek.com/quick_start/pricing) |
+| GLM-4.7     | [GLM-4.7-SMOKE.md](./GLM-4.7-SMOKE.md)         | z.ai internal                                                            | TBD                                                               |
+
+## Adding a New Provider
+
+1. Get an API key from the provider.
+2. Run `pi --provider <name> --list-models` to discover model IDs.
+3. Run the smoke: `pi --provider <name> --model <id> -p --mode json "reply: ok"`.
+4. Capture output to `tmp/<provider>-smoke.jsonl`.
+5. Create `doc/<PROVIDER>-SMOKE.md` following the DeepSeek template.
+6. Add a row to the status table above.
+7. Commit and push.
+
+## Key Rotation
+
+When a key needs rotation:
+
+1. Generate a new key at the provider dashboard.
+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.