feat: add capability-driven integration adapters

bin/agentic-kit.mjs

@@ -22,6 +22,8 @@ const PORCELAIN = Object.assign(Object.create(null), {
   dashboard: () => import('../src/commands/x/dashboard.mjs'),
   admin: () => import('../src/commands/x/admin.mjs'),
   dual: () => import('../src/commands/dual.mjs'),
+  host: () => import('../src/commands/x/provider.mjs'),
+  provider: () => import('../src/commands/x/provider.mjs'),
   uninstall: () => import('../src/commands/uninstall.mjs'),
 });
 
@@ -31,6 +33,7 @@ const PLUMBING = Object.assign(Object.create(null), {
   'dashboard': () => import('../src/commands/x/dashboard.mjs'),
   'harvest': () => import('../src/commands/x/harvest.mjs'),
   'mcp': () => import('../src/commands/x/mcp.mjs'),
+  'host': () => import('../src/commands/x/provider.mjs'),
   'provider': () => import('../src/commands/x/provider.mjs'),
   'reference': () => import('../src/commands/x/reference.mjs'),
   'statusline': () => import('../src/commands/x/statusline.mjs'),
@@ -47,6 +50,8 @@ Usage (ak = alias of agentic-kit):
   ak dashboard       open the local web dashboard (localhost; auto-opens browser)  [--port N] [--no-open]
   ak admin           maintainer-only telemetry admin (localhost; GitHub/npm egress)  [--port N] [--no-open]
   ak dual            run a Claude+Codex collaboration swarm (dual-host)  [run <template> "task"] [--dry-run]
+  ak host            manage agent hosts, routing, and provider bindings  [status|pick|refresh|off]
+  ak provider        deprecated alias for ak host; removed before the stable release
   ak uninstall       leave cleanly                                      [--this-project] [--purge]
 
   When in doubt: ak sync
@@ -67,7 +72,8 @@ Plumbing (power users) — each takes --help:
   ak x dashboard [--port N]    read-only local health dashboard (localhost only)
   ak x harvest [--dry-run]     opt-in learning-write: replay experiences into the substrate
   ak x mcp [status|pick|off]   MCP registration + tool-family deny rules
-  ak x provider [status|pick|off]   detect claude/codex CLIs; wire ruflo + aqe hosts/providers
+  ak x host [status|pick|refresh|off]   manage hosts, routing, and provider bindings
+  ak x provider [status|pick|refresh|off]   deprecated alias; removed before the stable release
   ak x reference [diff|sync]   CLAUDE.md managed-block inspection/reconcile
   ak x statusline [status|codex native|codex extended|codex off]   manage Codex's native user status line
   ak x verify [learning|security|aqe|providers|harvest|all]   deep proofs (slow, spawns real CLIs)
@@ -80,6 +86,7 @@ async function main() {
   const argv = process.argv.slice(2);
   let cmd = argv[0];
   let rest = argv.slice(1);
+  let deprecatedProvider = cmd === 'provider';
 
   if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
     console.log(argv.includes('--all') ? HELP_ALL : HELP);
@@ -97,6 +104,7 @@ async function main() {
     table = PLUMBING;
     cmd = rest[0];
     rest = rest.slice(1);
+    deprecatedProvider = cmd === 'provider';
     // `ak x`, `ak x --help`, `ak x -h` → the plumbing index.
     if (!cmd || cmd === '--help' || cmd === '-h') { console.log(HELP_ALL); return 0; }
     if (cmd === 'improvement-eval') {
@@ -120,6 +128,11 @@ async function main() {
     return 2;
   }
 
+  if (deprecatedProvider) {
+    const legacy = argv[0] === 'x' ? 'ak x provider' : 'ak provider';
+    const canonical = argv[0] === 'x' ? 'ak x host' : 'ak host';
+    console.error(`${legacy} is deprecated; use \`${canonical}\`. It will be removed before the stable release.`);
+  }
   const mod = await table[cmd]();
 
   // Per-command help — intercepted BEFORE run() so mutating commands

claude/aqe-reference.md

@@ -46,7 +46,7 @@ called first**, e.g. `fleet_init({ topology:"hierarchical", maxAgents:15, memory
   (metered API key), or `ollama`/`onnx` (local). It normalizes `anthropic`→`claude` and ignores
   unknown values. `AQE_MAX_BUDGET_USD` (or `--max-budget-usd`) caps metered spend; `aqe health`
   shows an "LLM Billing" section saying who pays. `aqe init` never writes these — but
-  **`ak x provider pick` now manages `AQE_LLM_PROVIDER` for you** (into
+  **`ak host pick` now manages `AQE_LLM_PROVIDER` for you** (into
   `.claude/settings.local.json` `env`, reversibly), and can write an ordered **fallback chain**
   into `.agentic-qe/llm-config.json` from `kit.json` (`--aqe-fallback 'claude-code:claude-opus-5; openai:gpt-5.6'`) —
   keys stay in the env, never the file. aqe is NOT limited to claude-code: codex the *CLI* isn't a

claude/dual-mode-reference.md

@@ -17,7 +17,7 @@ fallback.
 ### `ak dual run` — Claude+Codex collaboration pipelines
 
 `ak dual run <template> "<task>"` materializes a multi-worker pipeline from your
-per-activity routing policy (set via `ak x provider`) and runs it through the
+per-activity routing policy (set via `ak host`) and runs it through the
 `claude-flow-codex` adapter. Each worker is assigned a host + model by the policy, so a
 single run can span both vendors.
 
@@ -52,12 +52,12 @@ Register (or repair) both directions with `ak sync`; inspect with `ak status`.
 ### Per-activity routing + escalation ladders
 
 Routing is **per activity**, not per session — coder/tester lean Codex, reviewer and
-security-analysis lean Claude, and so on (`ak x provider` shows and edits the table).
+security-analysis lean Claude, and so on (`ak host` shows and edits the table).
 `--escalate` walks a **cross-vendor** ladder: a failed step retries on the other vendor's
 stronger model, so a Codex miss escalates into Claude (and vice-versa) rather than just
 burning retries on the same engine.
 
-**Which host leads.** The two are peers, but `ak x provider pick --primary-host claude|codex`
+**Which host leads.** The two are peers, but `ak host pick --primary-host claude|codex`
 (default `claude`) picks which one leads: codex-primary **mirrors** the default table so Codex
 takes the reasoning/review lead and Claude becomes the alternate/escalation target — the same
 ambidextrous experience with the roles flipped. `ak status` marks the primary and **fails**

claude/providers-reference.md

@@ -19,13 +19,19 @@ agentic-qe to use one or both. Two independent axes:
   - **ruflo** — `anthropic` / `openai` / `google` / `ollama` via `ruflo providers configure`.
   - API keys live in the environment; they are never persisted to `kit.json`.
 
+During the alpha, `ak host` is the canonical namespace for execution-host lifecycle and
+selection; `ak x host` is its plumbing spelling. `ak provider` and `ak x provider` are deprecated
+compatibility aliases that warn on stderr and will be removed before stable. This does not rename
+inference providers or bindings into hosts; provider flags remain temporarily co-located on this
+workflow while dedicated capability-driven surfaces mature.
+
 **One or several — you're never forced to pick just one.** All three surfaces run multiple
 providers concurrently:
 - **ruflo hosts** — enable `claude` *and* `codex` together (dual-mode); ruflo runs both.
 - **ruflo LLM providers** — a list, with load-balancing + automatic failover.
 - **agentic-qe** — its `HybridRouter` **auto-enables every provider that has an API key in the
   env** and fails over across an ordered chain. `AQE_LLM_PROVIDER` only pins the *default* (the
-  primary) — the others stay enabled. So `ak x provider` sets aqe's primary; adding
+  primary) — the others stay enabled. So `ak host` sets aqe's primary; adding
   `OPENAI_API_KEY` / `GEMINI_API_KEY` to the env brings those online as fallbacks automatically.
 
 ### aqe fallback chain — managed from `kit.json`
@@ -34,7 +40,7 @@ For **deterministic** ordering (rather than relying on env auto-enable), `ak` wr
 `.agentic-qe/llm-config.json` from `kit.json`:
 
 ```bash
-ak x provider pick --aqe-provider claude-code \
+ak host pick --aqe-provider claude-code \
   --aqe-fallback 'claude-code:claude-opus-5; openai:gpt-5.6; gemini:gemini-3.5-flash'
 ```
 
@@ -43,16 +49,16 @@ priority; model IDs are examples current as of July 2026 — use what your provi
 ak writes a **complete** chain (aqe merges it shallowly, so partial chains would drop
 defaults), sets each provider `enabled`, and tags the file `_managedBy: agentic-kit`. **API keys
 are never written** — they stay in the env (aqe refuses to persist them anyway). `ak sync`
-reapplies the chain; `ak status` flags drift; `ak x provider off` restores the pre-ak file from
+reapplies the chain; `ak status` flags drift; `ak host off` restores the pre-ak file from
 its one-time `.bak` (or removes an ak-created file). Entries need populated models — aqe's router
 skips an entry with none. For lower-level edits, `aqe llm-router config` still works.
 
 ### Managing it (prompts-once, reversible)
 
 ```bash
-ak x provider status   # detected CLIs + versions, what's enabled, what's wired
-ak x provider pick     # choose ruflo hosts / aqe provider / ruflo API providers → persist → apply
-ak x provider off      # reset to claude-only default; strip managed env keys
+ak host status   # detected CLIs + versions, what's enabled, what's wired
+ak host pick     # choose ruflo hosts / aqe provider / ruflo API providers → persist → apply
+ak host off      # reset to claude-only default; strip managed env keys
 ```
 
 `pick` persists your choice to `kit.json` and applies it: it writes the ruflo backend flags
@@ -70,7 +76,7 @@ dual-mode reference block and `docs/PROVIDERS.md` §3.5 for the routing table an
 
 ### Install & update (install-method-aware)
 
-- **First install** — `ak setup` (and `ak x provider pick`) installs any *enabled* host that
+- **First install** — `ak setup` (and `ak host pick`) installs any *enabled* host that
   is entirely **absent**: `npm i -g @anthropic-ai/claude-code` / `@openai/codex`.
 - **Updates** — `ak sync` keeps **npm-managed** hosts current (drift is detected on the same
   cached TTL as ruflo/aqe, and surfaces in the bin nudge + `ak status`).

docs/LIVE-SESSIONS.md

@@ -34,14 +34,15 @@ request. Stopping the dashboard closes the live service and all clients.
 
 - Claude and Codex sessions discovered newest-first from their local JSONL
   stores and bootstrapped from bounded, metadata-only records.
-- Project-first session cards with a provider glyph and text, model when
-  reported, lifecycle, freshness, and a concise operational summary.
+- Project-first session cards with a host glyph and name, independently
+  evidenced inference provider/model when reported, lifecycle, freshness, and
+  a concise operational summary.
 - Session, agent, sub-agent, tool, skill, plugin, MCP, and gate entities when a
   supported source record identifies them.
 - Authoritative Codex parent/child edges from the Codex state ledger.
 - Human-readable identity and current work: resolved agent or capability name,
-  host/model, lifecycle, elapsed time, latest safe operation summary, and
-  evidence confidence.
+  host, provider/model, lifecycle, elapsed time, latest safe operation summary,
+  and evidence confidence.
 - Typed relationships whose accessible titles use verbs such as **spawned**,
   **delegated**, **invoked**, **returned**, **evaluated**, and **gated**.
 - A semantic execution canvas with stable agent anchors and bounded tool,
@@ -57,8 +58,9 @@ request. Stopping the dashboard closes the live service and all clients.
   actor-specific geometry, and a **Pause live** control.
 - Sanitized adapter health showing status and aggregate file/event/error counts.
 
-The overview answers which project/provider is involved, whether the evidence
-is current, who is active, and what operation is happening now. Selecting a
+The overview answers which project and host are involved, which inference
+provider is evidenced, whether the evidence is current, who is active, and
+what operation is happening now. Selecting a
 node highlights adjacent relationships, focuses its work, and synchronizes the
 transcript. Search filters the current stream. Auto-follow yields when the
 reader scrolls away and reports unread activity until following resumes. The
@@ -67,7 +69,7 @@ flow downward. Follow anchors to the top; playback remains chronologically
 ordered internally.
 
 Projects are the durable top-level grouping. Select a project first, then one
-of its provider-qualified root sessions; currently active sessions appear
+of its host-qualified root sessions; currently active sessions appear
 before recent completed sessions. Selecting a root reveals its agent/worker
 threads as an indented hierarchy. Those child threads remain selectable for
 their own map, transcript, and playback, but do not inflate the project's
@@ -195,13 +197,13 @@ that the dashboard has inspected an agent's private reasoning.
 
 The topology plane is constructed from an allowlist and contains no transcript
 bodies. The separately selected content plane intentionally carries rich local
-evidence. It parses provider records into a bounded DTO, masks every emitted
+evidence. It parses source records into a bounded DTO, masks every emitted
 string server-side, and never emits Codex `encrypted_content`. Secret masking
 is best effort, not a guarantee; only run the dashboard where its local
 transcripts may be viewed.
 
 Transcript lookup validates both host and session ID, resolves the real file
-beneath the configured provider root, rejects symlink escapes, and rechecks
+beneath the configured host transcript root, rejects symlink escapes, and rechecks
 containment after replacement. Content responses are `no-store`, same-origin,
 bounded, and destroyed after their last subscriber.
 
@@ -246,7 +248,7 @@ unbounded content snapshot.
 | Symptom | Explanation |
 |---------|-------------|
 | No sessions | No supported metadata was found within the bounded newest-first discovery set |
-| Many identical provider session rows | Refresh after the current snapshot reconciles ledger hierarchy; root sessions and nested worker threads are counted separately |
+| Many identical host session rows | Refresh after the current snapshot reconciles ledger hierarchy; root sessions and nested worker threads are counted separately |
 | Worker thread appears at top level | Its declared parent is not currently retained, so it remains navigable as an orphan rather than hiding evidence |
 | Ruflo or AQE absent | Their stores are not auto-discovered; register each JSONL file with `--live-source` |
 | Project name not reported | No supported metadata supplied a working directory; raw paths are never sent to the browser |

docs/LOCAL-MODEL-VALIDATION.md

@@ -11,6 +11,13 @@ specifications, not observed** — at research time (2026-07-27) the Ollama daem
 indexed transcripts on the reference machine were vendor-metered. This document is the experiment
 that replaces derivation with measurement.
 
+[ADR-0016](adr/0016-capability-driven-integration-adapters.md) names the relationship this
+exercise is intended to prove: `ollama-via-claude` and `ollama-via-codex` are two independent
+**bindings** to one Ollama **provider**, while Claude Code and Codex CLI remain the transcript
+**hosts**. The catalogue/runtime API is a separate **observability source**. Configuring a binding
+establishes configured provenance; it does not upgrade provider, model digest, token, cache, quota,
+or `$0` claims to observed. This document remains that evidence gate.
+
 **Time:** about 15 minutes of interactive work, plus two paste-backs.
 
 ---

docs/MANAGED-TOOLS.md

@@ -5,6 +5,12 @@ version-detected, and displayed. This doc states the contract's four
 invariants, maps every managed tool onto them, and gives the checklist for
 adding a new tool without breaking them.
 
+The **host** rows here mean execution drivers such as Claude Code, Codex CLI, and OpenCode.
+Inference **providers** such as OpenRouter and Ollama are not install-owned hosts. Provider intent
+may use a **binding** and native configuration **projection**, while transcripts and catalogues
+remain separate **observability** evidence. The shared lifecycle and value-precise ownership
+design is Proposed in [ADR-0016](adr/0016-capability-driven-integration-adapters.md).
+
 Each invariant traces to a live failure it prevents — the appendix records
 them.
 
@@ -46,7 +52,7 @@ them.
 | --- | --- | --- | --- | --- | --- |
 | **ruflo** | npm `ruflo@latest` | `ak sync` | disk: global `package.json` | npm `view latest` (TTL-cached) | row ✓ / upstream's own `RuFlo V<x>` header ✓ / card + banner ✓ |
 | **agentic-qe** | npm `agentic-qe@latest` | `ak sync` | disk: global `package.json` (project-local fallback) | npm `view latest` (TTL-cached) | row ✓ / `Agentic QE V<x>` chip ✓ / card + banner ✓ |
-| **hosts** (claude, codex) | npm `@latest` — only when npm-managed | `ak sync` if npm-installed; **explicitly disowned** if brew/mise/native | disk: global `package.json`, else `--version` probe | npm latest for npm-managed only; external → `outdated:false` | row ✓ (version + method) / n/a / card + banner (npm-managed only) ✓ |
+| **hosts** (currently Claude/Codex; OpenCode is non-routable) | npm `@latest` — only when npm-managed | `ak sync` if npm-installed; **explicitly disowned** if brew/mise/native | disk: global `package.json`, else `--version` probe | npm latest for npm-managed only; external → `outdated:false` | row ✓ (version + method) / n/a / card + banner (npm-managed only) ✓ |
 | **agentdb** | npm, **pinned to ruflo's bundled version** — deliberately not latest | `ak sync` (repins on core skew) | disk: global `package.json` | ruflo's **bundled** copy (coherence), not npm latest — by design | row ✓ / n/a / card ✓; banner excluded (its authority isn't "latest") |
 | **ruvnet-brain** | npm `ruvnet-brain@latest` + `--version v<tag>` pin (never `github:` HEAD) | `ak sync`; the installer's own nightly self-updater is suppressed at install (`--no-nightly-prompt`) and disabled by sync if found (`ruvnet-brain-nightly` subsystem) | disk: KB `SOURCE.json → releaseTag`, falling back to ak's kit.json stamp for pre-stamping bundles | GitHub `releases/latest` tag (TTL-cached) | row ✓ / `V<tag>` chip ✓ / card + banner ✓ |
 | **kit (self)** | npm, **pinned to the exact version drift saw** (`@pacphi/agentic-kit@<v>`) | `ak sync` (runs last — npm replaces the running code) | disk: running copy's `package.json` | npm `latest` (+ `next` for prereleases, TTL-cached) | row ✓ / n/a / header version + card + banner ✓ |