claude-flow 3.56.0 → 3.56.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.56.0",
+  "version": "3.56.1",
   "workspaces": [
     "v3/@claude-flow/codex",
     "v3/@claude-flow/mcp",

package/v3/@claude-flow/cli/README.md

@@ -1,85 +1,22 @@
 <div align="center">
 
-<a href="https://cognitum.one/agentic-engineering"><img src="ruflo/assets/ruflo-neon-flicker.gif" alt="Ruflo animated neon sign" width="100%"></a>
-
-**An agent meta-harness for Claude Code and Codex.**
+[![Ruflo Banner](ruflo/assets/ruflo-small.jpeg)](https://cognitum.one/agentic-engineering)
 
 <!-- Try Ruflo — the 3 badges first-time visitors actually act on -->
 [![npm version (ruflo)](https://img.shields.io/npm/v/ruflo?label=npx%20ruflo&style=for-the-badge&logo=npm&color=cb3837)](https://www.npmjs.com/package/ruflo)
 [![MIT License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](https://opensource.org/licenses/MIT)
 [![Star on GitHub](https://img.shields.io/github/stars/ruvnet/claude-flow?style=for-the-badge&logo=github&color=gold)](https://github.com/ruvnet/claude-flow)
 
-<p align="center">
-<a href="data/npm-downloads.latest.json"><img src="docs/assets/readme/badges/downloads.svg?v=mobile-readable-3" width="300" alt="Ecosystem npm downloads: 12.52M over 12 months through October 4, 2026"></a>
-<br>
-<a href="https://github.com/ruvnet/claude-flow"><img src="docs/assets/readme/badges/claude.svg?v=mobile-readable-3" width="300" alt="Claude Code"></a>
-<a href="https://www.npmjs.com/package/@claude-flow/codex"><img src="docs/assets/readme/badges/codex.svg?v=mobile-readable-3" width="300" alt="Codex Plugin"></a>
-</p>
-
-</div>
-
-<a id="start-here"></a>
-
-## <img src="docs/assets/readme/icons/terminal.svg" width="32" height="32" alt=""> Get started with Ruflo
-
-<img src="docs/assets/readme/icons/plugins.svg" width="28" height="28" alt=""> **Start in Claude Code** with core tools, the visual console and runtime mods. Requires Claude Code **2.1.287 or later**. Run inside Claude Code:
-
-```text
-/plugin marketplace add ruvnet/ruflo
-/plugin install ruflo-core@ruflo
-/plugin install ruflo-console@ruflo
-/plugin install ruflo-mods@ruflo
-/reload-plugins
-/ruflo
-```
-
-**Core** provides foundation tools. **Console** opens the agent cockpit. **Mods** add routing and policy enforcement inside Claude Code. Mods run with your account's permissions; review their code before installing.
-
-<img src="docs/assets/readme/icons/terminal.svg" width="28" height="28" alt=""> **Using Codex or another MCP enabled tool?** Use NPX for Ruflo project setup and connect your client to the Ruflo MCP server. Run the setup wizard in your project terminal:
-
-```bash
-npx ruflo@latest init wizard
-```
-
-For clients that support local stdio MCP servers, configure **command** `npx` and **arguments** `["-y", "ruflo@latest", "mcp", "start"]`. The equivalent server command is:
-
-```bash
-npx -y ruflo@latest mcp start
-```
-
-MCP exposes Ruflo tools to your client. The console and mods above are Claude Code integrations; hook support depends on the client.
-
-[Compare install paths](#quick-start) · [Open the console](#console-walkthrough) · [User guide](docs/USERGUIDE.md)
-
-<div align="center">
-
-
-### Optional: ruOS Desktop
-
-<a href="https://ruos.cognitum.one"><img src="ruflo/assets/ruos-animated.svg" alt="ruOS — A desktop that runs itself" width="100%"></a>
-
-**Connect ruOS to ChatGPT or Claude via MCP:**
-
-```text
-https://ruos.cognitum.one/mcp
-```
-
-
-
-<!-- RuVector promo -->
-<a href="https://github.com/ruvnet/ruvector"><img src="docs/assets/readme/ruvector-promo-depth.svg" width="100%" alt="RuVector: Give your agents memory. Local vector search, persistent context, graph relationships and feedback learning. Explore RuVector."></a>
-
-```bash
-npx ruvector
-```
-
-
-
+<!-- Ecosystem strip (collapsed visually with flat-square) -->
+[![🕸️ RuVector Agentic DB](https://img.shields.io/badge/RuVector_Agentic-DB-06b6d4?style=flat-square&logoColor=white&logo=graphql)](https://github.com/ruvnet/ruvector)
+[![Ecosystem downloads](https://img.shields.io/badge/ecosystem%20downloads-8.1M%2B-blue?style=flat-square&logo=npm)](https://github.com/ruvnet/ruflo/blob/main/data/clone-data.proof.json)
+[![Git clones (14d)](https://img.shields.io/badge/git%20clones%2014d-106k-blueviolet?style=flat-square&logo=github)](https://github.com/ruvnet/ruflo/blob/main/data/clone-data.ledger.json)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-Plugin-D97757?style=flat-square&logoColor=white&logo=anthropic)](https://github.com/ruvnet/claude-flow)
+[![Codex Plugin](https://img.shields.io/badge/Codex-Plugin-412991?style=flat-square&logoColor=white&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI%2BPHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0yMi4yODIgOS44MjFhNS45ODUgNS45ODUgMCAwIDAtLjUxNi00LjkxIDYuMDQ2IDYuMDQ2IDAgMCAwLTYuNTEtMi45QTYuMDY1IDYuMDY1IDAgMCAwIDQuOTgxIDQuMThhNS45ODUgNS45ODUgMCAwIDAtMy45OTggMi45IDYuMDQ2IDYuMDQ2IDAgMCAwIC43NDMgNy4wOTcgNS45OCA1Ljk4IDAgMCAwIC41MSA0LjkxMSA2LjA1MSA2LjA1MSAwIDAgMCA2LjUxNSAyLjlBNS45ODUgNS45ODUgMCAwIDAgMTMuMjYgMjRhNi4wNTYgNi4wNTYgMCAwIDAgNS43NzItNC4yMDYgNS45OSA1Ljk5IDAgMCAwIDMuOTk4LTIuOSA2LjA1NiA2LjA1NiAwIDAgMC0uNzQ3LTcuMDczek0xMy4yNiAyMi40M2E0LjQ3NiA0LjQ3NiAwIDAgMS0yLjg3Ni0xLjA0bC4xNDItLjA4IDQuNzc4LTIuNzU4YS43OTUuNzk1IDAgMCAwIC4zOTMtLjY4MXYtNi43MzdsMi4wMiAxLjE2OGEuMDcxLjA3MSAwIDAgMSAuMDM4LjA1MnY1LjU4M2E0LjUwNCA0LjUwNCAwIDAgMS00LjQ5NSA0LjQ5NHpNMy42IDE4LjMwNGE0LjQ3IDQuNDcgMCAwIDEtLjUzNS0zLjAxNGwuMTQyLjA4NSA0Ljc4MyAyLjc1OWEuNzcxLjc3MSAwIDAgMCAuNzgxIDBsNS44NDMtMy4zNjl2Mi4zMzJhLjA4LjA4IDAgMCAxLS4wMzMuMDYyTDkuNzQgMTkuOTVhNC41IDQuNSAwIDAgMS02LjE0LTEuNjQ2ek0yLjM0IDcuODk2YTQuNDg1IDQuNDg1IDAgMCAxIDIuMzY2LTEuOTczVjExLjZhLjc2Ni43NjYgMCAwIDAgLjM4OC42NzdsNS44MTUgMy4zNTQtMi4wMiAxLjE2OGEuMDc2LjA3NiAwIDAgMS0uMDcyIDBsLTQuODMtMi43ODZBNC41MDQgNC41MDQgMCAwIDEgMi4zNCA3Ljg3MnptMTYuNTk3IDMuODU1LTUuODMzLTMuMzg3IDIuMDE2LTEuMTY1YS4wNzYuMDc2IDAgMCAxIC4wNzEgMGw0LjgzIDIuNzkxYTQuNDk0IDQuNDk0IDAgMCAxLS42NzYgOC4xMDR2LTUuNjc3YS43OS43OSAwIDAgMC0uNDA3LS42Njd6bTIuMDEtMy4wMjMtLjE0MS0uMDg1LTQuNzc0LTIuNzgyYS43NzYuNzc2IDAgMCAwLS43ODUgMEw5LjQwOSA5LjIzVjYuODk3YS4wNjYuMDY2IDAgMCAxIC4wMjgtLjA2Mmw0LjgzLTIuNzg3YTQuNDk5IDQuNDk5IDAgMCAxIDYuNjggNC42NnpNOC4zMDcgMTIuODYzbC0yLjAyLTEuMTY0YS4wOC4wOCAwIDAgMS0uMDM4LS4wNTdWNi4wNzRhNC40OTkgNC40OTkgMCAwIDEgNy4zNzYtMy40NTRsLS4xNDIuMDgtNC43NzggMi43NThhLjc5NS43OTUgMCAwIDAtLjM5My42ODJ6bTEuMDk3LTIuMzY2IDIuNjAyLTEuNSAyLjYwNyAxLjV2Mi45OTlsLTIuNTk3IDEuNS0yLjYwNy0xLjVaIi8%2BPC9zdmc%2B)](https://www.npmjs.com/package/@claude-flow/codex)
 
 # Ruflo
 
-[English](README.md) · [简体中文](README.zh-CN.md)
-
+**An agent meta-harness for Claude Code and Codex.**
 
 [![RuFlo Explained — build an AI team that plans, remembers, tests, and improves](docs/assets/ruflo-explained/ch14.jpg)](docs/ruflo-explained.md)
 
@@ -92,16 +29,13 @@ A 14-chapter guide: from the basic idea to a first useful task, then memory, age
 
 One `npx ruflo init` gives Claude Code a nervous system: agents self-organize into swarms, learn from every task, remember across sessions, and — with federation — securely talk to agents on other machines without leaking data. You keep writing code. Ruflo handles the coordination.
 
-<p align="center"><img src="docs/assets/readme/learning-cinematic-compact.svg" width="100%" alt="Ruflo trajectory learning: branching memory paths, outcome feedback, contrastive AI and local learning. No LLM required for local vector retrieval and contrastive updates; agent execution may still use an LLM."></p>
-
-<sub>Conceptual learning loop. Local vector retrieval and contrastive updates can run without an LLM; embeddings and configured learning modules are still required. See the <a href="v3/@claude-flow/cli/src/services/ruvector-training.ts">RuVector training integration</a> and <a href="v3/@claude-flow/neural/src/modes/balanced.ts">trajectory contrastive learning</a>.</sub>
-
-<details>
-<summary>Architecture in text</summary>
-
-User → Ruflo (CLI/MCP) → Router → Swarm → Agents → Memory → LLM providers. Memory feeds useful experience back into routing. This is a conceptual flow, not a live execution trace.
+```
+Self-Learning / Self-Optimizing Agent Architecture
 
-</details>
+User --> Ruflo (CLI/MCP) --> Router --> Swarm --> Agents --> Memory --> LLM Providers
+                          ^                           |
+                          +---- Learning Loop <-------+
+```
 
 > **New to Ruflo?** You don't need to learn 314 MCP tools or 26 CLI commands. After `init`, just use Claude Code normally — the hooks system automatically routes tasks, learns from successful patterns, and coordinates agents in the background.
 
@@ -114,50 +48,10 @@ User → Ruflo (CLI/MCP) → Router → Swarm → Agents → Memory → LLM prov
 
 ---
 
-<p align="center"><img src="docs/assets/readme/console.svg" alt="Mission control: inspect agent work" width="100%"></p>
-
-<p align="center"><img src="docs/assets/ruflo-console-workflows.svg" width="952" height="964" alt="An animated recording of the ruflo console inside Claude Code: the boot (the neon sign and every area checked), then the Workflows page on a sample run: phases and agents with model, tokens and time; drilling from a run into one agent's activity, log and result; search; failure triage; cost; replay and compare; the control tab with a confirm card; and the mission autopilot panel"></p>
-
-<img src="docs/assets/readme/console-icon-workflows.svg" width="28" height="28" alt=""> **Your agent cockpit.** Track workflows, agents, models, tokens and cost beside Claude Code. The animation shows startup checks and a **sample workflow**, not a live session.
-
-<img src="docs/assets/readme/console-icon-inspect.svg" width="28" height="28" alt=""> **Inspect any run.** Open agent logs and results, search, triage failures, replay and compare. Start with `npx ruflo init`, restart Claude Code, then `/ruflo`. [Full console tour](docs/assets/ruflo-console-walkthrough-wide.gif).
-
-<img src="docs/assets/readme/console-icon-control.svg" width="28" height="28" alt=""> **Let Claude drive. You set the limits.** Enable **Settings → Claude control** to navigate and run console actions. Choose `read`, `write`, `manage` or `full`, with `ask` or `auto` approval. The current default is **read + ask**; raising the level is your choice. Actions above your permission level are refused, and network, spending and destructive actions require confirmation even in `auto`. Review the live action log or press **Take back control** to stop Claude control. [Details](v3/docs/adr/ADR-444-claude-controls-the-console.md).
-
-<a id="console-walkthrough"></a>
-
-### One task: create a mission with Claude
-
-<img src="docs/assets/readme/console-icon-workflows.svg" width="28" height="28" alt=""> **Watch the recorded console session below.** Claude creates a mission, opens the Learning and Security pages, and reports its actions in Overview.
-
-1. **Set the boundary.** Install the console using the commands below, open `/ruflo`, then choose **Settings → Claude control → write + ask**.
-2. **Give a concrete request.** Try: “Create a mission to add a dark mode toggle. Show me the mission and its status.”
-3. **Approve creation.** Claude opens Missions and sets the goal. Confirm the pending create action in the console.
-4. **Verify the result.** Check that Missions contains the goal and Overview records the action. Creating a mission does not mean the feature has been implemented.
-5. **Keep control.** **Take back control** pauses Claude's console tools. A later call should be refused until you restore control.
-
-**What the recording demonstrates:** a real Claude Haiku session with `write + auto`, mission creation, page navigation, a refused swarm stop, and control being taken back. The steps above use `ask` so you approve creation yourself. The separate workflow animation uses sample data; neither is evidence of completed swarm work or memory recall.
-
-[Implementation and recorded test findings](v3/docs/adr/ADR-444-claude-controls-the-console.md) · [Reproduction script](plugins/ruflo-console/scripts/e2e-control.sh)
-
-<p align="center"><img src="docs/assets/ruflo-console-claude-control.gif" alt="Claude Code with the ruflo console beside it: Claude sets a mission goal, creates the mission and opens the Learning, Security and Overview pages through the console tools; the Claude control dashboard logs each action; swarm-stop is refused because it needs the full level; the person clicks Take back control and the next request is refused"></p>
-
-
-**Install the mods from the ruflo marketplace** (Claude Code 2.1.287 or later; mods run with your account's permissions and are not sandboxed, so read the code first):
-
-```text
-/plugin marketplace add ruvnet/ruflo
-/plugin install ruflo-console@ruflo
-/plugin install ruflo-mods@ruflo
-/reload-plugins
-```
-
-`ruflo-console` is the cockpit above, `ruflo-mods` routes prompts and enforces policy in-process, `ruflo-swarm` shows the swarm in a pane, and `ruflo-ruos` adds the ruOS status segment. Open `/plugin` to confirm they appear in the active mods line. Inside the console, `/ruflo market` is the Plugin Catalog: every ruflo plugin, mod and skill with what it ships, and buttons to install, enable, disable and update (each asks first).
+![Ruflo Plugins](./ruflo-plugins.gif)
 
 ## Quick Start
 
-<p align="center"><img src="docs/assets/readme/quick-start.svg" alt="Start building with Ruflo" width="100%"></p>
-
 There are **two different install paths** with very different surface areas. Pick based on what you need (#1744):
 
 | | **Claude Code Plugin** | **CLI install (`npx ruflo init`)** |
@@ -268,7 +162,7 @@ This adds slash commands and agent definitions. `ruflo-core` (installed above) d
 
 </details>
 
-### <img src="docs/assets/readme/icons/terminal.svg" width="28" height="28" alt=""> CLI Install
+### CLI Install
 
 **macOS / Linux / WSL / Git-Bash:**
 
@@ -292,50 +186,68 @@ npm install -g ruflo@latest
 
 > 💡 **Windows users:** the `curl ... | bash` form needs a POSIX shell (Git-Bash, WSL, MSYS). The `npx ruflo@latest init wizard` line works natively in PowerShell and cmd. If you hit an `'bash' is not recognized` error, use the `npx` line instead — both end up running the same init flow.
 
-### <img src="docs/assets/readme/icons/network.svg" width="28" height="28" alt=""> MCP Server
+### MCP Server
 
 ```bash
 # Add Ruflo as an MCP server in Claude Code
 claude mcp add claude-flow -- npx ruflo@latest mcp start
 ```
 
----
+#### HTTP transport security
 
-## What You Get
+`ruflo mcp start -t http` exposes every registered tool over HTTP (`/rpc`, `/mcp`, `/ws`). The default `stdio` transport is not affected.
 
-<p align="center"><img src="docs/assets/readme/capabilities.svg" alt="Your agent toolkit" width="100%"></p>
+| Setting | Effect |
+|---|---|
+| `RUFLO_MCP_HTTP_TOKEN=<token>` | Require `Authorization: Bearer <token>` on every request. Failure is a bare `401`. The token is compared in constant time and is never logged. Prefer this over `--auth-token`, which is visible in `ps`. |
+| `--auth-token-file <path>` | Read the token from a file (one line). Takes precedence over the env var. |
+| `--auth-token <token>` | Same, on the command line (visible in argv; highest precedence). |
+| `RUFLO_MCP_ALLOW_UNAUTHENTICATED_HTTP=1` | Allow an unauthenticated bind to a non-loopback `--host`. Only for a trusted network boundary or an authenticating reverse proxy. |
 
-<table>
-<tr><td width="50%"><a href="plugins/ruflo-swarm/README.md"><img src="docs/assets/readme/card-swarm.svg" width="100%" alt="Agent teams"></a></td><td width="50%"><a href="plugins/ruflo-rag-memory/README.md"><img src="docs/assets/readme/card-memory.svg" width="100%" alt="Persistent memory"></a></td></tr>
-<tr><td width="50%"><a href="plugins/ruflo-intelligence/README.md"><img src="docs/assets/readme/card-learning.svg" width="100%" alt="Learning loops"></a></td><td width="50%"><a href="plugins/ruflo-security-audit/README.md"><img src="docs/assets/readme/card-security.svg" width="100%" alt="Security controls"></a></td></tr>
-<tr><td width="50%"><a href="https://ruvnet.github.io/ruflo"><img src="docs/assets/readme/card-plugins.svg" width="100%" alt="Plugin marketplace"></a></td><td width="50%"><a href="plugins/ruflo-ruvllm/README.md"><img src="docs/assets/readme/card-routing.svg" width="100%" alt="Models and routing"></a></td></tr>
-</table>
+A token must be 16-512 printable ASCII characters (no spaces). `GET /health` stays public and returns only `{"status":"ok"}` when a token is set. Tokens are supported for `-t http` only; `-t websocket` rejects one.
 
-| Capability | Description |
-|------------|-------------|
-| <img src="docs/assets/readme/icons/agents.svg" width="28" height="28" alt=""> **100+ Agents** | Specialized agents for coding, testing, security, docs, architecture |
-| <img src="docs/assets/readme/icons/network.svg" width="28" height="28" alt=""> **Comms Layer** | Zero-trust federation — agents across machines/orgs discover, authenticate, and exchange work securely |
-| <img src="docs/assets/readme/icons/swarm.svg" width="28" height="28" alt=""> **Swarm Coordination** | Hierarchical, mesh, and adaptive topologies with consensus |
-| <img src="docs/assets/readme/icons/learning.svg" width="28" height="28" alt=""> **Self-Learning** | SONA neural patterns, ReasoningBank, trajectory learning |
-| <img src="docs/assets/readme/icons/memory.svg" width="28" height="28" alt=""> **Vector Memory** | HNSW-indexed AgentDB — measured ~1.9x faster at N=20k, ~3.2x–4.7x at N=5k vs brute force (recall@10 ~0.99); ANN wins above the crossover, ties/loses at small N. See [audit](docs/reviews/intelligence-system-audit-2026-05-29.md) + [`scripts/benchmark-intelligence.mjs`](scripts/benchmark-intelligence.mjs) |
-| <img src="docs/assets/readme/icons/workers.svg" width="28" height="28" alt=""> **Background Workers** | 12 auto-triggered workers (audit, optimize, testgaps, etc.) |
-| <img src="docs/assets/readme/icons/plugins.svg" width="28" height="28" alt=""> **Plugin Marketplace** | 33 native Claude Code plugins + 21 npm plugins |
-| <img src="docs/assets/readme/icons/routing.svg" width="28" height="28" alt=""> **Multi-Provider** | Claude, GPT, Gemini, Cohere, Ollama with smart routing |
-| <img src="docs/assets/readme/icons/security.svg" width="28" height="28" alt=""> **Security** | AIDefence, input validation, CVE remediation, path traversal prevention |
-| <img src="docs/assets/readme/icons/federation.svg" width="28" height="28" alt=""> **Agent Federation** | Cross-installation agent collaboration with zero-trust security |
-| <img src="docs/assets/readme/icons/audit.svg" width="28" height="28" alt=""> **[MetaHarness](docs/metaharness-user-guide.md)** | Audit your AI agent setup before you ship. Grade readiness (1-100), scan tool configs for security issues, snapshot the whole project to catch regressions over time, and find templates that match your repo. `ruflo eject` turns a ruflo project into a standalone agent toolkit with its own name. [Full guide](docs/metaharness-user-guide.md). |
+| `--host` | no token | token set |
+|---|---|---|
+| `localhost`, `127.0.0.1`, `::1` | starts, **unauthenticated** | starts, token required |
+| anything else (`0.0.0.0`, `::`, a LAN IP, `127.0.0.2`, `[::1]`, `LOCALHOST`) | **refuses to start** unless `RUFLO_MCP_ALLOW_UNAUTHENTICATED_HTTP=1` | starts, token required |
 
-### <img src="docs/assets/readme/icons/learning.svg" width="28" height="28" alt=""> Learning from experience
+Without a token, a loopback server is still unauthenticated: any process on the machine, and any web page that can reach it via DNS rebinding, can call tools. Set `RUFLO_MCP_HTTP_TOKEN` whenever the HTTP transport is used.
 
-<p align="center"><img src="docs/assets/readme/learning-flow.svg" width="100%" alt="Recall, execute, evaluate, store, adapt and reuse: an illustrative agent learning cycle."></p>
+**Upgrading:** binding off loopback (for example `--host 0.0.0.0` in Docker) now needs a token or the opt-out above; otherwise the server exits with an error.
 
-Useful trajectories and task feedback can inform future work. Results depend on the configured memory, learning components and quality of feedback. [Learning plugin](plugins/ruflo-intelligence/README.md).
+---
 
-### Agent Federation — Slack for Agents
+## What You Get
 
-<p align="center"><img src="docs/assets/readme/federation.svg" alt="Connected intelligence across machines" width="100%"></p>
+| Capability | Description |
+|------------|-------------|
+| 🤖 **100+ Agents** | Specialized agents for coding, testing, security, docs, architecture |
+| 📡 **Comms Layer** | Zero-trust federation — agents across machines/orgs discover, authenticate, and exchange work securely |
+| 🐝 **Swarm Coordination** | Hierarchical, mesh, and adaptive topologies with consensus |
+| 🧠 **Self-Learning** | SONA neural patterns, ReasoningBank, trajectory learning |
+| 💾 **Vector Memory** | HNSW-indexed AgentDB — measured ~1.9x faster at N=20k, ~3.2x–4.7x at N=5k vs brute force (recall@10 ~0.99); ANN wins above the crossover, ties/loses at small N. See [audit](docs/reviews/intelligence-system-audit-2026-05-29.md) + [`scripts/benchmark-intelligence.mjs`](scripts/benchmark-intelligence.mjs) |
+| ⚡ **Background Workers** | 12 auto-triggered workers (audit, optimize, testgaps, etc.) |
+| 🧩 **Plugin Marketplace** | 33 native Claude Code plugins + 21 npm plugins |
+| 🔌 **Multi-Provider** | Claude, GPT, Gemini, Cohere, Ollama with smart routing |
+| 🛡️ **Security** | AIDefence, input validation, CVE remediation, path traversal prevention |
+| 🌐 **Agent Federation** | Cross-installation agent collaboration with zero-trust security |
+| 🔬 **[MetaHarness](docs/metaharness-user-guide.md)** | Audit your AI agent setup before you ship. Grade readiness (1-100), scan tool configs for security issues, snapshot the whole project to catch regressions over time, and find templates that match your repo. `ruflo eject` turns a ruflo project into a standalone agent toolkit with its own name. [Full guide](docs/metaharness-user-guide.md). |
 
-<p align="center"><img src="docs/assets/readme/federation-flow.svg" width="100%" alt="Outbound agent, data filtering, signing and encryption, identity verification, input checks and receiving agent."></p>
+### Agent Federation — Slack for Agents
+
+```
+Your Agent --> [ Remove secrets ] --> [ Sign message ] --> [ Encrypted channel ]
+                 Emails, SSNs,        Proves it came       No one reads it
+                 keys stripped         from you              in transit
+                                                                |
+                                                                v
+Their Agent <-- [ Block attacks ] <-- [ Check identity ] <------+
+                 Stops prompt          Rejects forgeries
+                 injection
+
+                          Audit trail on both sides.
+                  Trust builds over time. Bad behavior = instant downgrade.
+```
 
 Slack gave teams channels. Federation gives agents the same thing — **shared workspaces across trust boundaries**, where agents on different machines, orgs, or cloud regions can discover each other, prove who they are, and collaborate on tasks.
 
@@ -437,8 +349,6 @@ User --> Claude Code / CLI
 
 ## Documentation
 
-<p align="center"><img src="docs/assets/readme/documentation.svg" alt="Guides, architecture and verification" width="100%"></p>
-
 Four docs for four audiences:
 
 | Doc | When to read it |
@@ -469,8 +379,6 @@ User Guide section index:
 
 ## Support
 
-<p align="center"><img src="docs/assets/readme/support.svg" alt="Build with the Ruflo community" width="100%"></p>
-
 | Resource | Link |
 |----------|------|
 | Documentation | [User Guide](docs/USERGUIDE.md) |
@@ -479,10 +387,6 @@ User Guide section index:
 | Community | [Agentics Foundation Discord](https://discord.com/invite/dfxmpwkG2D) |
 | Powered by | [Cognitum.one](https://cognitum.one) |
 
-<p align="center"><img src="docs/assets/readme/signal-divider.svg" alt="Ruflo" width="100%"></p>
-
 ## License
 
 MIT - [RuvNet](https://github.com/ruvnet)
-
-<a href="https://cognitum.one"><img src="docs/assets/readme/cognitum-banner-v2.svg" width="100%" alt="Cognitum One: Ambient Intelligence at the edge of the Physical World. Explore cognitum.one."></a>

package/v3/@claude-flow/cli/catalog-manifest.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
-  "generation": 7,
-  "generatedAt": "2026-10-08T21:48:51.902Z",
-  "gitSha": "527796ae",
+  "generation": 6,
+  "generatedAt": "2026-09-17T21:28:47.530Z",
+  "gitSha": "702d1461",
   "catalog": {
-    "agents": 176,
-    "tools": 423,
+    "agents": 167,
+    "tools": 418,
     "skills": 34
   },
   "benchmark": null

package/v3/@claude-flow/cli/dist/src/commands/config.js

@@ -309,7 +309,7 @@ const resetCommand = {
     ],
     action: async (ctx) => {
         try {
-            const configPath = configManager.reset(ctx.cwd);
+            const configPath = configManager.reset(ctx.cwd, ctx.flags.section);
             output.writeln(`Configuration reset to defaults: ${configPath}`);
             return { success: true };
         }

package/v3/@claude-flow/cli/dist/src/mcp-tools/config-tools.js

@@ -35,12 +35,110 @@ function ensureConfigDir() {
         mkdirSync(dir, { recursive: true, mode: 0o700 });
     }
 }
+// Plain CLI files and legacy MCP envelopes share the same path. Keep the
+// original plain document so MCP writes remain readable by the CLI.
+const plainDocuments = new WeakMap();
+const STORE_METADATA = new Set(['scopes', 'version', 'updatedAt']);
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function flattenValues(document) {
+    const values = {};
+    function visit(value, key) {
+        if (isRecord(value) && Object.keys(value).length > 0) {
+            for (const [child, entry] of Object.entries(value))
+                visit(entry, `${key}.${child}`);
+        }
+        else {
+            Object.defineProperty(values, key, { value, enumerable: true, configurable: true, writable: true });
+        }
+    }
+    for (const [key, value] of Object.entries(document)) {
+        if (!STORE_METADATA.has(key))
+            visit(value, key);
+    }
+    // CLI reads literal dotted keys before traversing nested objects.
+    for (const [key, value] of Object.entries(document)) {
+        if (key.includes('.'))
+            Object.defineProperty(values, key, { value, enumerable: true, configurable: true, writable: true });
+    }
+    return values;
+}
+function readDefaultValue(store, key) {
+    const document = plainDocuments.get(store);
+    if (!document)
+        return store.values[key];
+    return Object.hasOwn(document, key) ? document[key] : getNestedValue(document, key);
+}
+function writeDefaultValue(store, key, value) {
+    const document = plainDocuments.get(store);
+    if (!document) {
+        store.values[key] = value;
+        return;
+    }
+    // Keep existing literal dotted keys; otherwise use the CLI's nested shape.
+    if (Object.hasOwn(document, key)) {
+        // Reuse the same segment validation as nested writes.
+        setNestedValue({}, key, value);
+        document[key] = value;
+    }
+    else {
+        setNestedValue(document, key, value);
+    }
+    store.values = flattenValues(document);
+}
+function deleteDefaultValue(store, key) {
+    const document = plainDocuments.get(store);
+    if (!document)
+        return Object.hasOwn(store.values, key) && delete store.values[key];
+    let target = document;
+    let leaf = key;
+    if (!Object.hasOwn(document, key)) {
+        const parts = key.split('.');
+        leaf = parts.pop();
+        for (const part of parts) {
+            if (!Object.hasOwn(target, part) || !isRecord(target[part]))
+                return false;
+            target = target[part];
+        }
+    }
+    const deleted = Object.hasOwn(target, leaf) && delete target[leaf];
+    store.values = flattenValues(document);
+    return deleted;
+}
+function replaceDefaultValues(store, values) {
+    const document = plainDocuments.get(store);
+    if (!document) {
+        store.values = values;
+        return;
+    }
+    for (const key of Object.keys(document)) {
+        if (!STORE_METADATA.has(key))
+            delete document[key];
+    }
+    for (const [key, value] of Object.entries(values))
+        writeDefaultValue(store, key, value);
+}
 function loadConfigStore() {
     try {
         const path = getConfigPath();
         if (existsSync(path)) {
             const data = readFileSync(path, 'utf-8');
-            return JSON.parse(data);
+            const document = JSON.parse(data);
+            const isEnvelope = isRecord(document) && isRecord(document.values)
+                && isRecord(document.scopes) && typeof document.version === 'string'
+                && typeof document.updatedAt === 'string';
+            if (isRecord(document) && !isEnvelope) {
+                const store = {
+                    values: flattenValues(document),
+                    scopes: isRecord(document.scopes) ? document.scopes : {},
+                    version: typeof document.version === 'string' ? document.version : '3.0.0',
+                    updatedAt: typeof document.updatedAt === 'string' ? document.updatedAt : '',
+                };
+                plainDocuments.set(store, document);
+                return store;
+            }
+            return document;
         }
     }
     catch {
@@ -56,13 +154,20 @@ function loadConfigStore() {
 function saveConfigStore(store) {
     ensureConfigDir();
     store.updatedAt = new Date().toISOString();
-    writeFileSync(getConfigPath(), JSON.stringify(store, null, 2), 'utf-8');
+    const document = plainDocuments.get(store);
+    if (document) {
+        document.updatedAt = store.updatedAt;
+        if (Object.keys(store.scopes).length > 0 || Object.hasOwn(document, 'scopes')) {
+            document.scopes = store.scopes;
+        }
+    }
+    writeFileSync(getConfigPath(), JSON.stringify(document ?? store, null, 2), 'utf-8');
 }
 function getNestedValue(obj, key) {
     const parts = key.split('.');
     let current = obj;
     for (const part of parts) {
-        if (current && typeof current === 'object' && part in current) {
+        if (current && typeof current === 'object' && Object.hasOwn(current, part)) {
             current = current[part];
         }
         else {
@@ -95,7 +200,7 @@ function setNestedValue(obj, key, value) {
     let current = obj;
     for (let i = 0; i < parts.length - 1; i++) {
         const part = parts[i];
-        if (!(part in current) || typeof current[part] !== 'object') {
+        if (!Object.hasOwn(current, part) || current[part] === null || typeof current[part] !== 'object') {
             current[part] = {};
         }
         current = current[part];
@@ -134,7 +239,7 @@ export const configTools = [
                 value = store.scopes[scope][key];
             }
             if (value === undefined) {
-                value = store.values[key];
+                value = readDefaultValue(store, key);
             }
             if (value === undefined) {
                 value = DEFAULT_CONFIG[key];
@@ -144,7 +249,7 @@ export const configTools = [
                 value,
                 scope,
                 exists: value !== undefined,
-                source: value !== undefined ? (store.values[key] !== undefined ? 'stored' : 'default') : 'none',
+                source: value !== undefined ? (readDefaultValue(store, key) !== undefined ? 'stored' : 'default') : 'none',
             };
         },
     },
@@ -175,9 +280,9 @@ export const configTools = [
             const key = input.key;
             const value = input.value;
             const scope = input.scope || 'default';
-            const previousValue = store.values[key];
+            const previousValue = readDefaultValue(store, key);
             if (scope === 'default') {
-                store.values[key] = value;
+                writeDefaultValue(store, key, value);
             }
             else {
                 if (!store.scopes[scope]) {
@@ -289,8 +394,7 @@ export const configTools = [
             if (key) {
                 // Reset specific key
                 if (scope === 'default') {
-                    if (key in store.values) {
-                        delete store.values[key];
+                    if (deleteDefaultValue(store, key)) {
                         resetKeys.push(key);
                     }
                 }
@@ -303,7 +407,7 @@ export const configTools = [
                 // Reset all keys in scope
                 if (scope === 'default') {
                     resetKeys = Object.keys(store.values);
-                    store.values = { ...DEFAULT_CONFIG };
+                    replaceDefaultValues(store, { ...DEFAULT_CONFIG });
                 }
                 else if (store.scopes[scope]) {
                     resetKeys = Object.keys(store.scopes[scope]);
@@ -385,10 +489,11 @@ export const configTools = [
             const importedKeys = Object.keys(config);
             if (scope === 'default') {
                 if (merge) {
-                    Object.assign(store.values, config);
+                    for (const [key, value] of Object.entries(config))
+                        writeDefaultValue(store, key, value);
                 }
                 else {
-                    store.values = { ...DEFAULT_CONFIG, ...config };
+                    replaceDefaultValues(store, { ...DEFAULT_CONFIG, ...config });
                 }
             }
             else {

package/v3/@claude-flow/cli/dist/src/memory/memory-initializer.js

@@ -1235,7 +1235,11 @@ export async function ensureSchemaColumns(dbPath, options = {}) {
             if (columnsAdded.includes('status') || existingColumns.has('status')) {
                 try {
                     db.run(`UPDATE memory_entries SET status = 'active' WHERE status IS NULL`);
-                    modified = true;
+                    // #3918: only a backfill that changed rows dirties the image. Setting
+                    // this unconditionally rewrote every up-to-date store on each open (and,
+                    // with encryption at rest, with a fresh nonce, so the bytes changed too).
+                    if (db.getRowsModified() > 0)
+                        modified = true;
                 }
                 catch {
                     /* table is read-only or doesn't exist — skip */

package/v3/@claude-flow/cli/dist/src/services/config-file-manager.d.ts

@@ -18,8 +18,8 @@ export declare class ConfigFileManager {
     set(cwd: string, key: string, value: unknown): void;
     /** Create a new config file with defaults */
     create(cwd: string, overrides?: Record<string, unknown>, force?: boolean): string;
-    /** Reset config to defaults */
-    reset(cwd: string): string;
+    /** Reset all configuration or only the selected section to defaults. */
+    reset(cwd: string, section?: string): string;
     /** Export config to a specific path */
     exportTo(cwd: string, exportPath: string): void;
     /** Import config from a specific path */

package/v3/@claude-flow/cli/dist/src/services/config-file-manager.js

@@ -148,11 +148,30 @@ export class ConfigFileManager {
         this.configPath = targetPath;
         return targetPath;
     }
-    /** Reset config to defaults */
-    reset(cwd) {
+    /** Reset all configuration or only the selected section to defaults. */
+    reset(cwd, section = 'all') {
+        if (!['agents', 'swarm', 'memory', 'mcp', 'providers', 'all'].includes(section)) {
+            throw new Error(`Unknown configuration section: ${section}`);
+        }
         this.selectProject(cwd);
         const targetPath = this.findConfig(cwd) ?? path.resolve(cwd, CONFIG_FILENAMES[0]);
-        const config = structuredClone(DEFAULT_CONFIG);
+        const config = section === 'all'
+            ? structuredClone(DEFAULT_CONFIG)
+            : structuredClone(this.load(cwd) ?? {});
+        if (section === 'providers') {
+            // Provider defaults are supplied by the provider command, so remove
+            // only the persisted override, as a whole reset already does.
+            delete config.providers;
+        }
+        else if (section !== 'all') {
+            config[section] = structuredClone(DEFAULT_CONFIG[section]);
+        }
+        if (section !== 'all') {
+            for (const key of Object.keys(config)) {
+                if (key.startsWith(`${section}.`))
+                    delete config[key];
+            }
+        }
         this.writeAtomic(targetPath, config);
         this.config = config;
         this.configPath = targetPath;

package/v3/@claude-flow/cli/dist/src/services/policy-ledger-anchor.d.ts

@@ -22,6 +22,14 @@ export type AnchorAssessment = {
 };
 export type AnchorWriter = (file: string, value: unknown) => Promise<void>;
 export declare const anchorLogPath: (projectRoot: string) => string;
+/**
+ * Directory holding per-project trust material (anchor mirror, HMAC key).
+ * Resolved from the environment at call time (#3919): $XDG_CONFIG_HOME when it
+ * is absolute, else $HOME/.config (os.homedir() honours $HOME), so a scratch
+ * HOME keeps tests and sandboxed runs out of the developer's real home. An XDG
+ * user who already has trust state under the legacy ~/.config keeps using it.
+ */
+export declare function policyTrustRoot(): string;
 /**
  * How the stored anchors relate to `state`; read-only. `rebuild` is the
  * explicit-establish path: an unreadable log or mirror is treated as absent, but

package/v3/@claude-flow/cli/dist/src/services/policy-ledger-anchor.js

@@ -13,14 +13,29 @@
  */
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, realpathSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
-import { userInfo } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
 const LOG_FILE = 'ledger-anchors.json';
 const MIRROR_FILE = 'ledger-anchor-head.json';
 export const anchorLogPath = (projectRoot) => join(resolve(projectRoot), '.claude-flow', 'policy', LOG_FILE);
+/**
+ * Directory holding per-project trust material (anchor mirror, HMAC key).
+ * Resolved from the environment at call time (#3919): $XDG_CONFIG_HOME when it
+ * is absolute, else $HOME/.config (os.homedir() honours $HOME), so a scratch
+ * HOME keeps tests and sandboxed runs out of the developer's real home. An XDG
+ * user who already has trust state under the legacy ~/.config keeps using it.
+ */
+export function policyTrustRoot() {
+    const legacy = join(homedir(), '.config', 'ruflo', 'policy-trust');
+    const xdg = process.env.XDG_CONFIG_HOME;
+    if (!xdg || !isAbsolute(xdg))
+        return legacy;
+    const preferred = join(xdg, 'ruflo', 'policy-trust');
+    return !existsSync(preferred) && existsSync(legacy) ? legacy : preferred;
+}
 function mirrorPath(projectRoot) {
     const id = createHash('sha256').update(realpathSync(projectRoot)).digest('hex');
-    return join(userInfo().homedir, '.config', 'ruflo', 'policy-trust', id, MIRROR_FILE);
+    return join(policyTrustRoot(), id, MIRROR_FILE);
 }
 function entryHash(entry) {
     return createHash('sha256').update(JSON.stringify([

package/v3/@claude-flow/cli/dist/src/services/policy-runtime.js

@@ -5,7 +5,7 @@ import { closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync,
 import { dirname, join, resolve } from 'node:path';
 import { hostname, userInfo } from 'node:os';
 import { syncPolicyProjection } from '../mods/policy-projection.js';
-import { assessAnchors, recordAnchor } from './policy-ledger-anchor.js';
+import { assessAnchors, policyTrustRoot, recordAnchor } from './policy-ledger-anchor.js';
 const POLICY_DIR = join('.claude-flow', 'policy');
 const POLICY_FILE = 'state.json';
 const LOCK_FILE = 'state.lock';
@@ -194,7 +194,7 @@ async function writeJsonAtomic(file, value) {
     }
 }
 function trustPaths(projectRoot) {
-    const trustRoot = join(userInfo().homedir, '.config', 'ruflo', 'policy-trust');
+    const trustRoot = policyTrustRoot();
     const projectId = createHash('sha256').update(realpathSync(projectRoot)).digest('hex');
     const dir = join(trustRoot, projectId);
     return { key: join(dir, 'anchor.key'), anchor: join(dir, 'state.anchor.json') };

package/v3/@claude-flow/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.56.0",
+  "version": "3.56.1",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",