ennodia 0.2.0 → 0.3.0-rc.2

package/README.md

@@ -1,156 +1,112 @@
-<div align="center">
-
-<a href="https://ennodia.cherninlab.com">
-<picture> 
-  <source media="(prefers-color-scheme: dark)" srcset="https://github.com/cherninlab/ennodia/raw/main/docs/assets/logo-dark.svg">
-  <source media="(prefers-color-scheme: light)" srcset="https://github.com/cherninlab/ennodia/raw/main/docs/assets/logo.svg">
-  <img alt="Ennodia" src="https://github.com/cherninlab/ennodia/raw/main/docs/assets/logo.svg" width="235" height="50">
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
+  <img alt="Ennodia" src="docs/assets/logo.svg" width="235" height="50">
 </picture>
-</a>
 
-<p><strong>Model Context Protocol (MCP) server for multi-agent review with Compare and traceable receipts</strong></p>
+**Keep your agent. Get another way forward.**
 
-<p>
-  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-informational"></a>
-  <img alt="Continuous integration" src="https://github.com/cherninlab/ennodia/actions/workflows/ci.yml/badge.svg" />
-  <a href="https://smithery.ai/servers/cherninlab/ennodia"><img alt="Smithery: Ennodia" src="https://img.shields.io/badge/Smithery-Ennodia-FF5601"></a>
-</p>
+When a task stalls, Ennodia lets your primary artificial intelligence (AI) agent try another agent, model, or skill.
+The findings come back to the same conversation.
+You keep your familiar interface and decide what to try next.
 
-<p align="center">
-  <img alt="Ennodia terminal with three completed artificial intelligence reviews" src="https://github.com/cherninlab/ennodia/raw/main/docs/assets/terminal.png" width="600">
-</p>
+```text
+Use Ennodia MCP to get a second opinion on this bug.
+Give one available agent the failing test and our attempted fixes.
+Request a different explanation and a way to test it.
+Bring the findings back here.
+```
 
-</div>
+## When it helps
 
-Ennodia gives your primary agent access to installed agent command-line
-interfaces (CLIs). It tracks each child task and uses model-led Compare to show
-agreements, disagreements, omissions, and one recommended answer with receipts.
+- A task is stuck and you want to check another approach.
+- A skill looks useful, but you want to try it in a separate task first.
+- Two answers disagree and you need to identify the next check.
+- An unsuccessful attempt can help you avoid repeating the same approach under the same conditions.
 
-Before work, an optional Plan Advisor can propose a bounded set of harnesses,
-models, and skills. It does not start the proposed work.
+Your main agent checks the findings and integrates useful work.
+Additional attempts consume time and resources. General time or token savings have not been established.
 
 ## Install
 
-Send this address to your primary agent. The agent can then complete the
-installation:
+Send this address to your primary agent:
 
 ```text
 try-ennodia.cherninlab.com
 ```
-To run Ennodia directly as a standard input/output (stdio) MCP server, use:
 
-```sh
-npx -y ennodia
+For manual setup, add this Model Context Protocol (MCP) server to your client:
+
+```json
+{
+  "mcpServers": {
+    "ennodia": {
+      "command": "npx",
+      "args": ["-y", "ennodia"]
+    }
+  }
+}
 ```
-To use Bun directly, run `bunx ennodia`.
 
-For a registry or client installer, use the
-[Ennodia Smithery page](https://smithery.ai/servers/cherninlab/ennodia).
+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`.
 
