ennodia 0.3.0-rc.2 → 0.4.0

package/CONTRIBUTING.md

@@ -104,15 +104,14 @@ exists solely on that channel.
 - `bin/ennodia`
 - source files that the Bun runtime needs
 - README, LICENSE, CONTRIBUTING, and documentation files
-- benchmark fixtures
 
 The core npm package must not include these items:
 
 - `.github/`, `AGENTS.md`, or `CLAUDE.md`
 - `bun.lock`, `src/dev/`, or `src/io.ts`
-- `*.test.ts`, `packages/`, or `website/`
+- `*.test.ts`, `bench/`, `packages/`, or `website/`
 
-JSR publishes the TypeScript source and docs, but not benchmark fixtures.
+JSR publishes the TypeScript source and docs.
 The IO npm package must include `bin/ennodia-io`, its `src/` files, and its
 README. It has an exact runtime dependency on the matching `ennodia` version.
 The release workflow publishes the core package first. The IO package stays
@@ -152,22 +151,6 @@ Community aggregators (Glama, PulseMCP, mcp.so, Smithery) index
 GitHub and the official registry automatically or accept one-time
 submissions. They do not need per-release updates.
 
-## Benchmarks
-
-The deterministic benchmark suite is:
-
-```sh
-bun run bench:bug-recall
-```
-
-Live harness benchmarks use:
-
-```sh
-bun run bench:bug-recall:live
-```
-
-Live runs are intentionally not part of `bun run verify`.
-
 ## Security
 
 Do not commit credentials, provider tokens, `.env` files, or private tool

package/README.md

