feat(AI-011): bootstrap opencode + canonical AGENTS.md migration

[mlorentedev]

Summary

Bootstraps OpenCode as a secondary AI coding agent alongside Claude Code, with the Go subscription ($10/mo fixed) as the primary provider — catalog-restricted to DeepSeek V4 Pro + Kimi K2.6 to prevent accidental PAYG billing on Zen frontier models. OpenRouter added as an env-detected fallback (reuses existing OPENROUTER_API_KEY). Aider stays in this PR for coexistence; sunset lands in a follow-up PR.

Folds in AI-013 (copilot-instructions-refresh): per ADR-009, the canonical agent instructions move to AGENTS.md at repo root (read natively by OpenCode and other agents.md-aware tools). ai/claude/CLAUDE.md, ai/gemini/GEMINI.md, and both copilot-instructions.md files shrink to pointer-style files retaining only agent-specific extensions.

Bug fixes en passant (zero-debt rule):

• Unresolved template placeholder `the knowledge base (...)` in both copilot-instructions.md files.
• Wrong path %USERPROFILE%\Apps\knowledge\ → Projects\knowledge.

Idempotence (per pattern-setup-script-idempotence)

• command -v opencode gate before install (no force re-install).
• cmp -s reconcile-not-skip on config deploy.
• Post-deploy assertion: binary reachable + version reports.
• No new silenced errors (2>/dev/null || true).
• PATH addition via ensure_line_in_file (idempotent, no manual sed).

Three-layer PAYG guardrail

Layer	Where	What it does
1. Config	opencode.jsonc	provider.opencode-go.models lists only Go catalog; /models picker hides frontier.
2. Workspace	Zen dashboard	Set PAYG cap to $0 (documented in runbook).
3. Payment	Zen dashboard	No payment method for PAYG → frontier calls fail rather than charge.

Tests

• 27 new in tests/opencode.bats — relational (not presence-only): idempotence pattern, reconcile-not-skip, regression test for aider coexistence, schema declaration, MCP mirror, model restriction, pointer-file enforcement on CLAUDE.md/GEMINI.md/copilot.
• healthcheck.sh extended with section 10/11 (OpenCode binary + config + schema).
• healthcheck.bats updated for 11-section count + renamed assertions.
• 493/493 tests pass. ShellCheck clean (one info-level SC2016 suppressed with justification).

Test plan

• Clean-install: `./setup-linux.sh` on a fresh box → `command -v opencode` resolves, `opencode --version` reports.
• Idempotence: re-run `./setup-linux.sh` → no binary re-download, `cmp -s` no-op on config, no error noise.
• Alias: `source ~/.zshrc && command -v oc` resolves to opencode.
• Healthcheck: `./scripts/healthcheck.sh` includes section 10/11 OpenCode (3 checks: binary, config, schema).
• Bats: `~/.local/bin/bats tests/opencode.bats` → 27/27.
• Manual: launch `oc` → `/connect` → select OpenCode Go → paste API key → `/models` shows only DeepSeek V4 Pro + Kimi K2.6 under opencode-go provider.
• AGENTS.md: confirm OpenCode reads it at repo root on first launch (no fallback to vendored prompt).

References

• Spec: `specs/AI-011-opencode-bootstrap/` (proposal, tasks, verification)
• ADR: `adr-009-multi-agent-runtime` (vault)
• Pattern: `pattern-setup-script-idempotence` (vault)
• Runbook: `10_projects/dotfiles/40-runbooks/guide-opencode-go-setup.md` (vault)
• Closes: AI-011, AI-013

Follow-ups (not in this PR)

• PR2 — Aider sunset + amend ADR-009 status proposed → accepted.
• Hive MCP lock-file (separate repo) for safe parallel oc + claude on the same repo.
• A/B comparison Kimi K2.6 vs DeepSeek V4 Pro after first month of real use.