docs(readme): document opencode prerequisites (#90)

## Summary

Document the two prerequisites for running opencode under the
dispatcher: (1) `opencode providers login` to set up credentials, and
(2) explicit `AGENT_DEV_MODEL` / `AGENT_REVIEW_MODEL` in
`autonomous.conf` (opencode is provider-agnostic — no default model).
Also flag that `AGENT_PERMISSION_MODE=bypassPermissions` isn't yet wired
to opencode's `--dangerously-skip-permissions` flag (same gap as codex).

## Why

After #89 added first-class opencode support, a user reading the
README's "Full support" badge and setting `AGENT_CMD=opencode` would get
a silently stalled pipeline: opencode enters a session but produces no
output without credentials and an explicit model. Spelling out the
prereqs up-front prevents the foot-gun.

## What changed

- **README → Supported Agent CLIs**: opencode row now has a † footnote
covering auth + explicit model + the bypassPermissions gap.
- **README → variable table**: the `AGENT_CMD` row gets an inline
pointer to the footnote so users editing `autonomous.conf` see the
warning without scrolling.
- **`autonomous.conf.example`**: the `AGENT_CMD` comment and the
`AGENT_DEV_MODEL` / `AGENT_REVIEW_MODEL` comments now explicitly call
out that empty model values are valid for claude/codex but invalid for
opencode.

## Test Plan

- [x] No code changes; `bash -n` clean on `autonomous.conf.example`
- [ ] CI checks pass

## Checklist

- [x] Docs only
- [x] Build/tests not affected

Author: zxkane

README.md

@@ -168,7 +168,7 @@ The file is a bash script that's `source`d at every dispatcher tick and wrapper
 | `REPO` | Yes | `owner/repo-name` | The GitHub repo the pipeline watches. |
 | `REPO_OWNER`, `REPO_NAME` | Yes | Split form of `REPO` | Used for App-token scoping. |
 | `PROJECT_DIR` | Yes | Absolute path to the project root on the dispatcher box | Where the agent runs. |
-| `AGENT_CMD` | No (default `claude`) | `claude`, `codex`, `kiro`, or `opencode` | The CLI used to spawn dev/review agents. Other CLIs work via the generic `<cli> -p <prompt>` fallback. See the Supported Agent CLIs table for resume semantics per CLI. |
+| `AGENT_CMD` | No (default `claude`) | `claude`, `codex`, `kiro`, or `opencode` | The CLI used to spawn dev/review agents. Other CLIs work via the generic `<cli> -p <prompt>` fallback. See the Supported Agent CLIs table for resume semantics per CLI. **`opencode` requires `opencode providers login` and explicit `AGENT_DEV_MODEL`/`AGENT_REVIEW_MODEL` values** — see the table footnote. |
 | `AGENT_DEV_MODEL`, `AGENT_REVIEW_MODEL` | No (default empty / `sonnet`) | Model name passed to the agent CLI | Empty = let the CLI pick. The review model defaults to `sonnet` to keep review costs predictable. |
 | `AGENT_PERMISSION_MODE` | No (default `auto`) | `auto`, `plan`, or `bypassPermissions` | `bypassPermissions` grants the agent unrestricted shell access — only use in a trusted sandbox. |
 | `AGENT_TIMEOUT` | No (default `4h`) | coreutils `timeout` units (e.g. `30m`, `2h`, `1d`) | Wall-clock cap on each agent invocation. Prevents hung CLI processes (stale `--resume`, MCP stdio deadlock) from monopolizing wrapper PID slots. |
@@ -373,7 +373,17 @@ The dispatcher is an [OpenClaw](https://github.com/OpenClaw/OpenClaw) skill that
 | Kiro CLI | `kiro-cli` | `chat --no-interactive [--agent <name>]` | (falls back to new) | Basic support |
 | Cursor Agent | `agent` | `-p "<prompt>"` | `--resume=<chat-id>` | Generic fallback (untested explicit branch) |
 | Gemini CLI | `gemini` | `-p "<prompt>"` | (no documented resume flag) | Generic fallback (untested explicit branch) |
-| opencode | `opencode` | `run --format json [PROMPT]` | `run --session <sessionID>` (captured from JSON stream) | Full support |
+| opencode | `opencode` | `run --format json [PROMPT]` | `run --session <sessionID>` (captured from JSON stream) | Full support † |
+
+† **opencode prerequisites.** Unlike Claude Code (Anthropic-bound) or Codex CLI (OpenAI-bound), opencode is provider-agnostic — it has no default model, and no built-in credentials. Before setting `AGENT_CMD=opencode`:
+
+1. **Authenticate a provider.** Run `opencode providers login` once on the dispatcher box (or every box that runs the wrapper if `EXECUTION_BACKEND=remote-aws-ssm`). Without this, the agent enters a session but produces no output and the pipeline silently makes no progress.
+2. **Set an explicit model.** opencode's `--model` argument expects `provider/model` form (e.g. `anthropic/claude-sonnet-4-6`, `openai/gpt-5.4`). The wrapper forwards `AGENT_DEV_MODEL` / `AGENT_REVIEW_MODEL` from `autonomous.conf`; leave them empty and opencode will either error out or wait for interactive selection (which never arrives in headless mode). Recommended:
+   ```bash
+   AGENT_DEV_MODEL="anthropic/claude-sonnet-4-6"
+   AGENT_REVIEW_MODEL="anthropic/claude-haiku-4-5"
+   ```
+3. **`AGENT_PERMISSION_MODE=bypassPermissions` is not yet wired** to opencode's `--dangerously-skip-permissions` flag (same gap as the codex branch — tracked as a follow-up). For now, run opencode in a sandboxed environment where the missing permission flag is acceptable.
 
 Configure via `AGENT_CMD` in `scripts/autonomous.conf`. The `claude`, `codex`, `kiro`, and `opencode` rows have explicit branches in `scripts/lib-agent.sh`; the others run through the generic `<cli> -p <prompt>` fallback. Any CLI not listed should still work if it accepts a `-p <prompt>` non-interactive flag — the abstraction layer is intentionally permissive.
 

skills/autonomous-dispatcher/scripts/autonomous.conf.example

@@ -15,7 +15,18 @@ PROJECT_DIR="/path/to/project"
 # First-class support: claude, codex, kiro, opencode. Other CLIs work via
 # the generic `<cli> -p <prompt>` fallback. See README "Supported Agent
 # CLIs" for resume semantics per CLI.
+#
+# opencode prerequisites (provider-agnostic CLI, no defaults):
+#   1. Run `opencode providers login` once on this box to set up
+#      credentials for at least one model provider.
+#   2. Set AGENT_DEV_MODEL and AGENT_REVIEW_MODEL below to explicit
+#      `provider/model` strings (e.g. "anthropic/claude-sonnet-4-6").
+#      Leaving them empty leaves opencode without a model to call.
 AGENT_CMD="claude"
+# AGENT_DEV_MODEL / AGENT_REVIEW_MODEL: model passed via the CLI's
+# --model flag. Empty = let the CLI pick its default (claude/codex
+# only — opencode has no default and will fail if both are empty when
+# AGENT_CMD=opencode).
 AGENT_DEV_MODEL=""
 AGENT_REVIEW_MODEL="sonnet"
 # WARNING: 'bypassPermissions' grants the agent unrestricted shell access.