@@ -47,6 +47,8 @@ For manual setup, add this Model Context Protocol (MCP) server to your client:
 }
 ```
 
+Ennodia loads six core tools by default. Add `"--tools", "all"` to `args` for the [full tool set](https://ennodia.cherninlab.com/docs/reference/mcp-tools/#tool-sets).
+
 Requirements: Bun `1.3.14` or newer, a compatible MCP client, and a supported agent with working provider access.
 `npx` downloads Ennodia. Bun runs it. You can also use `bunx ennodia`.
 
@@ -70,12 +72,8 @@ Native agents can also select unrequested skills from their own environment.
 
 ## See it in practice
 
-- [Building Ennodia with Ennodia](https://ennodia.cherninlab.com/docs/evidence/building-ennodia/): a worker patch, a failed login, and primary-agent corrections.
-- [Find stale documentation](https://ennodia.cherninlab.com/docs/evidence/docs-drift/): a small review with known answers.
-- [Try a skill separately](https://ennodia.cherninlab.com/docs/evidence/skill-trial/): two attempts against the same contract.
-
-The existing saved-answer benchmark is a regression check, not a live speed or cost comparison.
-[Measurement plan](https://ennodia.cherninlab.com/docs/evidence/measurement/)
+- [Can Gemini hear this file?](https://ennodia.cherninlab.com/articles/can-gemini-hear-this-file/): a Codex conversation hands an audio file to Gemini through Antigravity.
+- [Measurement plan](https://ennodia.cherninlab.com/docs/evidence/measurement/): how Ennodia will compare single agents with teams on public benchmarks.
 
 ## Data and limits
 
@@ -107,6 +105,7 @@ bun run verify
 
 ### Experimental Pragmatic mode
 
-In `ennodia@next`, delegate bounded investigation or patch proposals to an explicitly selected model.
+Version 0.3.0 supports independent model attempts, tailored planning, skill trials and evidence comparison.
+The published `ennodia@next` recipes retain the earlier single-worker restriction.
 [Pragmatic mode](docs/guides/pragmatic-mode.md) keeps bulky evidence outside the main conversation and returns findings for verification.
 Savings are not yet validated.

package/docs/comparisons/agent-frameworks.md

@@ -1,5 +1,5 @@
 ---
-title: Ennodia vs Agent Frameworks
+title: Ennodia vs agent frameworks
 description: How Ennodia differs from general-purpose agent frameworks such as LangGraph, AutoGen, CrewAI, and similar systems.
 ---
 
@@ -11,14 +11,14 @@ Ennodia is less general on purpose. Its small Model Context Protocol (MCP)
 interface lets a primary agent request help from installed agent command-line
 interfaces (CLIs). The primary agent can then inspect the result.
 
-## Choose an Agent Framework When
+## Choose an agent framework when
 
 - You define the agent workflow.
 - You need custom roles, memory, state, routing, or persistence.
 - The agent system is part of your application or service.
 - You want code-level control over every edge in the workflow.
 
-## Choose Ennodia When
+## Choose Ennodia when
 
 - You do not want to build an agent system.
 - You want a local MCP tool that works with installed agent CLIs.
@@ -29,13 +29,13 @@ interfaces (CLIs). The primary agent can then inspect the result.
   remains a separate, validated action.
 - You want the primary agent to remain in charge.
 
-## Key Difference
+## Key difference
 
 Agent frameworks provide components for custom agent systems. Ennodia is an
 orchestration helper for an active agent. Its Plan Advisor produces inert plan
 data. It does not create a persistent autonomous team or execute the proposal.
 
-## Common Mistake
+## Common mistake
 
 Do not claim that Ennodia is more powerful than a framework. It is deliberately
 smaller. A user can add multi-agent review to a current local workflow. This

package/docs/comparisons/autogen.md

@@ -11,14 +11,14 @@ systems.
 Ennodia is not a framework for a new multi-agent application. It is a local
 Model Context Protocol (MCP) server that an active agent can call.
 
-## Choose AutoGen When
+## Choose AutoGen when
 
 - You want to create a multi-agent system in application code.
 - You need programmable agent roles, event handling, message passing, and custom
   workflow control.
 - Your product needs a framework-level architecture.
 
-## Choose Ennodia When
+## Choose Ennodia when
 
 - The primary workflow uses Codex, Claude Code, OpenCode,
   Antigravity, or another MCP-capable client.
@@ -29,13 +29,13 @@ Model Context Protocol (MCP) server that an active agent can call.
 - You want a Plan Advisor to suggest explicit harness, model, and skill
   assignments. Plan Advisor has no execution control.
 
-## Key Difference
+## Key difference
 
 AutoGen helps developers create multi-agent applications. Ennodia lets one agent
 request help from other installed agents. A Plan Advisor can propose a bounded
 team. The proposal stays inert until the caller explicitly starts it.
 
-## Common Mistake
+## Common mistake
 
 Do not compare them only by "number of agents." The important question is the
 location of the orchestration. It can be in a custom application framework or a

package/docs/comparisons/chathub.md

@@ -10,14 +10,14 @@ web, browser extension, desktop, and mobile access.
 Ennodia is not a chat user interface (UI). An AI agent calls Ennodia during a
 task.
 
-## Choose ChatHub When
+## Choose ChatHub when
 
 - A human wants to compare chatbot answers visually.
 - The main workflow is interactive chat, not local Model Context Protocol (MCP)
   tool orchestration.
 - You want a polished multi-chat interface across hosted chatbots.
 
-## Choose Ennodia When
+## Choose Ennodia when
 
 - A primary agent needs help and can call MCP tools.
 - You want local agent command-line interfaces (CLIs) to run as child tasks.
@@ -26,12 +26,12 @@ task.
 - You want a Judge to map the differences. You want a Result Advisor to
   recommend an answer. The user does not need to grade all responses.
 
-## Key Difference
+## Key difference
 
 ChatHub helps a person compare chatbot outputs. Ennodia helps an agent delegate
 work to other local agents and inspect what happened.
 
-## Common Mistake
+## Common mistake
 
 Do not call Ennodia "ChatHub for agents." Explain that Ennodia provides task
 orchestration and traces. It does not provide a human chat comparison interface.

package/docs/comparisons/index.md

@@ -17,7 +17,7 @@ interface (API) subset to the same agents.
 Some adjacent tools have similar descriptions. They usually have different
 purposes.
 
-## Choose the Right Page
+## Choose the right page
 
 | Question | Page |
 | --- | --- |
@@ -30,7 +30,7 @@ purposes.
 | Is Ennodia model merging? | [Ennodia vs Model Merging](./model-merging/) |
 | What is the broader pattern? | [Second Opinions as Infrastructure](/docs/concepts/second-opinions/) |
 
-## What Ennodia Is
+## What Ennodia is
 
 Ennodia is:
 
@@ -47,7 +47,7 @@ Ennodia is:
   Result Advisor recommends an answer
 - a native Agent Skills bridge for harnesses that support `SKILL.md` folders
 
-## What Ennodia Is Not
+## What Ennodia is not
 
 Ennodia is not:
 
@@ -64,7 +64,7 @@ Durable model and skill preference memory is roadmap work. By default, Ennodia
 stores terminal run history locally. In-progress run and task state remains
 process-local.
 
-## Other Related Work
+## Other related work
 
 Some related ideas do not need a full page yet:
 

package/docs/comparisons/langgraph.md

@@ -10,14 +10,14 @@ manage, and deploy long-running, stateful agents.
 Ennodia is intentionally narrower. It does not require a custom graph,
 state machine, durable agent state, or application runtime.
 
-## Choose LangGraph When
+## Choose LangGraph when
 
 - You create an agentic application.
 - You need custom graph nodes, edges, state, persistence, or deployment control.
 - You want to model a workflow as programmable application infrastructure.
 - You own the application code and want a framework embedded in that code.
 
-## Choose Ennodia When
+## Choose Ennodia when
 
 - You have a primary agent in a Model Context Protocol (MCP) client.
 - You want that agent to request help from other installed local agent
@@ -28,7 +28,7 @@ state machine, durable agent state, or application runtime.
   validated start request.
 - You want a small MCP surface without a full application framework.
 
-## Key Difference
+## Key difference
 
 LangGraph helps developers create agent systems. Ennodia lets one agent delegate
 work to other local agents during a task.
@@ -36,7 +36,7 @@ work to other local agents during a task.
 Plan Advisor does not change this boundary: it can propose explicit worker
 assignments, but it cannot define arbitrary graph behavior or execute the plan.
 
-## Common Mistake
+## Common mistake
 
 Do not treat Ennodia as a lighter LangGraph runtime. Ennodia does not replace a
 programmable graph framework. It gives an active agent a simple way to request

package/docs/comparisons/mixture-of-agents.md

@@ -1,5 +1,5 @@
 ---
-title: Ennodia vs Mixture-of-Agents and Ensembles
+title: Ennodia vs Mixture-of-Agents and ensembles
 description: How Ennodia differs from Mixture-of-Agents papers, large language model ensembles, majority voting, and benchmark-oriented aggregation.
 ---
 
@@ -11,14 +11,14 @@ or task-specific aggregation over multiple model outputs.
 Ennodia uses some related ideas, but it is not primarily a benchmark ensemble
 or formal voting engine.
 
-## Choose Mixture-of-Agents or an Ensemble When
+## Choose Mixture-of-Agents or an ensemble when
 
 - You define an inference strategy.
 - You want a repeatable aggregation method over model outputs.
 - You need benchmarked quality gains for a specific task family.
 - You want majority vote, quorum, weighting, or another formal decision rule.
 
-## Choose Ennodia When
+## Choose Ennodia when
 
 - You want to run real local agent command-line interfaces (CLIs), not only raw
   model calls.
@@ -27,13 +27,13 @@ or formal voting engine.
   a result.
 - You need practical local delegation more than a research-grade ensemble.
 
-## Key Difference
+## Key difference
 
 Mixture-of-Agents and ensemble methods focus on output aggregation. Ennodia
 focuses on visible local agent orchestration. It then uses model-led Compare
 when multiple answers are available.
 
-## Common Mistake
+## Common mistake
 
 Do not describe Ennodia Compare as consensus. The Judge maps the candidate
 outputs, and the Result Advisor recommends an answer. It does not implement

package/docs/comparisons/model-merging.md

@@ -1,5 +1,5 @@
 ---
-title: Ennodia vs Model Merging
+title: Ennodia vs model merging
 description: How Ennodia differs from model merging tools such as mergekit and other weight-level model-combination approaches.
 ---
 
@@ -10,14 +10,14 @@ describes it as tools for model-checkpoint merging strategies.
 
 Ennodia does not change model weights.
 
-## Choose Model Merging When
+## Choose model merging when
 
 - You control compatible model weights.
 - You want one merged model artifact.
 - You want changes to happen before inference.
 - You evaluate merge recipes, checkpoints, or open-weight model behavior.
 
-## Choose Ennodia When
+## Choose Ennodia when
 
 - You want separate agents to run at task time.
 - You want to keep provider subscriptions and installed command-line interfaces
@@ -26,12 +26,12 @@ Ennodia does not change model weights.
   output.
 - You do not want to produce or host a new model artifact.
 
-## Key Difference
+## Key difference
 
 Model merging changes the model artifact. Ennodia coordinates multiple agents at
 runtime.
 
-## Common Mistake
+## Common mistake
 
 Do not describe Ennodia as model merging, fine-tuning, or weight composition. It
 is runtime orchestration over installed local agents.

package/docs/comparisons/openrouter.md

@@ -19,7 +19,7 @@ installed local agents.
 
 Ennodia does not sell hosted model access or proxy provider billing.
 
-## Choose OpenRouter When
+## Choose OpenRouter when
 
 - You want one hosted API for many models.
 - You want provider routing, fallback, and pricing controls behind one endpoint.
@@ -27,7 +27,7 @@ Ennodia does not sell hosted model access or proxy provider billing.
   command-line interface (CLI) runs.
 - You want centralized hosted model access outside a local desktop agent installation.
 
-## Choose Ennodia When
+## Choose Ennodia when
 
 - Your primary agent has a task in a Model Context Protocol (MCP) client.
 - You want that agent to request help from installed local agent command-line
@@ -41,7 +41,7 @@ Ennodia does not sell hosted model access or proxy provider billing.
   automatic execution. Plan Advisor cannot start the proposal.
 - You want a local HTTP bridge over those same agent runs.
 
-## Key Difference
+## Key difference
 
 OpenRouter routes hosted model API calls. Ennodia coordinates local agent
 subprocesses and can expose that local orchestration through MCP or IO.
@@ -49,7 +49,7 @@ subprocesses and can expose that local orchestration through MCP or IO.
 OpenRouter provides infrastructure for application developers. Ennodia is a
 local collaboration tool for agents in a code or research workflow.
 
-## Common Mistake
+## Common mistake
 
 Do not describe Ennodia as a cheaper OpenRouter or an OpenRouter replacement.
 It solves a different problem: visible delegation to installed local agents.

package/docs/concepts/compositional-audits.md

@@ -1,14 +1,16 @@
 ---
-title: Compositional Audits
+title: Compositional audits
 description: Split large reviews into focused slices, route them to local agents, and combine the results without losing traceability.
 ---
 
+The tools on this page are in the [full tool set](/docs/reference/mcp-tools/#tool-sets). Add `--tools all` to the Ennodia server arguments to load them.
+
 Large reviews work better when each agent gets a small, explicit slice. Ennodia
 supports this pattern with `ennodia_start_compositional`, existing task polling,
 and `ennodia_start_compare`. The `compositional-audit` skill gives reviewers a
 consistent rubric.
 
-## When To Use It
+## When to use it
 
 Use a compositional audit when the request mixes multiple risk types, such as:
 
@@ -20,7 +22,7 @@ Use a compositional audit when the request mixes multiple risk types, such as:
 One broad prompt can make every reviewer repeat the same surface-level answer.
 Slices make each response easier to verify and combine.
 
-## Good Slice Shape
+## Good slice shape
 
 A useful slice includes:
 
@@ -48,7 +50,7 @@ Return under 450 words:
 4. concrete recommendation
 ```
 