-For manual installation or local development, see
-[Quickstart](https://ennodia.cherninlab.com/docs/getting-started/).
+[Get your first result](https://ennodia.cherninlab.com/docs/getting-started/) ·
+[Installation for agents](https://ennodia.cherninlab.com/docs/install/)
 
-## What Ennodia does
+## Use your installed agents and skills
 
-- Discovers available local artificial intelligence (AI) tools
-- Plans a route with a caller-provided category or keyword fallback
-- Estimates preflight input tokens and enforces local caps on that estimate
-- Starts and monitors child tasks
-- Shows status, elapsed time, logs, and failures
-- Cancels tasks and runs explicitly
-- Lets a Plan Advisor propose an inert, validated work plan
-- Compares multiple completed outputs with a Judge
-- Lets a Result Advisor combine the Judge findings into one answer
+Supported agents: Codex CLI, Claude Code, OpenCode, Kilo Code, Kiro CLI, Cline, Hermes Agent, and Antigravity.
+Model availability and tool permissions depend on the installed agent and its provider configuration.
+Discovery finds executable commands. It does not verify authentication or model access.
+Codex workers use a read-only sandbox by default.
 
-`ennodia_run` is the main entrypoint. It plans and starts tasks. It can also use
-Compare. It returns a run identifier (ID) for use with `ennodia_get_run`.
+Ennodia discovers native Agent Skills and can request them for specific tasks.
+A separate task keeps the trial outside the main conversation.
+Native agents can also select unrequested skills from their own environment.
 
-See [MCP tools](https://ennodia.cherninlab.com/docs/reference/mcp-tools/) for
-the full tool and parameter reference.
+[Recipes](https://ennodia.cherninlab.com/docs/guides/recipes/) ·
+[Using skills](https://ennodia.cherninlab.com/docs/guides/agent-skills/) ·
+[Understand results](https://ennodia.cherninlab.com/docs/guides/understand-results/)
 
-Use Ennodia for work that needs additional model analysis. A run usually takes
-minutes. Compare adds two serial model passes after the child agents finish.
+## See it in practice
 
-## Judge, Plan Advisor, and Result Advisor
+- [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.
 
-Each role has limited responsibilities:
+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/)
 
-- **Plan Advisor** runs before work when requested. It proposes explicit
-  harness, model, and skill assignments as inert data. Ennodia validates the
-  proposal against a frozen inventory. Plan Advisor cannot execute it. The
-  caller must use a separate call to start the validated plan once.
-- **Judge** runs during Compare and maps agreements, contradictions, unique
-  evidence, omissions, and risks across completed outputs.
-- **Result Advisor** follows the Judge. It uses the Judge findings and original
-  outputs to recommend an answer. If Judge analysis is not usable, it uses
-  `basis: "candidates-only"`. This status makes the degradation visible.
+## Data and limits
 
-## Ennodia IO
-
-The separate `@cherninlab/ennodia-io` package provides a local Hypertext
-Transfer Protocol (HTTP) and TypeScript interface. Apps can use it with
-user-supplied keys and installed local agents:
-
-```sh
-npx -y @cherninlab/ennodia-io
-```
+Ennodia runs locally without an Ennodia-hosted service.
+Selected agents can send material to their configured model providers.
+Terminal run history is stored locally and can be disabled with `ENNODIA_HISTORY=0`.
 
-See [Ennodia IO](https://ennodia.cherninlab.com/docs/reference/ennodia-io/) for
-supported fields, authentication behavior, cross-origin resource sharing
-rules, and current limits.
+Ennodia can limit child tasks and estimated input tokens.
+Those estimates exclude internal harness work and are not provider bills.
+Automatic agent updates and recommendations learned from past results remain future work.
 
-## Supported harnesses
+[Data governance](https://ennodia.cherninlab.com/docs/concepts/data-governance/) ·
+[Budgets](https://ennodia.cherninlab.com/docs/guides/budgets-and-limits/) ·
+[Roadmap](https://ennodia.cherninlab.com/docs/roadmap/)
 
-- Codex CLI
-- Claude Code
-- OpenCode
-- Kilo Code
-- Kiro CLI
-- Cline CLI
-- Hermes Agent
-- Antigravity
+## Technical reference and contribution
 
-Adapters stay thin. Core modules contain shared routing, trace data, task state,
-recovery, and Compare logic.
+The main entrypoint is `ennodia_run`. The optional Plan Advisor proposes explicit tasks before execution.
+Compare examines completed answers and returns advice with its evidence and limitations.
 
-Evaluated candidates include Gemini CLI, GitHub Copilot CLI, Amp, Aider, Goose,
-Qwen Code, and Cursor CLI. Ennodia does not include these candidates.
-
-Ennodia can add a candidate after verification of a supported prompt-in and
-text-out interface. Verification must not use permission-bypass flags or
-provider-private APIs.
-
-## Documentation
-
-- [Installation for Agents](https://ennodia.cherninlab.com/docs/install/): agent-controlled installation
-- [Quickstart](https://ennodia.cherninlab.com/docs/getting-started/): manual installation and local development
-- [MCP Tools](https://ennodia.cherninlab.com/docs/reference/mcp-tools/): full tool parameter reference
-- [How Ennodia Works](https://ennodia.cherninlab.com/docs/concepts/how-ennodia-works/): orchestration pipeline
-- [Second Opinions](https://ennodia.cherninlab.com/docs/concepts/second-opinions/): replicate, decompose, and red-team patterns
-- [Data Governance](https://ennodia.cherninlab.com/docs/concepts/data-governance/): local storage and data movement boundaries
-- [Controlled English](https://ennodia.cherninlab.com/docs/reference/controlled-english/): ASD-STE100 rules and Ennodia technical terms
-- [Comparisons](https://ennodia.cherninlab.com/docs/comparisons/): comparisons with adjacent tools
-- [Benchmarks](https://ennodia.cherninlab.com/docs/reference/benchmarks/): deterministic bug-recall results
-- [Better Audits](https://ennodia.cherninlab.com/docs/guides/running-better-audits/): prompt rubrics for Compare
-
-## Benchmarks
-
-The current benchmark is `multi-model-bug-recall`. It uses small TypeScript
-review fixtures and committed bug oracles. Run the deterministic suite with:
+[MCP tools](https://ennodia.cherninlab.com/docs/reference/mcp-tools/) ·
+[Experimental Ennodia IO](https://ennodia.cherninlab.com/docs/reference/ennodia-io/) ·
+[Contributing](CONTRIBUTING.md) · [MIT license](LICENSE)
 
 ```sh
-bun run bench:bug-recall
+bun install
+bun run verify
 ```
 
-Live harness runs are available through `bun run bench:bug-recall:live` and are
-kept out of `bun run verify`.
-
-The current dated fixture snapshot is published in
-[Benchmarks](https://ennodia.cherninlab.com/docs/reference/benchmarks/): 4
-cases, with `ennodia-parallel-compare` at 100% recall and 100% precision.
-
-## Contribute
+### Experimental Pragmatic mode
 
-Ennodia is under active development. You can submit bug reports and small,
-focused pull requests. See [CONTRIBUTING.md](CONTRIBUTING.md) for the local
-verification workflow.
+In `ennodia@next`, delegate bounded investigation or patch proposals to an explicitly selected model.
+[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/evidence/building-ennodia.md

@@ -0,0 +1,66 @@
+---
+title: Building Ennodia with Ennodia
+description: A real development case with a failed launch, a useful worker patch, and primary-agent review.
+---
+
+# Building Ennodia with Ennodia
+
+Development record: September 6, 2026. These changes belong to the next release candidate.
+
+A local server could accept browser requests that started agent work without an intended origin check.
+The primary agent had a reproduced defect and a focused implementation task.
+It stayed in Codex and used Ennodia to dispatch the work.
+
+## What happened
+
+| Attempt | Observed result | Next action |
+| --- | --- | --- |
+| Claude Code with Sonnet | Authentication failed before the task ran. | Use another configured agent. |
+| OpenCode with its configured model | Reproduced the problem, edited four files, and added seven regression tests. | Review the patch in the primary conversation. |
+| Primary agent | Tightened malformed Host and Origin validation and preserved the native request size limit. | Run the combined verification suite. |
+
+The worker tested both the request handler and a real listening server.
+It also found that Bun can return an empty oversized-request error before the handler runs.
+Its proposed size-limit adjustment could not guarantee a structured response for every oversized request.
+The primary agent kept the hard limit and documented the actual behavior.
+
+The combined suite passed after integration.
+This demonstrates a useful contribution that still needed review and adaptation.
+It does not establish how long the primary agent alone would have taken.
+
+## What did not help
+
+A separate Compare review used a smaller GPT model with the rigorous-review skill.
+It reached the ten-minute task limit without returning a usable proposal.
+The primary agent completed those fixes locally.
+The record includes that failed attempt, rather than treating every delegation as a success.
+
+The Claude failure indicates an expired login, not model quality.
+The GPT attempt does not establish that the model or skill is generally unsuitable.
+Its observed result applies to this task, configuration, and time limit.
+
+A later broad documentation assignment through OpenCode also reached its ten-minute limit without producing edits.
+The primary agent completed those pages directly.
+This suggests testing smaller assignments and clearer execution controls. It does not establish a general provider limitation.
+
+## Inspect and reproduce
+
+The implementation and regressions are in the open repository:
+
+- [HTTP implementation](https://github.com/cherninlab/ennodia/blob/main/packages/ennodia-io/src/io.ts)
+- [HTTP regressions](https://github.com/cherninlab/ennodia/blob/main/packages/ennodia-io/src/io.test.ts)
+
+Use the release candidate checkout that contains this page.
+
+```sh
+bun install
+bun test packages/ennodia-io/src/io.test.ts
+bun run verify
+```
+
+The tests use local fixtures. They do not call model providers.
+A live repeat requires an authenticated supported agent.
+Save the worker output and the primary agent’s final diff when repeating the experiment.
+
+The practical benefit here was a reviewed contribution from another tool without moving the primary conversation.
+No token-saving or speed comparison was measured.

package/docs/evidence/docs-drift.md

@@ -0,0 +1,73 @@
+---
+title: Find stale documentation
+description: Review current documentation without deleting useful historical records.
+---
+
+# Find stale documentation
+
+A current guide can disagree with code while a historical document remains correct for its period.
+This exercise gives an additional agent a bounded review task.
+
+The fixture lives in `examples/docs-drift` in the Ennodia checkout.
+It contains deliberate documentation errors and a labeled migration record.
+
+## Try it
+
+The recording below shows an actual MCP run from the release candidate checkout.
+The final frame includes ten extra seconds for reading.
+
+<video controls preload="metadata" aria-label="Recorded Ennodia documentation review" style="width:100%; height:auto;" src="/demos/docs-drift.mp4"></video>
+
+The [terminal recording](/demos/docs-drift.cast) preserves the captured output and timing.
+The text below provides the same findings without video.
+
+1. Use a local checkout of Ennodia.
+2. Run the fixture’s behavior check.
+
+```sh
+bun examples/docs-drift/check.ts
+```
+
+3. Give this request to your primary agent.
+
+```text
+Use Ennodia MCP to review examples/docs-drift in a separate read-only task.
+Compare the current README with config.ts. Identify each conflicting claim.
+Distinguish current instructions from the labeled historical migration record.
+Return proposed corrections with file references. Bring the findings back here.
+```
+
+4. Review each proposed correction against the source.
+5. Update the current guide in your copy.
+6. Keep the historical migration record labeled as history.
+
+## Check the result
+
+The current implementation uses port `4545`, the variable `APP_PORT`, and the response `{ "ready": true }`.
+The README contains three conflicting current claims.
+The migration record describes the previous release and does not need the same changes.
+
+A useful review finds the three conflicts and preserves the historical distinction.
+A model can still miss a conflict or recommend deleting useful history.
+This exercise has known answers. It is not a general benchmark.
+
+## Recorded development trial
+
+On September 6, 2026, an Antigravity task through Ennodia found all three current documentation conflicts.
+It also identified the archive as a historical record that did not need changes.
+The primary agent checked each finding against the fixture source.
+This is one successful trial on a small known-answer example, not a general performance result.
+
+The fixture includes `recorded-run.json` with the answer, task IDs, timing, and verification notes.
+Local file URL prefixes were normalized for sharing.
+
+The video records a later successful repetition through the candidate's MCP server.
+It uses the configured default Antigravity model, with no model override.
+The opt-in script starts one real agent using your configured provider access:
+
+```sh
+bun examples/docs-drift/demo.ts --live antigravity
+```
+
+Replace `antigravity` with another installed, authenticated harness ID when needed.
+The recording uses the [asciicast format](https://docs.asciinema.org/manual/asciicast/v2/).

package/docs/evidence/index.md

@@ -0,0 +1,18 @@
+---
+title: Examples and evidence
+description: Try small examples and inspect what Ennodia contributed to its own development.
+---
+
+# Examples and evidence
+
+Ennodia helps your primary agent try another approach and bring the findings back.
+These examples show the workflow and its limits.
+
+- [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.

package/docs/evidence/measurement.md

@@ -0,0 +1,40 @@
+---
+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.
+A separate control can give the main agent the same additional models without Ennodia.
+That control helps distinguish orchestration benefits from additional computation.
+
+## Pilot design
+
+- Select 20 tasks before running the experiment.
+- Repeat each condition three times.
+- Fix models, versions, source material, available skills, and resource limits.
+- Define correctness checks before collecting answers.
+- Keep evaluator answers outside agent materials.
+- Retain failed, canceled, and incomplete attempts.
+
+| Measure | Definition |
+| --- | --- |
+| Correctness | Fraction of tasks meeting the predefined checks. |
+| Time | Elapsed time through planning, workers, comparison, verification, and integration. |
+| Resources | Reported input, output, and cached tokens across all participants. Unknown usage stays unknown. |
+| Human work | Interventions, manual transfers, and repeated setup steps. |
+| Repeated attempts | Reuse of a previously unsuccessful approach under the same recorded conditions. |
+
+Compare time together with correctness. Excluding failures from timing can hide a worse completion rate.
+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.
+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/evidence/skill-trial.md

@@ -0,0 +1,68 @@
+---
+title: Try a skill separately
+description: Compare two reviews of one function while keeping the main conversation focused.
+---
+
+# Try a skill separately
+
+A skill can improve a review, add irrelevant work, or make no difference.
+A small separate task gives you evidence before you use its recommendations.
+
+The fixture lives in `examples/skill-trial` in the Ennodia checkout.
+It contains a short function and a local contract with deliberate mismatches.
+
+## Prepare two comparable attempts
+
+1. Select one available agent and model.
+2. Check that the requested skill is installed for that agent.
+3. Give both attempts the same `retry.ts` and `contract.md` files.
+4. Keep the evaluator `check.ts` out of the review materials.
+5. Run the plain review and skill review as separate read-only tasks.
+
+```text
+Use Ennodia MCP for two separate read-only reviews of examples/skill-trial/retry.ts.
+Provide contract.md as the source of truth. Use the same agent and model.
+First run: request no additional skill.
+Second run: request the installed source-grounded-audit skill.
+Do not open check.ts until both reviews finish.
+Return each contract mismatch with a concrete failing input.
+Compare useful findings, unsupported claims, and time spent.
+```
+
+Your agent can use `ennodia_start_compositional` with one slice per attempt.
+Set `skillIds: []` on the plain slice and `skillIds: ["source-grounded-audit"]` on the skill slice.
+The [skill guide](/docs/guides/agent-skills/) describes installation and explicit selection.
+
+A native agent can self-select other available skills.
+An empty requested skill list does not guarantee a skill-free control.
+For strict measurement, use separate controlled skill inventories and record the skills actually loaded.
+
+## Validate the findings
+
+Run the evaluator after saving both reviews:
+
+```sh
+bun examples/skill-trial/check.ts
+```
+
+The supplied implementation deliberately fails some cases.
+Use each reported input to check a proposed fix in a disposable copy.
+A useful finding needs to explain a contract mismatch, not just suggest a stylistic change.
+Keep useful partial findings even if the skill adds other irrelevant advice.
+
+This fixture supports a repeatable workflow demonstration.
+No quality improvement is claimed for it.
+
+## Recorded development trial
+
+On September 6, 2026, two Antigravity tasks ran through Ennodia in separate temporary copies.
+The plain review found the six failing evaluator cases and an additional alternative-number-notation case.
+The requested-skill attempt produced no answer because native tool permissions blocked a required read.
+
+The agent command exited with code zero despite the permission denial.
+Ennodia initially labeled that task successful. This trial exposed a classification defect that the next release candidate fixes.
+The denied attempt cannot establish the quality of the skill.
+No permission bypass was used to force a successful result.
+
+The fixture includes `recorded-trial.json` with both observed outcomes and the diagnostic excerpt.
+Local paths were normalized, and CLI remediation instructions were omitted from the excerpt.

package/docs/getting-started.md

@@ -1,22 +1,36 @@
 ---
 title: Quickstart
-description: Install Ennodia manually, perform the first checks, and find the next documentation page.
+description: Give your agent the Ennodia setup link, get your first useful result, or follow the manual installation instructions.
 ---
 
-This page gives manual installation instructions for a Model Context Protocol
-(MCP) client. To use an agent for installation and configuration, see
-[Installation for Agents](/docs/install/).
+Paste this address into a new or existing conversation with your agent:
 
-## Requirements
+```text
+try-ennodia.cherninlab.com
+```
+
+Your agent can follow the setup instructions, check the requirements, and connect Ennodia to your client.
+Continue in your preferred compatible chat app, command-line interface (CLI), or editor.
+Ennodia connects through Model Context Protocol (MCP).
+
+The [installation instructions for agents](/docs/install/) explain the setup steps.
+Your agent will identify any client restart or reload needed to make the new tools available.
+
+After setup, [try your first useful result](#your-first-useful-result).
+For manual setup, follow the instructions below.
+
+## Manual Setup
+
+### Requirements
 
 - Bun `1.3.14` or newer
 - An MCP client that can launch a standard input/output (stdio) server
-- At least one supported artificial intelligence (AI) command-line tool for
-  real agent execution
+- At least one supported artificial intelligence (AI) command-line tool with
+  working provider access
 
 See [Supported Harnesses](/docs/reference/supported-harnesses/).
 
-## Install from npm
+### Install from npm
 
 Install the stable release from npm:
 
@@ -30,7 +44,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:
 
@@ -41,7 +55,7 @@ bun install
 bun run verify
 ```
 
-## MCP Client Config
+### MCP Client Config
 
 ```json
 {
@@ -69,28 +83,37 @@ For a local checkout, use the source file:
 
 Replace `/absolute/path/to/ennodia` with your local repository path.
 
-## First Checks
+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.
 
-From the repository:
+## Your first useful result
 
-```bash
-bun install
-bun run mcp:smoke
-bun run verify
+After installation, give your primary agent a small request:
+
+```text
+Use Ennodia MCP to get one additional opinion on this function.
+Choose an available agent. Keep the review read-only.
+Return one concrete issue or explain that no issue was established.
+Bring the findings back to this conversation.
 ```
 
-From an MCP client, call `ennodia_list_harnesses`. Then call
-`ennodia_estimate_budget`. To inspect the route, call `ennodia_plan`.
+Start with one worker and a small set of files.
+Discovery checks installed commands, not authentication, model access, or provider quota.
+A live task establishes which configuration works in your environment.
+
+Your agent can call `ennodia_list_harnesses`, then `ennodia_run` with a selected `harnessId`, `mode: "single"`, and `compare: false`.
+Poll `ennodia_get_run` with the returned run identifier (ID).
+Stop when the status is `succeeded`, `failed`, or `cancelled`.
 
-Start the work with `ennodia_run`. This tool plans the route and starts the
-selected tasks. It can also compare successful outputs. It returns a run
-identifier (ID).
+Inspect the result before starting more work.
+Use the [recipes](/docs/guides/recipes/) for a stuck task, a skill trial, or conflicting answers.
+See [Understand Results](/docs/guides/understand-results/) when the attempt is incomplete or unhelpful.
 
-Poll `ennodia_get_run` with that ID. Stop when the status is `succeeded`,
-`failed`, or `cancelled`.
+Expect live runs to take time. A timeout budget is not a completion prediction.
+Compare adds a Judge pass and a Result Advisor pass after child agents finish.
 
-Expect real runs to take minutes. 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.
 
 ## Optional Team Advice