feat(opencode): add compact connected ruv gateway

README.md

@@ -224,27 +224,29 @@ native surfaces rather than env flags.
 `ak setup --opencode` (or `integrations.hosts.opencode: true`
 in `kit.json`) converges, on every `ak sync`:
 
-- **`~/.config/opencode/opencode.json`** — the `claude-flow` MCP server (ruflo's 300+ tools,
-  via `claude-flow-mcp` with `ruflo mcp start` fallback) and `ruvnet-brain` MCP (the
-  stable-spine shim, hot-swapped on brain updates), plus ruflo's `skills.paths` and
-  pre-approved `permission` patterns — merged backup-first into whatever you already have
-  (a JSONC file ak can't parse is refused, never clobbered). Opting in authorizes the
-  `claude-flow_*` and `ruvnet-brain_*` MCP tool families without per-call prompts; use
-  OpenCode's permission configuration if you need narrower approval policy.
+- **`~/.config/opencode/opencode.json`** — connected `claude-flow`, `agentic-qe`, and
+  `ruvnet-brain` MCP entries, plus Ruflo skill paths and explicit permission rules. Values are
+  merged backup-first into the operator's existing JSON; collisions and user-authored tool or
+  permission policies are preserved rather than overwritten.
+- **Compact rUv gateway** — `claude-flow` and `agentic-qe` remain visibly connected in OpenCode,
+  while their hundreds of direct tool schemas are blacklisted from provider requests and exposed
+  lazily as `ak_ruflo_search` / `ak_ruflo_call` and `ak_aqe_search` / `ak_aqe_call`. RuvNet Brain
+  remains a small direct MCP. The gateway asks through OpenCode's permission system before calls
+  and opts a family back into direct exposure when user tool policy conflicts with projection.
 - **Lifecycle hooks** — `~/.config/opencode/plugins/ruflo-hooks.js`: session restore/end,
   best-effort bash safety screening (defense-in-depth, fail-open if the local handler is
   unavailable), edit/task outcome recording for ruflo's learning substrate
   (opencode has no settings-hooks surface; its plugin events are the hook spine).
-- **Subagents + skills** — ruflo's agent set converted to opencode subagents
-  (`~/.config/opencode/agents/`, re-converted whenever the catalog source changes) and the
-  platform skill (`~/.config/opencode/skills/ruflo/`). The catalog source resolves
-  automatically: claude marketplace clone (full set, auto-updated) → published
-  `@claude-flow/cli` package (substrate set); override via
-  `integrations.ownership.opencode.catalogDir` or `$RUFLO_REPO`.
+- **Lazy specialists + skills** — one receipt-owned `ak-specialist` subagent replaces the eager
+  107-profile task catalogue. The complete converted catalogue is embedded in the gateway and
+  reached through `ak_agent_search`, stock OpenCode `task`, and `ak_agent_load`. Installed skills
+  remain loadable through stock `skill`; only their eager system-prompt catalogue is compacted
+  behind `ak_skill_search`. Optional external MCP dependencies named by a specialist are reported
+  explicitly and are never presented as installed by Agentic Kit.
 - **Guidance** — `~/.config/opencode/AGENTS.md` gets ak's managed blocks with
-  opencode-correct tool names (`claude-flow_*`, `ruvnet-brain_search_ruvnet`).
+  the compact OpenCode workflow and direct RuvNet Brain grounding rule.
 
-Everything is ownership-recorded (`integrations.ownership.opencode.mcp`) and stripped surgically by
+Everything is value- and SHA-receipted under `integrations.ownership.opencode` and stripped surgically by
 `ak host off` / `ak uninstall` — your own opencode.json entries are never touched.
 
 **Execution routing.** `ak run` is the host-neutral runner for explicit OpenCode routes. For

claude/ruflo-opencode-reference.md

@@ -6,22 +6,25 @@
 ## Ruflo for opencode
 
 Ruflo is an AI orchestration toolkit (memory, hooks, swarms, neural learning,
-security). On this machine it is wired into opencode three ways (all managed by
+security). On this machine it is wired into opencode through native host surfaces (all managed by
 `ak`, converged on every `ak sync`):
 
-1. **MCP server `claude-flow`** — the full ruflo tool surface (300+ tools):
-   memory, swarms, agents, hooks, routing, workflows. Tools appear with the
-   `claude-flow_` prefix (e.g. `claude-flow_memory_store`,
-   `claude-flow_memory_search`, `claude-flow_swarm_init`,
-   `claude-flow_agent_spawn`, `claude-flow_hooks_route`). Pre-approved in
-   `~/.config/opencode/opencode.json` (`permission`).
+1. **Connected MCP servers, compact provider projection** — `claude-flow` and
+   `agentic-qe` stay connected in OpenCode, but their eager direct tool catalogues are
+   blacklisted from model requests. Discover and invoke the full live surfaces through
+   `ak_ruflo_search` / `ak_ruflo_call` and `ak_aqe_search` / `ak_aqe_call`.
+   RuvNet Brain stays direct: search it before making a factual rUv capability claim and
+   cite the returned source. Never substitute memory or model priors for Brain evidence.
 2. **Lifecycle hooks** — `~/.config/opencode/plugins/ruflo-hooks.js` maps
    opencode events to `ruflo hooks` verbs: session restore/end, bash safety
    screening, edit/task outcome recording for the learning substrate.
-3. **Skills + agents** — ruflo's skill catalog is on the skills path
-   (`skills.paths` in opencode.json), and ruflo's agent set is converted to
-   opencode subagents under `~/.config/opencode/agents/` (re-converted on
-   every `ak sync` after a ruflo upgrade).
+3. **Lazy skills + specialists** — use `ak_skill_search`, then stock `skill` with the
+   exact selected name. Use `ak_agent_search`, then stock `task` with
+   `subagent_type="ak-specialist"` and a prompt beginning `PROFILE: <exact name>`.
+   The specialist loads its receipt-owned profile with `ak_agent_load`. This preserves the
+   complete catalogue without paying its descriptions on every initial provider request.
+   If a profile names an external MCP dependency that is unavailable, report it; do not
+   invent the tool call or its result.
 
 **Restart after wiring.** opencode loads config, plugins, MCP servers, and
 agents once at startup. After `ak setup --opencode` (or any `ak sync` that
@@ -48,27 +51,25 @@ over prior decisions.
 
 ### Quick decision tree
 
-```
+```text
 Need to ... ?
-├─ Search past work / decisions      → ruflo memory search -q "..." --smart  (or claude-flow_memory_search)
+├─ Search past work / decisions      → ak_ruflo_search, then ak_ruflo_call(memory_search)
 ├─ Store a decision/pattern          → ruflo memory store -k K --value V -n patterns
-├─ Pick the right agent for a task   → ruflo route "task description"
-├─ Run a security audit              → ruflo security scan && the security-auditor subagent
+├─ Pick the right specialist         → ak_agent_search, then task(ak-specialist)
+├─ Run a security audit              → ak_agent_search for the security specialist
 ├─ Check ruv stack health            → ruflo doctor && ruflo status && ak status
-├─ Coordinate 3+ subagents           → native task tool first; claude-flow_swarm_init if topology/consensus needed
+├─ Coordinate 3+ agents              → ak_ruflo_search, then invoke the selected swarm operation
 ├─ Scan untrusted text               → ruflo security defend -i "..."
 ├─ Re-apply after a ruflo upgrade    → ak sync   (one command heals everything)
 └─ Anything rUv CLI                  → ruflo <cmd> --help
 ```
 
 ### Subagent coordination
 
-opencode's native `task` tool spawns subagents (ruflo's converted agent set is
-under `~/.config/opencode/agents/`, e.g. `coder`, `reviewer`, `tester`,
-`planner`, `researcher`, `security-auditor`, swarm coordinators). Spawn
-parallel subagents in ONE message whenever the work is independent. There is
-no SendMessage equivalent — subagents return a single final report; design
-prompts accordingly (self-contained context, explicit deliverable).
+opencode's native `task` tool spawns the receipt-owned `ak-specialist` dispatcher.
+Select the exact profile with `ak_agent_search`; do not guess profile names. Spawn parallel
+specialists in one message only when work is genuinely independent. There is no SendMessage
+equivalent — subagents return a final report, so give each a self-contained task and deliverable.
 
 ### Daemon (host-independent)
 

docs/HOST-SUPPORT.md

@@ -100,13 +100,13 @@ Official extension references: [Claude hooks](https://code.claude.com/docs/en/ho
 | Ruflo capability | Claude Code | Codex | OpenCode |
 | --- | --- | --- | --- |
 | Upstream host orientation | **Native:** primary/reference CLI surface | **Native + managed:** upstream backend/plugin pieces plus agentic-kit bridge | **Managed:** no equivalent upstream backend flag |
-| Ruflo MCP tools | Native registration | Managed Ruflo MCP registration | Managed OpenCode MCP entry |
+| Ruflo MCP tools | Native registration | Managed Ruflo MCP registration | Connected managed MCP; compact lazy `ak_ruflo_*` provider projection |
 | Shared Ruflo memory | Same project store | Same project store | Same project store when pointed at the same Ruflo server |
-| Agents and skills | Upstream Claude assets | Codex-compatible skills/plugin assets and generated guidance | Ruflo agents converted to OpenCode frontmatter/tool names |
+| Agents and skills | Upstream Claude assets | Codex-compatible skills/plugin assets and generated guidance | Receipt-owned lazy profile catalogue through one stock `ak-specialist`; stock skills loaded on demand |
 | Lifecycle hooks | Native Claude hooks | Codex hooks/plugin surfaces | OpenCode events translated by `ruflo-hooks.js` |
 | Inference-backend flag | `ENABLE_CLAUDE_CODE` | `ENABLE_CODEX` | None |
 | Cross-host bridge | Claude can call the Codex MCP server | Codex can call Ruflo MCP | No equivalent peer bridge |
-| Upgrade convergence | `ak sync` heals managed assets | `ak sync` heals bridge/guidance | `ak sync` reconverts catalog assets and repairs the plugin/config |
+| Upgrade convergence | `ak sync` heals managed assets | `ak sync` heals bridge/guidance | `ak sync` regenerates the embedded catalogue and repairs exact-receipted plugins/config |
 | Teardown | Managed blocks and registrations | Receipt-based managed teardown | Value- and hash-receipt teardown; user-owned values survive |
 
 Ruflo MCP access and Ruflo-backed inference are different contracts. In

docs/TROUBLESHOOTING.md

@@ -33,9 +33,10 @@ ak sync             # apply it
 | Want the rich Ruflo/SONA/AQE display inside Codex | Codex currently accepts built-in status-line fields only, not a command-backed renderer | Keep the rich footer in Claude Code; see [Managed Codex status line](CODEX-STATUSLINE.md) for the current boundary |
 | Too many `⚙` daemons / stale daemons | One daemon per active project is normal (local-only workers, $0). Stale = workspace deleted or past the 12h TTL | `ak x daemon-gc --kill`; `sync` also reaps (and verifies the pid really is a ruflo daemon before killing) |
 | Want to change which MCP tool families are callable | Exclusions are `permissions.deny` rules, persisted in kit.json | `ak x mcp pick` (re-runnable); `x mcp status` shows the inventory; `x mcp off` unregisters |
-| opencode: `claude-flow_*` tools / hooks / agents missing after `ak setup --opencode` or a sync | opencode loads config, plugins, MCP servers, and agents **once at startup** — a running session never sees the new wiring | quit and restart opencode; `ak status` (opencode rows) shows exactly which piece is missing |
+| opencode: Ruflo/AQE are not connected, compact `ak_*` tools are missing, or `ak-specialist` is unavailable after `ak setup --opencode` / `ak sync` | opencode loads config, plugins, MCP servers, and agents **once at startup** — a running session never sees new wiring | quit and restart opencode; `ak status` shows MCP connectivity, compact gateway, lifecycle plugin, skill, and specialist state separately |
 | opencode: `status` says `opencode.json is not plain JSON` | opencode legally allows JSONC comments; ak refuses to rewrite a file it can't parse rather than normalize (and silently drop) your comments | hand-merge the ak entries (`mcp`, `skills.paths`, `permission`) per `docs/adr/0017-opencode-host.md`, or remove the comments and run `ak sync` |
-| opencode: an agent/skill/plugin file you created yourself keeps ak's version away | deploys are no-clobber: a file without ak's generated marker at the destination is treated as user-owned and preserved (`status` reports it as `foreign`) | rename yours (or delete it and `ak sync` to get ak's managed copy) |
+| opencode: `status` reports a later `opencode.jsonc` override | stock OpenCode loads that file after `opencode.json`, so it can shadow the exact MCP/permission values ak receipts; ak cannot verify JSONC without rewriting user comments | merge the Agentic Kit entries into the later file and remove the duplicate override, or keep the override and use direct user-managed wiring; ak preserves both files and does not deploy its gateway against ambiguous effective config |
+| opencode: an agent/skill/plugin file you created yourself keeps ak's version away | deploys are no-clobber: only exact receipt-matching bytes are repairable; an unreceipted or edited destination is user-owned and preserved (`status` reports it as `foreign`) | rename yours (or remove it and run `ak sync` to get ak's managed copy) |
 | opencode: `status` says `no ruflo catalog source` | the agent/skill catalog resolves override → `$RUFLO_REPO` → claude marketplace clone → `@claude-flow/cli` (direct, then nested under ruflo) — all missing | install ruflo (`ak setup` does), or point `integrations.ownership.opencode.catalogDir` / `$RUFLO_REPO` at a ruflo checkout |
 | `ruflo memory store` says OK but reads return nothing | Absolute-DB-path pin missing, or an older check looked only at `.swarm/memory.db` while the native bridge selected `.swarm/agentdb-memory.db` | Run `ak x verify memory` for an isolated store/retrieve/on-disk/purge proof; `ak setup` re-pins and verifies the runtime-selected store |
 | `status` shows a `codex-plugins` warning such as unknown field `_note` | An enabled plugin's newest cached hook file does not match Codex's `description` + `hooks` top-level schema | Open Codex `/plugins`, refresh or disable the named plugin, then start a new session. `ak sync` deliberately does not rewrite Codex-owned cache |