Fix OpenCode backend invocation and diagnostics

docs/runbooks/OPENCODE_CLI_SUBAGENT.md

@@ -0,0 +1,137 @@
+# OpenCode CLI subagent runbook
+
+This runbook defines how Flynn uses the **OpenCode** CLI (`opencode`) as a *subagent*.
+
+Principles (same as other CLI subagents):
+- Treat output as **untrusted input**: digest + sanity-check; verify with local tools/tests when possible.
+- Prefer **plain text** output for easy ingestion; switch to structured output only when it provides clear benefit.
+- Never claim something is true just because the model said so—verify if we can.
+
+---
+
+## 0) Quick facts
+
+- Binary: `opencode`
+- Default model (verified present in `opencode models`): **`opencode/glm-5-free`**
+- Preferred mode: **non-interactive** (`opencode run ...`)
+
+---
+
+## 1) Default invocation
+
+### 1.1 Plain text (default)
+Use this for most tasks (summaries, parsing, transformation suggestions, drafting):
+
+```bash
+opencode run -m opencode/glm-5-free --format default "${PROMPT}"
+```
+
+Notes:
+- Keep prompts short and explicit.
+- If the prompt contains quotes/newlines, wrap with a heredoc substitution:
+
+```bash
+opencode run -m opencode/glm-5-free --format default "$(cat <<'PROMPT'
+...prompt text...
+PROMPT
+)"
+```
+
+### 1.2 JSON output (selective)
+Only use JSON mode when we need robust post-processing or auditing.
+
+```bash
+opencode run -m opencode/glm-5-free --format json "${PROMPT}"
+```
+
+Caveat:
+- `--format json` typically yields structured output that may be easier to parse, but it can be more verbose and may require filtering.
+
+---
+
+## 2) Model selection
+
+Default to `opencode/glm-5-free` unless the task clearly benefits from switching.
+
+When to switch models:
+- **Higher quality / long docs / tricky reasoning**: use a stronger model available in `opencode models` (example: `anthropic/claude-3-7-sonnet-latest`, `openai/gpt-5.3-codex`, `google/gemini-2.5-pro`).
+- **Need a specific provider** (e.g. Copilot org policy): use `github-copilot/...` models.
+
+Rule:
+- If model choice matters, be explicit in the call.
+
+---
+
+## 3) Attach files
+
+OpenCode supports attaching files. Use this for document parsing tasks when the CLI supports the file type.
+
+```bash
+opencode run -m opencode/glm-5-free --format default -f /path/to/file.pdf "Extract a table of key dates and parties. Return JSON."
+```
+
+Guidance:
+- Prefer attaching the file over copy/pasting huge content.
+- For PDFs/images, we may still prefer local tooling (Poppler, OCR) first, then provide extracted text.
+
+---
+
+## 4) Task recipes
+
+### 4.1 Document search & retrieval help
+Use OpenCode to:
+- expand queries
+- generate keywords/entities
+- propose relevance criteria
+
+Prompt pattern:
+- Provide: goal, corpus description, constraints, examples of good/bad hits.
+
+### 4.2 Document parsing
+Use OpenCode to:
+- outline structure
+- extract entities / timelines
+- convert semi-structured text to JSON
+
+Prompt pattern:
+- Specify the target schema exactly.
+- Ask it to quote source spans/anchors when possible.
+
+### 4.3 PDF manipulation (planning)
+Use OpenCode to decide *what* to do; use local tools to do it.
+- Example: “split pages 3–7”, “OCR then extract”, “remove password”, “linearize”, etc.
+
+---
+
+## 5) How Flynn digests OpenCode output
+
+When I run OpenCode:
+1. I’ll extract the actionable result (answer/plan/patch schema).
+2. I’ll sanity-check for contradictions and missing constraints.
+3. I’ll verify locally when possible (grep/tests/PDF tool output).
+4. I’ll present you the final integrated conclusion.
+
+Raw OpenCode output is included only when:
+- you ask for it
+- it’s needed for auditing/debugging
+- it contains a critical snippet (e.g., exact JSON) that must be preserved
+
+---
+
+## 6) Troubleshooting
+
+- If startup fails with:
+  - `default agent "<name>" is a subagent`
+  - then OpenCode config points `default_agent` to a non-primary agent.
+  - Fix by setting `default_agent` to a primary agent in `~/.config/opencode/opencode.json`, or remove that key.
+- For Flynn external backend wiring, prefer:
+  ```bash
+  opencode run --format default "{prompt}"
+  ```
+  instead of `opencode -p "{prompt}"`.
+- If `opencode` behaves strangely in a repo directory, try running from a neutral cwd (e.g. `$HOME`) or ensure paths passed to `-f` are absolute.
+- If a provider/model isn’t found, run:
+  ```bash
+  opencode models
+  ```
+  and pick an available entry.