-## Current Workflow
+## Current workflow
 
 Install the skill into the harnesses you want to use:
 
@@ -150,14 +152,14 @@ When `compareReady` is true, pass the returned `readyTaskIds` to
 }
 ```
 
-## What To Avoid
+## What to avoid
 
 - Do not send the entire plan to every shard if the goal is faster, deeper review.
 - Do not mix unrelated evidence in one slice.
 - Do not treat failed, empty, or access-limited shard output as a normal review.
 - Do not claim consensus when the slices disagree.
 
-## Current Boundary
+## Current boundary
 
 `ennodia_estimate_compositional_budget` resolves and budgets slices without
 starting child agents. `ennodia_start_compositional` starts and budgets the shard

package/docs/concepts/data-governance.md

@@ -1,5 +1,5 @@
 ---
-title: Data Governance
+title: Data governance
 description: What Ennodia stores, what it does not store, and where data can leave the machine.
 ---
 
@@ -8,7 +8,7 @@ task output, or telemetry to an Ennodia-hosted service. The selected child agent
 CLIs can still contact their own model providers according to their own
 configuration, subscriptions, and policies.
 
-## What Ennodia Stores
+## What Ennodia stores
 
 Live process state is held in memory while the server runs. It includes run
 status, task IDs, command summaries, stdout/stderr captures, failures, timing,
@@ -44,7 +44,7 @@ A concurrent append in the short compaction window can also be lost.
 Set `ENNODIA_HISTORY=0` to disable durable history. Set
 `ENNODIA_HISTORY_DIR=/path/to/dir` to move the history file.
 
-## What Ennodia Does Not Know
+## What Ennodia does not know
 
 Budget estimates are preflight input-token estimates, not provider bills. They
 exclude provider-side system prompts, file reads performed inside a child
@@ -52,17 +52,13 @@ agent, tool loops, output tokens, cache behavior, and private subscription
 state. Subscription quota is reported as unknown unless a supported local
 surface exposes a reliable value.
 
-## Explicit Writes
+## Explicit writes
 
 `ennodia_install_skills` can write bundled `SKILL.md` folders into project or
 user skill locations. It defaults to `dryRun: true`, and project-scope installs
 require an explicit `cwd`.
 
-Benchmark runs write under `bench/results/bug-recall/` unless `--out` is
-provided. Those results are ignored by default because live outputs can include
-model text and environment metadata.
-
-## Practical Guidance
+## Practical guidance
 
 Use Ennodia for work that you are willing to send to the selected local agent
 CLIs. Use `cwd` deliberately. Prefer short staged case files over broad prompts.

package/docs/concepts/how-ennodia-works.md

@@ -1,5 +1,5 @@
 ---
-title: How Ennodia Works
+title: How Ennodia works
 description: A visible orchestration pipeline for optional plan advice, routing, budget checks, task watching, recovery, Judge, and Result Advisor passes.
 ---
 
@@ -8,7 +8,7 @@ turns one request into a visible orchestration. The normal entrypoint is
 `ennodia_run`. Lower-level task and Compare tools stay available for debugging
 and manual control.
 
-## Pipeline at a Glance
+## Pipeline at a glance
 
 | Stage | What happens | Main tools |
 | --- | --- | --- |

package/docs/concepts/interfaces-and-core.md

@@ -3,7 +3,7 @@ title: Interfaces and Core
 description: How Ennodia's Model Context Protocol (MCP) interface and shared core behavior relate to each other.
 ---
 
-## Current Shape
+## Current shape
 
 Ennodia has a Model Context Protocol (MCP) interface and a shared Core.
 

package/docs/concepts/second-opinions.md

@@ -1,5 +1,5 @@
 ---
-title: Second Opinions as Infrastructure
+title: Second opinions as infrastructure
 description: How to use Ennodia for independent artificial intelligence (AI) panels, decomposed reviews, and red-team prompts.
 ---
 
@@ -11,7 +11,7 @@ delegation to installed local agents with a visible trace. Compare turns
 multiple answers into a disagreement map and one usable result. The Judge maps
 the evidence, and the Result Advisor recommends the answer.
 
-## Three Patterns
+## Three patterns
 
 ### Replicate
 
@@ -79,7 +79,7 @@ Fan out prompts that argue against a proposal from different angles.
 Use this when the primary agent has a plausible plan and you want
 independent pressure before committing.
 
-## Staging Pattern
+## Staging pattern
 
 For larger reviews, have the primary agent stage a folder containing the case
 file: relevant paths, screenshots, dataset summaries, contracts, or decision
@@ -87,7 +87,7 @@ criteria. Then pass `cwd` to Ennodia so child agents can inspect the same local
 context independently. Keep staged material deliberate. Do not give every agent
 an unbounded workspace when a smaller evidence bundle will do.
 
-## Skills Carry Expertise
+## Skills carry expertise
 
 Use Agent Skills as reusable rubrics. A skill can define the review standard,
 expected evidence, output shape, and escalation rules. Ennodia installs bundled
@@ -104,7 +104,7 @@ run without inlining the full instructions into every prompt.
 - Exam or rubric QA: send the same staged rubric to multiple agents. Compare
   where their grading differs.
 
-## Honest Constraints
+## Honest constraints
 
 Ennodia supports careful review. A run usually takes minutes, not seconds.
 Compare adds two serial model passes after the child agents finish.

package/docs/evidence/index.md

@@ -1,18 +1,11 @@
 ---
-title: Examples and evidence
-description: Try small examples and inspect what Ennodia contributed to its own development.
+title: Evidence
+description: What Ennodia can show with recorded runs, and how it will measure the rest.
 ---
 
-# Examples and evidence
+Ennodia publishes a claim only with a recorded run behind it.
 
-Ennodia helps your primary agent try another approach and bring the findings back.
-These examples show the workflow and its limits.
+- [Can Gemini hear this file?](/articles/can-gemini-hear-this-file/) follows a Codex conversation that handed an audio file to Gemini through Antigravity.
+- The [measurement plan](./measurement.md) defines how Ennodia will compare single agents with teams on public benchmarks.
 
-- [Building Ennodia with Ennodia](./building-ennodia.md) follows a real development task, including an authentication failure and the primary agent’s corrections.
-- [Find stale documentation](./docs-drift.md) provides a small reproducible review exercise.
-- [Try a skill separately](./skill-trial.md) compares two reviews of the same function.
-- [Measurement plan](./measurement.md) defines the next comparative experiment.
-
-The examples are not a speed or cost benchmark.
-The [existing deterministic benchmark](../reference/benchmarks.md) checks saved answers against known findings.
-It does not measure live task completion time.
+For which models lead which kinds of work, see the [leaderboard figure](/#evidence) on the home page. Its values come from the public sources it links.

package/docs/evidence/measurement.md

@@ -3,8 +3,6 @@ title: How we will measure usefulness
 description: A planned comparison of complete tasks, including unsuccessful attempts and human intervention.
 ---
 
-# How we will measure usefulness
-
 Status: proposed experiment. Results are not available yet.
 
 The primary comparison uses the same main agent with and without Ennodia.
@@ -32,9 +30,12 @@ Compare time together with correctness. Excluding failures from timing can hide
 Report model tokens, estimated provider charges, and subscription payments separately.
 A token estimate is not a measured provider bill.
 
-[Terminal-Bench](https://github.com/harbor-framework/terminal-bench) is a candidate for terminal tasks.
-[SWE-bench](https://github.com/SWE-bench/SWE-bench) provides a separate direction for repository bug fixes.
+Two public sets fit a first pilot on one computer:
+
+- [Aider polyglot](https://github.com/Aider-AI/polyglot-benchmark): Exercism exercises in Python and JavaScript, graded by each exercise's own tests.
+- [MMAU test-mini](https://huggingface.co/datasets/gamma-lab-umd/MMAU-test-mini): multiple-choice questions about audio clips. It tests routing audio away from agents that cannot hear it.
+
+[Terminal-Bench](https://github.com/harbor-framework/terminal-bench) and [SWE-bench](https://github.com/SWE-bench/SWE-bench) need a container runtime for grading.
 Pin the exact dataset version and evaluation environment.
-Use small custom fixtures for skill trials and manual workflow measurements.
 
 This pilot can reveal useful patterns. It cannot establish universal superiority.