ennodia 0.3.0 → 0.4.1

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.

package/docs/getting-started.md

@@ -47,7 +47,7 @@ Compare adds a Judge pass and a Result Advisor pass after child agents finish.
 
 For a local development checkout, run `bun run verify` before relying on changes.
 
-## Manual Setup
+## Manual setup
 
 ### Requirements
 
@@ -72,7 +72,7 @@ To use Bun directly, run `bunx ennodia`.
 The JSR package `@cherninlab/ennodia` exposes TypeScript modules for import.
 Use the npm package for the stdio MCP executable.
 
-### Local Checkout
+### Local checkout
 
 Use a checkout to modify Ennodia:
 
@@ -83,7 +83,7 @@ bun install
 bun run verify
 ```
 
-### MCP Client Config
+### MCP client config
 
 ```json
 {
@@ -111,12 +111,15 @@ For a local checkout, use the source file:
 
 Replace `/absolute/path/to/ennodia` with your local repository path.
 
+Ennodia loads six core tools by default. For Plan Advisor, compositional slices, raw tasks, and skill installation, add `"--tools", "all"` to `args`. See [tool sets](/docs/reference/mcp-tools/#tool-sets).
+
 Use your client's supported configuration method.
 Preserve existing server entries.
 Reload the tools or restart the client if its setup instructions require this step.
 
-## Optional Team Advice
+## Optional team advice
 
+Team advice uses the [full tool set](/docs/reference/mcp-tools/#tool-sets).
 For a proposed work split, call `ennodia_start_plan_advice`. The Plan Advisor
 proposes explicit harness, model, and skill assignments. It cannot execute them.
 
@@ -138,7 +141,7 @@ completed answers. Then the Result Advisor recommends one answer.
 If Judge analysis is not available, the Result Advisor can use only the
 candidate outputs. The Compare result shows this condition.
 
-## Next Pages
+## Next pages
 
 - [Budgets and Limits](/docs/guides/budgets-and-limits/) explains
   `ennodia_estimate_budget` and run limits.
@@ -148,7 +151,7 @@ candidate outputs. The Compare result shows this condition.
   and installation notes.
 - [MCP Tools](/docs/reference/mcp-tools/) is the full parameter reference.
 
-## Expected Behavior
+## Expected behavior
 
 An Ennodia run is visible. You can inspect:
 

package/docs/guides/agent-skills.md

@@ -3,6 +3,8 @@ title: Agent Skills
 description: Install bundled Ennodia skills in native harness locations and tell child agents to use them during a run.
 ---
 
+Listing skills is in the core tool set. Installing them needs the [full tool set](/docs/reference/mcp-tools/#tool-sets).
+
 A new Agent Skill can help a task, add irrelevant advice, or make no difference.
 Try the skill in a separate Ennodia task and bring useful findings back to your main conversation.
 
@@ -11,9 +13,8 @@ Ennodia discovers that folder and requests the selected skill by name.
 It does not inline the full instructions into each delegated prompt.
 
 The primary agent can keep useful partial findings without adopting every recommendation.
-The [skill trial example](/docs/evidence/skill-trial/) shows a controlled small exercise.
 
-## List Available Skills
+## List available skills
 
 ```json
 {
@@ -27,7 +28,7 @@ The [skill trial example](/docs/evidence/skill-trial/) shows a controlled small
 The response includes bundled skills, installed native skills, searched
 directories, and load warnings.
 
-## Preview Installation
+## Preview installation
 
 Bundled skills use dry-run installation by default. The caller can inspect the
 planned writes before any change:
@@ -47,7 +48,7 @@ planned writes before any change:
 
 Review the planned paths. If they are correct, repeat with `dryRun: false`.
 
-## Use a Skill in a Run
+## Use a skill in a run
 
 ```json
 {
@@ -81,7 +82,7 @@ Bundled skills include:
 | `release-readiness` | Public release candidate checks. |
 | `benchmark-critic` | Benchmark credibility and reproducibility review. |
 
-## Native Install Locations
+## Native install locations
 
 | Harness | Project path | User path |
 | --- | --- | --- |

package/docs/guides/budgets-and-limits.md

@@ -1,8 +1,10 @@
 ---
-title: Budgets and Limits
+title: Budgets and limits
 description: How Ennodia estimates preflight input-token budgets and enforces local run limits before child agents start.
 ---
 
+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.
+
 Ennodia can estimate the input-token budget before a costly run starts. The
 estimate is a budget limit check, not a provider invoice. Child-task estimates
 are lower bounds.
@@ -13,7 +15,7 @@ not visible before the run.
 Use it before parallel work or long reviews. Also use it when the user limits
 cost, subscription use, or child-task count.
 
-## What the Estimate Includes
+## What the estimate includes
 
 `ennodia_estimate_budget` reports:
 
@@ -29,7 +31,7 @@ cost, subscription use, or child-task count.
 The estimate does not claim to know provider billing, output tokens, tool-call
 cost, cache behavior, harness-internal context, or private subscription quota.
 
-## Estimate Before a Run
+## Estimate before a run
 
 ```json
 {
@@ -54,7 +56,7 @@ If the estimate is too high, use one or more of these changes:
 - Decrease `maxOutputChars`.
 - Use a narrower first pass.
 
-## Enforce Limits on a Run
+## Enforce limits on a run
 
 The same budget object can be passed to `ennodia_run`:
 
@@ -78,7 +80,7 @@ Ennodia checks these local limits before child tasks start. The run fails early
 if estimated input tokens or the child-task count exceed a cap. Ennodia does
 not start the excess model work.
 
-## Subscription Limits
+## Subscription limits
 
 Subscription quota checks are conservative by design. Ennodia uses only
 supported local command-line interface (CLI) and application programming
@@ -93,7 +95,7 @@ supported local surface exposes a reliable account limit. An older fail-closed
 quota gate has been retired until at least one current harness exposes a real
 supported quota surface.
 
-## Practical Defaults
+## Practical defaults
 
 - Start with one agent and a narrow task. Add attempts when they address a specific uncertainty.
 - Use `maxOutputChars` to keep Compare input bounded.

package/docs/guides/pragmatic-mode.md

@@ -3,6 +3,8 @@ title: Pragmatic mode
 description: Organize independent model attempts and compare evidence against complete acceptance criteria.
 ---
 
+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.
+
 Pragmatic mode is an opt-in beta in `0.3.0`, available through `ennodia`.
 It helps your main agent delegate bounded work without loading entire logs or files into the main conversation.
 It does not guarantee lower costs or select the cheapest model automatically.

package/docs/guides/recipes.md

@@ -3,9 +3,7 @@ title: Recipes
 description: Three small ways to get useful help from Ennodia.
 ---
 
-# Start with one useful attempt
-
-A focused request is easier to check and integrate.
+Start with one useful attempt. A focused request is easier to check and integrate.
 Give your primary agent the relevant files, attempted fixes, and the result you need.
 
 ## A task is stuck
@@ -30,7 +28,6 @@ Show which skill and model were requested and what remains unverified.
 
 Check native installation with your agent before the task starts.
 A requested skill is not proof that the worker loaded it.
-Use the [small skill trial](/docs/evidence/skill-trial/) to practice comparing two attempts.
 
 ## Two answers disagree
 

package/docs/guides/running-better-audits.md

@@ -1,5 +1,5 @@
 ---
-title: Better Audits
+title: Better audits
 description: How Ennodia audits can detect product problems that users see, not only consistency issues.
 ---
 
@@ -11,7 +11,7 @@ This pass can find broken links, mismatched documentation, release metadata erro
 errors, and copy drift. It does not prove that the page is clear to a first-time
 visitor.
 
-## Quick Recipe
+## Quick recipe
 
 Use a source-grounded audit for answers that depend on documentation,
 standards, package behavior, or another product's public surface:
@@ -31,7 +31,7 @@ standards, package behavior, or another product's public surface:
 Install the skill first if the harness does not have it. See
 [Agent Skills](/docs/guides/agent-skills/).
 
-## Pick the Audit Mode
+## Pick the audit mode
 
 Name the failure mode you want reviewers to catch.
 
@@ -50,7 +50,7 @@ For a large review, split the work into focused slices. Do not send the entire
 prompt to each reviewer. See
 [Compositional Audits](/docs/concepts/compositional-audits/).
 
-## Landing Page Rubric
+## Landing page rubric
 
 For landing pages, require each reviewer to answer these questions:
 
@@ -64,7 +64,7 @@ For landing pages, require each reviewer to answer these questions:
 For Ennodia, use `mode: "parallel"` and `compare: true` for this type of review.
 A single source-only answer is not sufficient for product pages.
 
-## Include Rendered Evidence
+## Include rendered evidence
 
 Source-only review misses visual problems. Before an Ennodia website review,
 include desktop and mobile screenshots. You can also use a harness with browser
@@ -79,7 +79,7 @@ Then inspect the child outputs for access errors.
 If a harness cannot read the files, put them in an accessible location and run
 the task again. Do not treat that failure as a normal design review.
 
-## Ground Standards in Sources
+## Ground standards in sources
 
 Include primary sources when an audit depends on an external standard, registry
 convention, or product behavior. Require reviewers to separate facts from
@@ -99,7 +99,7 @@ The bundled `source-grounded-audit` skill supports this case. Install it in the
 harnesses that perform standards-sensitive audits. Then tell Ennodia to use the
 skill when the answer depends on external documentation.
 
-## Good Prompt Shape
+## Good prompt shape
 
 ```text
 Audit this landing page as a first-time visitor, not as a code consistency

package/docs/guides/troubleshooting.md

@@ -3,8 +3,6 @@ title: Troubleshooting
 description: Resolve failed starts without confusing configuration errors with model quality.
 ---
 
-# When an attempt cannot finish
-
 Start with the task’s failure reason and captured output.
 Use `ennodia_get_task` for details and `ennodia_list_harnesses` to inspect supported commands.
 

package/docs/guides/understand-results.md

@@ -3,8 +3,6 @@ title: Understand results
 description: Distinguish useful findings, disagreement, missing evidence, and failed execution.
 ---
 
-# Understand the result
-
 Process completion is one signal. A useful answer also needs evidence that fits your task.
 
 | Result | Meaning | Next step |

package/docs/index.md

@@ -3,8 +3,6 @@ title: What is Ennodia?
 description: Try other agents, models, and skills while staying in your familiar conversation.
 ---
 
-# Keep your agent. Get another way forward.
-
 Ennodia lets your primary artificial intelligence (AI) agent try another agent, model, or skill on a focused task.
 The findings return to your existing conversation.
 
@@ -17,7 +15,7 @@ Even an unsuccessful attempt can show which approach was tested under the record
 - [Get your first result](/docs/getting-started/).
 - [Choose a recipe](/docs/guides/recipes/).
 - [Understand the result](/docs/guides/understand-results/).
-- [Read a development case](/docs/evidence/building-ennodia/).
+- [Read a recorded run](/articles/can-gemini-hear-this-file/).
 
 ## Your existing tools
 
@@ -33,7 +31,7 @@ A native agent can also choose unrequested skills from its environment.
 - [Agent skills](/docs/guides/agent-skills/)
 - [Troubleshooting](/docs/guides/troubleshooting/)
 - [Data movement and history](/docs/concepts/data-governance/)
-- [Examples and evidence](/docs/evidence/)
+- [Evidence](/docs/evidence/)
 - [Roadmap](/docs/roadmap/)
 - [Technical reference](/docs/reference/mcp-tools/)
 

package/docs/install.md

@@ -1,5 +1,5 @@
 ---
-title: Installation for Agents
+title: Installation for agents
 description: A copy-paste installation page for agents that install Ennodia in Codex, Claude Code, OpenCode, Antigravity, and other Model Context Protocol (MCP) clients.
 ---
 
@@ -7,7 +7,7 @@ This page gives setup instructions to the user's agent.
 Install Ennodia as a local Model Context Protocol (MCP) server.
 Then connect it to the user's preferred compatible client.
 
-## Copy-Paste Prompt
+## Copy-Paste prompt
 
 ```text
 try-ennodia.cherninlab.com
@@ -16,7 +16,7 @@ try-ennodia.cherninlab.com
 The user can send this address in a new or existing agent conversation.
 The agent handles the setup steps below.
 
-## Check the Environment
+## Check the environment
 
 1. Identify the user's client and the machine where Ennodia will run.
 2. Check that the client can launch a local standard input/output (stdio) MCP server.
@@ -31,7 +31,7 @@ If the current client cannot launch a local MCP server, explain the missing capa
 Use a compatible local client for Ennodia.
 See [Supported Harnesses](/docs/reference/supported-harnesses/) for the worker agents Ennodia can call.
 
-## Install Command
+## Install command
 
 Use the npm package for normal MCP client installation:
 
@@ -42,7 +42,7 @@ npx -y ennodia
 Ennodia requires Bun `1.3.14` or newer. `npx` downloads Ennodia. Bun runs it.
 If the client supports Bun directly, use `bunx ennodia`.
 
-## MCP Configuration
+## MCP configuration
 
 Add this server to the user's MCP client configuration:
 
@@ -70,12 +70,14 @@ For a local Ennodia checkout, use:
 }
 ```
 
+Ennodia loads six core tools by default. For Plan Advisor, compositional slices, raw tasks, and skill installation, add `"--tools", "all"` to `args`. See [tool sets](/docs/reference/mcp-tools/#tool-sets).
+
 The configuration above shows the server command and arguments.
 Adapt its format to the client's documented configuration method.
 Reload the tools or restart the client only when its setup instructions require this step.
 Tell the user which step is needed before trying to call Ennodia.
 
-## Get One Useful Result
+## Get one useful result
 
 After the client exposes Ennodia's tools, start with one small task:
 
@@ -98,7 +100,7 @@ The first run does not require separate planning, budget estimation, or Compare
 These tools remain available for larger tasks.
 See [MCP Tools](/docs/reference/mcp-tools/) for exact parameters and identifiers (IDs).
 
-## Installed Components
+## Installed components
 
 Ennodia is a local MCP server. It lets the user's main agent request help from
 other installed agent CLI programs during the same task.
@@ -123,7 +125,7 @@ answer.
 Tell the user a real run can take minutes. Compare adds two serial model passes
 after the selected child agents finish.
 
-## Example Requests
+## Example requests
 
 Use Ennodia when the user permits more model work to get a better answer than
 one agent usually gives.
@@ -148,7 +150,7 @@ Compare the results before you recommend the final documentation edit.
 Compare is model-led. The user does not normally need to judge the parallel
 answers. The trace remains available for inspection.
 
-## Optional Next Steps
+## Optional next steps
 
 - Use [Budgets and Limits](/docs/guides/budgets-and-limits/) before costly
   parallel runs.

package/docs/questions.md

@@ -0,0 +1,56 @@
+---
+title: Questions
+description: Short answers about switching agents, setup, data, cost, time, and what Ennodia remembers.
+---
+
+## Do I need to switch agents?
+
+No. You keep the agent you use, in the app you like.
+Ennodia adds a few tools to it, and your agent calls another agent only when a task needs it.
+
+## Where does Ennodia run?
+
+On your computer. Your agent starts it as a local Model Context Protocol (MCP) server.
+It needs Bun 1.3.14 or newer.
+Your agent can [set it up for you](/docs/install/), or you can [add the server entry yourself](/docs/getting-started/#manual-setup).
+
+## Which agents can I use?
+
+Ennodia uses the agents on your computer, with the models and access you have set up.
+It supports Codex CLI, Claude Code, OpenCode, Antigravity, Kilo Code, Kiro, Cline, and Hermes Agent.
+[Check compatibility](/docs/reference/supported-harnesses/).
+
+## What does it cost?
+
+Ennodia is free and MIT licensed, with no account and no subscription of its own.
+Each agent you call runs through its own command-line tool, with the plan or API key you set up for it.
+
+## Will it use more tokens?
+
+It can. Each agent you call reads its own prompt, and Compare reads every answer.
+Ennodia's six core tools add about 2,600 tokens to each session.
+You can cap agent runs and estimated input tokens for every run. [Set limits](/docs/guides/budgets-and-limits/).
+
+## Is it slower?
+
+A handoff takes as long as the other agent's session.
+In the [audio pilot](https://github.com/cherninlab/ennodia/blob/main/bench/audio-routing/pilot-2026-09-26.md), Codex with Ennodia took a median of 57 seconds per clip, against 27 seconds alone.
+Alone, Codex answered without listening.
+
+## What data leaves my computer?
+
+Ennodia has no hosted service and sends nothing to its authors.
+The agents you call send prompts and files to their own model providers, as they do without Ennodia.
+[How data is handled](/docs/concepts/data-governance/).
+
+## Does my agent hand off work on its own?
+
+Only when you let it. Say it in your own words, like "get Codex's opinion".
+Or install the pragmatic skill, so your agent can hand off bounded work within the limits you set.
+[The delegation skill](/docs/guides/agent-skills/#main-agent-delegation-skill).
+
+## Does it remember what worked?
+
+It keeps a local run history, including outputs and failures, so you can look back.
+Learning which agent or skill to choose next is the [next step on the roadmap](/docs/roadmap/).
+[What the history records](/docs/guides/understand-results/).

package/docs/reference/controlled-english.md

@@ -3,15 +3,13 @@ title: Controlled English
 description: Ennodia terminology and writing rules for ASD-STE100 Issue 9.
 ---
 
-# Controlled English
-
 Ennodia documentation uses ASD-STE100 Issue 9 as its writing standard.
 This policy applies to the README, documentation, website text, and visible asset text.
 
 Commands, API fields, status values, model IDs, and quoted interface text are data.
 Keep this data exact, even when its text does not use controlled English.
 
-## Writing Rules
+## Writing rules
 
 - Use American English.
 - Use active voice when the agent is known.

package/docs/reference/ennodia-io.md

@@ -57,7 +57,7 @@ Environment variables:
 | `ENNODIA_IO_MAX_REQUEST_BODY_SIZE` | Default request body byte cap. |
 | `ENNODIA_IO_MAX_CONCURRENT_CHAT_COMPLETIONS` | Default in-flight chat completion cap. |
 
-## Security and Browser Access
+## Security and browser access
 
 IO binds to loopback by default and refuses non-loopback hosts unless an API key
 is configured. Bearer tokens are compared with a timing-safe comparison.
@@ -94,7 +94,7 @@ boundary.
 | `GET /v1/models` | Supported | Returns local virtual model IDs for compatible clients. |
 | `POST /v1/chat/completions` | Supported subset | Non-streaming text messages only. Requires a JSON media type. |
 
-## Provider Options
+## Provider options
 
 Use provider options when building a settings screen:
 
@@ -135,7 +135,7 @@ Option statuses:
 
 Add `?includeUnavailable=false` to return only ready options.
 
-## Virtual Models
+## Virtual models
 
 `GET /v1/models` returns local virtual models for OpenAI-compatible clients:
 
@@ -148,7 +148,7 @@ Add `?includeUnavailable=false` to return only ready options.
 Older aliases `ennodia-auto`, `ennodia/auto`, and `ennodia/compare` are accepted
 for compatibility. Prefer `local/*` IDs in new app integrations.
 
-## Chat Completions
+## Chat completions
 
 Minimal request:
 
@@ -234,7 +234,7 @@ HTTP error response:
 - timeout, disappeared run, or start failure -> `502 ennodia_run_error`
 - failed run or run with `cancelled` status -> `502 ennodia_run_failed` plus run metadata
 
-## Library Use
+## Library use
 
 Apps can import the same primitives without running the HTTP server:
 
@@ -249,7 +249,7 @@ const providerOptions = await listAppProviderOptions(core);
 The app stays in control of its settings UI, labels, persistence, and consent
 flow. Ennodia supplies local discovery and execution primitives.
 
-## Smoke Test
+## Smoke test
 
 From a checkout:
 
@@ -260,7 +260,7 @@ bun run io:smoke
 The smoke test starts a local IO server and checks `/health`,
 `/v1/provider-options`, and `/v1/models` without launching child agents.
 
-## Not Implemented
+## Not implemented
 
 IO deliberately rejects or omits: