pacphi · pacphi · Sep 25, 2026 · Sep 23, 2026 · Sep 23, 2026 · Sep 23, 2026
diff --git a/.gitattributes b/.gitattributes
@@ -5,3 +5,6 @@
 *.mjs text eol=lf
 *.cjs text eol=lf
 *.js text eol=lf
+# Captured CLI output fixtures are byte-exact evidence (one keeps a spinner \r):
+# never let a Windows checkout rewrite their line endings.
+tests/fixtures/ruflo-components/** -text
diff --git a/README.md b/README.md
@@ -40,6 +40,7 @@ container for you. See [docs/DEVCONTAINERS.md](https://github.com/pacphi/agentic
 - **Local transcript recall (optional):** [deja-vu](docs/DEJA-VU.md) indexes coding-agent histories for MCP search or host-native automatic recall. It is off by default because the derived plaintext index has its own privacy and retention boundary.
 - **Multi-host execution (optional):** Claude, Codex, and opt-in OpenCode can share one activity policy; `ak run` is the canonical executor, while `ak setup --codex` enables the subscription-backed Claude/Codex defaults.
 - **Self-healing:** `ak sync` re-converges after every upgrade; `ak status` and a local dashboard report observed state and explicit evidence gaps.
+- **Managed ruflo components:** ak applies and reports ruflo's opt-in agent pickers, MCP tool governance, learning profile, and promotional funnel — see [Managed ruflo components](docs/MANAGED-TOOLS.md#managed-ruflo-components).
 - **Scoped verification:** `ak x verify` exercises named paths against real CLIs and reports
   their results. Registration, configuration, and one passing probe do not establish
   every capability or every running session.

diff --git a/docs/DASHBOARD.md b/docs/DASHBOARD.md
@@ -93,6 +93,11 @@ comes from the same read-only status facts as the terminal: compatible package,
 verified native executable, trusted MCP config, and local browser payload remain
 separate from Vibium's Agentic-QE-owned cache visibility in System.
 
+The ruflo card carries a summary line ("ruflo components: 6 of 7 active") built from the same
+`ak status` row Overview > Runtime's panel header shows, so About and Runtime always agree. The
+line links to that panel; it appears only once `ak status` has reported the subsystem at least
+once.
+
 System's capability catalog counts both user/plugin surfaces and the project
 surfaces discovered by the host census. In particular, Codex project skills in
 `.agents/skills` are distinct evidence from user `~/.codex/skills` and enabled
@@ -136,7 +141,8 @@ Overview keeps status and routing in one health-first area:
   model, and the Ruflo/MCP process must inherit the required credential environment. Served-provider
   and served-model claims come from **Usage → Scorecard** evidence instead.
 - **Runtime** presents operational services, processes, MCP readiness, and cached
-  context configuration with host-specific native controls.
+  context configuration with host-specific native controls. It also holds the read-only
+  "ruflo components" panel (below).
 - **Intelligence** presents memory, learning, and quality-improvement signals machine-wide: an
   always-visible rollup folded across every project on this machine where memory or intelligence has
   been activated — a `.claude-flow`, `.agentic-qe` or `.swarm` directory, whichever host created it
@@ -155,6 +161,27 @@ Overview keeps status and routing in one health-first area:
   worktree, user-level, and other/unclassified subgroups. Each table subgroup shows
   five rows before scrolling; all rows remain available inside the bounded panel.
 
+### Ruflo components
+
+[ADR-0058](adr/0058-managed-ruflo-components.md)'s managed ruflo components — the typesafe and
+MiniLM agent pickers, MCP tool governance, the learning profile, MetaHarness turn-credit, the
+memory durability fix, and the funnel toggle — get one card each in Overview > Runtime. A card
+shows the state badge beside its plain-language meaning (and the action to take, when one
+applies), the current value and who controls it, an expandable "what it does" with its benefit,
+cost, and how to change it in `kit.json`, and the live evidence behind the state: which picker a
+`hooks route` probe reported, MCP calls audited and refused in the last 24 hours (zero on ruflo
+≤ 3.44.0, which does not yet enforce the policy on stdio launches; see
+[ADR-0058](adr/0058-managed-ruflo-components.md)), whether the
+learning engine is loaded, or the funnel's deciding source. The panel header repeats the same
+count and ruflo version `ak status` reports, so the two never disagree. Encryption at rest shows
+as `not yet managed` (ADR-0059) and is not part of that count. With ruflo not installed, the panel
+says so instead of showing cards.
+
+The panel reads a cache-only `GET /api/ruflo-components` route — the dashboard never probes ruflo
+itself. Run `ak status --refresh` (or `ak sync`) to collect fresh evidence, then reload the panel.
+The dashboard stays read-only here too: a card names the `kit.json` change or command instead of
+offering a control to act with.
+
 ### Why project counts differ between tabs
 
 Project counts reflect different populations. Intelligence uses the learning census, while Usage

diff --git a/docs/MANAGED-TOOLS.md b/docs/MANAGED-TOOLS.md
@@ -106,6 +106,73 @@ are separate facts. Existing compatible packages stay external; incompatible ext
 are preserved. Normal detection never runs `agent-browser doctor` or launches Chrome. Package
 removal is receipt-gated, while browser/session/profile data is always preserved.
 
+## Managed ruflo components
+
+[ADR-0058](adr/0058-managed-ruflo-components.md) applies the same ownership discipline to a set of
+opt-in ruflo capabilities that ship off by default: two agent pickers, MCP tool governance, the
+learning profile, MetaHarness turn-credit, a memory durability fix, and ruflo's promotional
+funnel. `ak setup` and `ak sync` apply the managed value for each component the installed ruflo
+version supports; `ak status` reports the real state, never a bare label.
+
+| Component | Managed value | Minimum ruflo | Applied by |
+| --- | --- | --- | --- |
+| Typesafe agent picker | on | 3.43.0 | global `@ruvector/typesafe` package + `CLAUDE_FLOW_ROUTER_TYPESAFE=1` |
+| MiniLM agent picker | on | 3.44.0 | `CLAUDE_FLOW_ROUTER_EMBEDDER=minilm` |
+| MCP tool governance | on; 120 calls/min, audit on | 3.42.0 | project `.harness/mcp-policy.json` + project-scoped `RUFLO_MCP_ENFORCE_POLICY=1` (not yet enforced on stdio launches by ruflo ≤ 3.44.0) |
+| Learning profile | `balanced` | 3.42.1 | `RUFLO_INTELLIGENCE_MODE=balanced` |
+| MetaHarness turn-credit | on | 3.36.0 | nothing to apply; ak confirms ruflo's bundled dependency resolves |
+| Memory durability fix (#2887) | on | 3.36.0 | nothing to apply; ak confirms `@claude-flow/memory` ≥ 3.0.0-alpha.22 |
+| Ruflo funnel (promotions) | off | any ruflo with `ruflo funnel` | `ruflo funnel disable` |
+| Encryption at rest | — | — | not managed yet; waits on ADR-0059 and is left out of the "N of M active" count |
+
+Opt out of any component in `kit.json`:
+
+```json
+{ "rufloComponents": { "minilmPicker": false, "learningProfile": "edge", "funnel": true } }
+```
+
+`false` means "ak does not manage this component" — the next `ak sync` restores, by receipt,
+whatever value existed before ak changed it; until it runs, `ak status` shows the component as
+`not applied` with that sync as its fix. `funnel` is inverted: `true` means "leave ruflo's funnel
+alone" (ak's managed value is off), and the next `ak sync` re-enables the funnel if ak was the one
+that disabled it. Turning `typesafePicker` off removes its environment variable but keeps the
+`@ruvector/typesafe` package; only `ak uninstall --purge` removes a package ak installed.
+
+A value ak did not write is never overwritten: a variable you set yourself, or one of ak's values
+you changed afterwards, is reported `user-managed` and kept, and ak still applies the other
+components in the same settings file. If you delete a value ak set, `ak status` reports it
+`drifted` and the next `ak sync` puts it back.
+
+The governance policy file is enforced only when it carries ak's own `_about` marker; a
+project's own pre-existing `.harness/mcp-policy.json` is left alone and reported `user-managed`.
+Ruflo 3.44.0 and earlier do not apply the policy on the stdio MCP launches Claude Code, Codex and
+OpenCode use (ADR-0058 upstream request 6): ak writes the file and the variable so they are ready
+when ruflo wires enforcement, and the component reports `unknown` until then, because no audit
+records appear.
+
+Every state `ak status`, `ak setup`, and the dashboard show carries its meaning and, where one
+applies, the fix:
+
+| State | Meaning | Action |
+| --- | --- | --- |
+| `active` | Applied and confirmed by ruflo's own evidence. | none |
+| `applied, not verified` | Set, but not yet confirmed — usually the hosts have not restarted. | restart Claude Code, Codex and OpenCode |
+| `needs ruflo ≥ X` | The installed ruflo is too old for this component. | `ak sync` upgrades ruflo |
+| `not applied` | ak has not applied the managed value yet. | `ak sync` |
+| `drifted` | A value ak set was removed. | `ak sync` restores it, or set the component to `false` to leave it out |
+| `user-managed` | You set your own value or opted out; ak reports it and leaves it alone. | none |
+| `partial` | Applied for some hosts only; the ones missing are named. | shown per host |
+| `blocked` | Applying failed; the reason is shown. | the specific next step |
+| `not yet managed` | ak does not manage this yet (encryption at rest, ADR-0059). | none |
+| `unknown` | No current evidence, so ak does not claim the component is on. | `ak status --refresh` |
+
+Restart Claude Code, Codex and OpenCode after a setup or sync that changes any component —
+hosts read their environment at start-up, so a component stays `applied, not verified` until a
+new session and ruflo's own check confirm it. See
+[Ruflo components](adr/0058-managed-ruflo-components.md) for the full design, and
+[Troubleshooting](TROUBLESHOOTING.md) for governance that stays `unknown` and stuck
+`applied, not verified` rows.
+
 ## Where each piece lives
 
 - **npm tools** — `src/lib/versions.mjs` (`installedVersion`, `driftReport`,
@@ -117,6 +184,11 @@ removal is receipt-gated, while browser/session/profile data is always preserved
 - **agent-browser** — `src/lib/agent-browser.mjs` (Node-aware exact version,
   native verification, trusted MCP config, receipt-gated teardown); lifecycle
   rationale in [ADR-0043](adr/0043-managed-ruflo-browser-executor.md).
+- **ruflo components** — `src/lib/ruflo-components/` (catalogue, states, `kit.json` intent,
+  the owned Claude/Codex/OpenCode environment projection, the governance policy file, evidence
+  collection and classification, apply/reconcile, uninstall teardown); surfaced in
+  `src/commands/status/sections/ruflo-components.mjs` and the dashboard's Overview > Runtime
+  panel; design in [ADR-0058](adr/0058-managed-ruflo-components.md).
 - **ruvnet-brain** — `src/lib/ruvnet-brain.mjs` (`installedReleaseOnDisk`,
   `latestVersion`, `classifyDrift`, `drift`, nightly-agent detection), heals
   `installRuvnetBrain` / `disableRuvnetBrainNightly`. Full background on its

diff --git a/docs/SETUP.md b/docs/SETUP.md
@@ -72,6 +72,22 @@ Use `--no-agent-browser` to disable the component. Restart or reconnect Claude,
 Codex, and OpenCode after setup so their stdio MCP process receives the new
 environment.
 
+### Ruflo components
+
+Machine setup also applies [ADR-0058's managed ruflo components](MANAGED-TOOLS.md#managed-ruflo-components):
+the typesafe and MiniLM agent pickers, the learning profile, and the funnel toggle. Project setup
+additionally applies MCP tool governance, which needs a project root for its policy file. Each is
+skipped when the installed ruflo predates its minimum version, and any component can be turned off
+with `rufloComponents` in `kit.json`.
+
+The setup trust manifest's "Managed ruflo components" group discloses each applicable change
+before setup runs: the exact environment variable or file it will set, one line of benefit and
+cost, and the `kit.json` opt-out. After changes, machine and project setup both print a results
+table (component, state, meaning), any step that failed, and, if anything changed, a reminder to
+restart Claude Code, Codex and OpenCode — hosts read their environment at start-up, so a
+component stays `applied, not verified` until the next session and ruflo's own check confirm it. `ak status --refresh` re-checks without a restart
+once the hosts are back up.
+
 ### Optional deja-vu companion
 
 deja-vu is disabled unless setup receives `--with-deja-vu`. The default opted-in

diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
@@ -55,6 +55,8 @@ ak sync             # apply it
 | `ruflo memory store` says OK but reads return nothing | Missing project pin, wrong working directory, or CLI and MCP selecting different files when both `.swarm/memory.db` and `.swarm/agentdb-memory.db` exist | `ak sync` can repair owned registration drift. `ak x verify memory` proves an isolated canary only; inspect existing-corpus routing separately as described below |
 | `status` shows a `codex-plugins` warning | A plugin is enabled in the wrong host, its newest cached hooks or skills fail a known Codex compatibility check, or `config.toml` cannot be inspected safely. The exact `codex@openai-codex` identity is a Claude Code companion and must not be enabled inside Codex | For a valid, regular `config.toml` and verified companion 1.0.6, preview the approval-required repair with `ak heal hooks --host codex`; it changes only that Codex entry, never Claude Code or the cache. Repair malformed TOML or merge symlink-managed config manually. For other plugin findings, open Codex `/plugins`, refresh or disable the named plugin, then start a new session. Setup and sync never rewrite Codex-owned plugin state |
 | `status` shows a `memory-pin` warning | `CLAUDE_FLOW_DB_PATH` is pinned to a dead or foreign path, so every memory op targets the wrong DB ("Database not initialized" beside a healthy in-repo DB). The pin may be deliberate, so `sync` never touches it | repoint (or remove) the pin in `.claude/settings.local.json` `env` |
+| MCP tool governance stays `unknown` | Ruflo 3.44.0 and earlier do not route stdio MCP tool calls through their policy enforcer, so no audit records are written even though ak wrote the policy file and set `RUFLO_MCP_ENFORCE_POLICY=1` | Nothing to fix on your side; the component confirms once ruflo wires enforcement (ADR-0058 upstream request 6). A project whose `.harness/mcp-policy.json` is invalid shows `mcpGovernance: blocked` instead: restore a valid, ak-written file and run `ak sync`, which also removes the enforcement variable for that project until the file is fixed |
+| A [ruflo component](MANAGED-TOOLS.md#managed-ruflo-components) stays `applied, not verified` | Claude Code, Codex, and OpenCode read their environment only at process start-up, so a change setup or sync just made has not reached a running session yet | Restart Claude Code, Codex, and OpenCode, then run `ak status --refresh` to re-collect evidence with the new environment in effect |
 | Want to run `ak sync` but Claude/Codex/OpenCode sessions are open in other terminals | Upgrade-bearing syncs stop **all** ruflo daemons machine-wide and swap the global npm trees live sessions execute hooks/statusline/MCP calls from; even a no-upgrade sync can repair configuration or missing dependencies | `ak sync --dry-run` first; a `versions` row means idle the other sessions or use `ak sync --no-upgrade`; see [Running `ak sync` while sessions are live](UPGRADING.md#running-ak-sync-while-sessions-are-live) |
 | Suspicious token burn | Background automation vs interactive usage | ask Claude to run the **ruflo-token-audit** skill (deployed by `setup`) |
 | Observability is empty or has no ruflo/AQE nodes | Live mode tails Claude/Codex records by default, while ruflo/AQE stores are not auto-discovered | open Observability before producing activity; switch to History for retained sessions; register a trusted JSONL file with repeatable `--live-source 'surface=path'`; see [Observability](https://github.com/pacphi/agentic-kit/blob/main/docs/OBSERVABILITY.md) |

diff --git a/docs/USAGE-SCORECARD-METRICS.md b/docs/USAGE-SCORECARD-METRICS.md
@@ -1916,7 +1916,7 @@ aggregated here, and deriving the baseline from a widened bound would silently
 stretch it to whatever lookback the caller happened to pass. The dashboard route widens it to
 the depth the personal tap-share baseline needs rather than to the previous
 window alone: `days + BASELINE_TRAILING_DAYS` (`lookbackDays`,
-`src/lib/dashboard-server.mjs:1779`); `ak usage score` applies the same rule
+`src/lib/dashboard-server.mjs:1824`); `ak usage score` applies the same rule
 (`src/commands/usage.mjs:316`). One extra window would be a strict
 subset — too shallow for `promptBaselines`, which needs
 BASELINE_MIN_ACTIVE_DAYS of history BEFORE the displayed window and returns

diff --git a/docs/adr/0016-capability-driven-integration-adapters.md b/docs/adr/0016-capability-driven-integration-adapters.md
@@ -4,6 +4,7 @@
   [ADR-0020](0020-ga-stable-surfaces.md); closed-registry clause superseded by
   [ADR-0029](0029-host-adapter-extension-point.md)
 - **Date:** 2026-07-28
+- **Updated:** 2026-09-23 — the Claude memory pin is receipt-owned and removed by uninstall (ADR-0058).
 - **Updated:** 2026-09-09 — reconciled against repository source and tests for issue #211
 - **Earlier update:** 2026-09-02
 - **Update note:** Added read-only Codex plugin-hook compatibility facts,