Document Pi DeepSeek smoke lane

Capture Linux Pi credential layout and JSON-mode DeepSeek smoke checks for the Colibri provider gate.

---
Build: pass | Tests: pass — 2467 passed (184 files)

doc/COLIBRI-PI-CONTROL-PLAN.md

@@ -100,10 +100,11 @@ No legacy runner/status code should be removed until these are true:
 1. Pi works on Linux for an end-to-end task.
 2. Pi works on FreeBSD for an end-to-end task.
 3. Pi JSON or SDK events map into Clawdie task/activity state.
-4. Colibri can consume watchdog status without breaking `doctor` or `pi-profile`.
-5. Herdr can display or launch the Linux-side operator workflow without becoming
+4. A DeepSeek provider lane works through Pi on Linux using `--mode json`.
+5. Colibri can consume watchdog status without breaking `doctor` or `pi-profile`.
+6. Herdr can display or launch the Linux-side operator workflow without becoming
    a required FreeBSD dependency.
-6. The network throughput coordination test has produced structured manifests
+7. The network throughput coordination test has produced structured manifests
    from at least two hosts.
 
 ## Branch Plan
@@ -148,6 +149,7 @@ Initial implementation modules:
 ## Related Documents
 
 - `doc/INTERAGENT-RUN-CONTRACT.md`
+- `doc/PI-DEEPSEEK-LINUX-SMOKE.md`
 - `doc/CONTROLPLANE-ARCHITECTURE.md`
 - `doc/CONTROLPLANE-MESSAGE-CONTRACT.md`
 - `doc/CONTROLPLANE-AGENT-ROLES.md`

doc/PI-DEEPSEEK-LINUX-SMOKE.md

@@ -0,0 +1,119 @@
+# Pi DeepSeek Linux Smoke
+
+**Date:** 14.maj.2026  
+**Status:** PLANNED — Linux-side provider lane for Colibri validation
+
+## Purpose
+
+Validate DeepSeek as the next Pi provider lane on Linux before wiring broader
+Colibri control flows. This is a provider smoke test, not a FreeBSD host-safety
+change.
+
+## Credential File
+
+Pi stores persistent provider credentials at:
+
+```text
+~/.pi/agent/auth.json
+```
+
+DeepSeek is a built-in Pi provider. No custom `models.json` base URL is needed.
+
+Expected shape:
+
+```json
+{
+  "deepseek": { "type": "api_key", "key": "<YOUR_DEEPSEEK_KEY>" }
+}
+```
+
+Important details:
+
+- field name is `key`, not `apiKey`
+- type literal is exactly `api_key`
+- do not commit this file
+- do not send the key through chat or agent prompts
+
+Alternative: Pi also reads `DEEPSEEK_API_KEY`, but credential resolution prefers
+`auth.json` over environment variables when both exist.
+
+Observed resolution order:
+
+```text
+--api-key flag -> auth.json -> OAuth -> env var -> models.json
+```
+
+## Local-Only Key Write Pattern
+
+Use a local shell prompt so the key does not pass through an agent transcript.
+In Pi interactive mode, prefix with `!` so it runs locally:
+
+```sh
+read -rs K
+```
+
+```sh
+printf '{\n  "deepseek": { "type": "api_key", "key": "%s" }\n}\n' "$K" > ~/.pi/agent/auth.json
+```
+
+```sh
+unset K
+```
+
+## Smoke Test
+
+First list models and record the exact model IDs. Do not hardcode model names
+before this succeeds.
+
+```sh
+pi --provider deepseek --list-models
+```
+
+Then run a JSON-mode connectivity smoke test:
+
+```sh
+pi --provider deepseek -p --mode json "reply with the single word: ok"
+```
+
+Expected result:
+
+- command exits successfully
+- output is JSONL
+- Colibri can parse the stream with `src/colibri-pi-events.ts`
+- a text delta or final assistant message contains `ok`
+
+## Linux Install Notes
+
+Observed on Linux with user-managed Node (`nvm`):
+
+- `npm i -g @earendil-works/pi-coding-agent` succeeds without sudo
+- install created `~/.pi/agent/` and `auth.json` automatically
+- no `pi init` was required
+- `--mode json`, `--mode rpc`, and `-p/--print` are available
+- default provider is Google if no provider is specified
+- DeepSeek and ZAI are first-class providers in Pi
+
+Cross-platform install tooling must detect prefix writability instead of assuming
+sudo or assuming a user-writable npm prefix.
+
+## Colibri Gate
+
+This smoke test supports the Colibri proof gates:
+
+```text
+Pi on Linux works
+Pi JSON event stream is available
+DeepSeek provider lane works through Pi, not through a separate CLI
+```
+
+## Non-Goals
+
+- Do not store or handle DeepSeek keys in Clawdie-AI source.
+- Do not add DeepSeek-specific CLI support outside Pi.
+- Do not hardcode DeepSeek model IDs before `--list-models` confirms them.
+- Do not make this Linux provider smoke test a dependency of FreeBSD host safety.
+
+## Related Documents
+
+- `doc/COLIBRI-PI-CONTROL-PLAN.md`
+- `doc/INTERAGENT-RUN-CONTRACT.md`