ennodia 0.1.1 → 0.3.0-rc.2

package/CONTRIBUTING.md

@@ -6,7 +6,7 @@ review.
 ## Prerequisites
 
 - Bun `1.3.14` or newer
-- Local AI tools only when you are changing or testing their adapters
+- Local artificial intelligence (AI) tools only when you change or test their adapters
 
 ## Local workflow
 
@@ -21,8 +21,9 @@ bun run verify
 - Oxlint
 - Bun tests
 - website build
+- controlled-English deterministic checks
 - task smoke test
-- MCP smoke test
+- Model Context Protocol (MCP) smoke test
 
 Before changing release metadata, package contents, or registry config, also run:
 
@@ -35,7 +36,8 @@ bun run release:check
 - Keep adapters thin. Put shared routing, tracing, task lifecycle, recovery, and
   Compare behavior in core modules.
 - Do not add permission-bypass flags to harness commands by default.
-- Do not call provider-private APIs. Use supported CLI or API surfaces.
+- Do not call provider-private application programming interfaces (APIs).
+  Use supported command-line interface (CLI) or API surfaces.
 - Keep progress and status output compact and factual.
 - Keep docs, website copy, package metadata, and MCP behavior aligned in the
   same change when public behavior changes.
@@ -46,10 +48,11 @@ bun run release:check
 
 `bin/ennodia` is the executable used by npm, `bunx`, and `npx`.
 `src/cli.ts` starts the stdio MCP server only.
-`src/index.ts` is the side-effect-free TypeScript export surface for JSR and
-imports.
-`packages/ennodia-io` is the experimental local HTTP package. It owns the
-`ennodia-io` binary and imports Core from the `ennodia` package surface; the
+`src/index.ts` is the side-effect-free TypeScript export surface for the
+JavaScript Registry (JSR) and imports.
+`packages/ennodia-io` is the experimental local Hypertext Transfer Protocol
+(HTTP) package. It owns the
+`ennodia-io` binary and imports Core from the `ennodia` package surface. The
 root package must not ship the HTTP server.
 
 ## Releasing
@@ -57,13 +60,16 @@ root package must not ship the HTTP server.
 Releases are cut by a maintainer, not part of a normal contribution. This
 section exists so the process is written down.
 
-**Versioning.** Prerelease versions use SemVer suffixes such as `0.1.0-rc.1`;
+**Versioning.** Prerelease versions use SemVer suffixes such as `0.1.0-rc.1`.
 stable versions omit the suffix, such as `0.1.0`. The source of truth is the
-root `package.json` version; `bun run version:sync` derives `jsr.json`,
-`src/version.ts`, and the IO package version/peer dependency from it. `bun test`
-verifies they match.
+root `package.json` version.
 
-**Dist-tags.** Tags containing a hyphen publish to npm's `next` dist-tag;
+`bun run version:sync` derives `jsr.json`,
+`src/version.ts`, `server.json`, `manifest.json`, and the IO package version.
+It also derives the IO dependency on the core version. `bun test` verifies
+that the versions match.
+
+**Dist-tags.** Tags containing a hyphen publish to npm's `next` dist-tag.
 tags without a hyphen publish to `latest`:
 
 ```bash
@@ -73,7 +79,7 @@ git tag v0.1.0 && git push origin v0.1.0             # publishes to latest
 
 Since `v0.1.0`, docs recommend the unqualified `ennodia` install, which npm
 resolves to the `latest` dist-tag. Prerelease work between stable releases
-still publishes to `next`; recommend `ennodia@next` in docs only while a fix
+still publishes to `next`. Recommend `ennodia@next` in docs only while a fix
 exists solely on that channel.
 
 **Release checklist.**
@@ -89,44 +95,62 @@ exists solely on that channel.
 3. Commit the version change.
 4. Push a matching tag, for example `v0.1.0-rc.1`.
 5. The `Release` GitHub Actions workflow publishes the core `ennodia` package
-   to npm and JSR, plus the GitHub release asset. Until the workflow is updated
-   to publish both packages, `@cherninlab/ennodia-io` is published manually by a
-   maintainer after the core package version it peers against is available.
-
-**Package contents.** The core npm package must include `bin/ennodia`, the source
-files the Bun runtime needs, README/LICENSE/CONTRIBUTING/docs, and benchmark
-fixtures — and must not include `.github/`, `AGENTS.md`, `CLAUDE.md`,
-`bun.lock`, `src/dev/`, `src/io.ts`, `*.test.ts`, `packages/`, or `website/`.
+   to npm and JSR, then `@cherninlab/ennodia-io` to npm, the MCP Registry
+   listing, and the GitHub release asset. Re-running a release is safe when a
+   prior attempt published one of these immutable versions.
+
+**Package contents.** The core npm package must include these items:
+
+- `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/`
+
 JSR publishes the TypeScript source and docs, but not benchmark fixtures.
 The IO npm package must include `bin/ennodia-io`, its `src/` files, and its
-README, and keeps `ennodia` as a peer dependency. `bun run release:check`
-enforces these lists.
+README. It has an exact runtime dependency on the matching `ennodia` version.
+The release workflow publishes the core package first. The IO package stays
+outside the root Bun workspace so an unpublished next version does not block
+the root install. `bun run release:check` enforces these rules.
 
-**Registry publishing.** Both npm and JSR publish from GitHub Actions using
-OIDC — there is no long-lived `NPM_TOKEN`. To reconfigure a trusted
-publisher: npm needs provider "GitHub Actions", org/user `cherninlab`,
-repository `ennodia`, workflow filename `release.yml`, allowed action
-`npm publish`; JSR needs scope `@cherninlab`, package `ennodia`, linked
-repository `cherninlab/ennodia`.
+**Registry publishing.** npm publishes use the repository `NPM_TOKEN` secret.
+The workflow passes it to npm as `NODE_AUTH_TOKEN`. JSR uses GitHub Actions
+OpenID Connect (OIDC) without a JSR token.
+
+Link scope `@cherninlab`, package `ennodia`, to
+`cherninlab/ennodia` in JSR package settings. The workflow's `id-token: write`
+permission enables that authentication. To reconfigure npm, ensure the token
+can publish both `ennodia` and `@cherninlab/ennodia-io` with public access.
 
 **MCP registry listing.** The official MCP Registry
-(`registry.modelcontextprotocol.io`) hosts metadata only; npm remains the
+(`registry.modelcontextprotocol.io`) hosts metadata only. npm remains the
 artifact source. The listing is defined by `server.json` at the repo root,
 and npm-side ownership is verified through the `mcpName` field in
-`package.json` (`io.github.cherninlab/ennodia`) — the two names must match.
+`package.json`. Its value must match `io.github.cherninlab/ennodia` in
+`server.json`.
 To publish or update the listing after the npm package is live:
 
 ```sh
 brew install mcp-publisher        # or download from the registry's releases
-mcp-publisher login github        # device-code flow; grants io.github.cherninlab/*
+mcp-publisher login github        # interactive local login; grants io.github.cherninlab/*
 mcp-publisher publish             # validates and submits server.json
 ```
 
-Keep the `version` fields in `server.json` in step with releases; the
-listing is per-version, so re-run `mcp-publisher publish` after each stable
-release. Community aggregators (Glama, PulseMCP, mcp.so, Smithery) index
+The release workflow uses the non-interactive GitHub Actions OIDC equivalent:
+`mcp-publisher login github-oidc --registry=https://registry.modelcontextprotocol.io`.
+This also requires the workflow's `id-token: write` permission.
+
+Keep the `version` fields in `server.json` in step with releases. The
+listing is per-version, so re-run `mcp-publisher publish` after each release.
+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.
+submissions. They do not need per-release updates.
 
 ## Benchmarks
 

package/README.md

@@ -1,140 +1,112 @@
-<div align="center">
-
-<a href="https://ennodia.cherninlab.com">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
-  <source media="(prefers-color-scheme: light)" srcset="docs/assets/logo.svg">
   <img alt="Ennodia" src="docs/assets/logo.svg" width="235" height="50">
 </picture>
-</a>
 
-<p><strong>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="CI" 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 comparing three completed AI reviews" src="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
 
-No single model or agent should be the only reviewer for work that matters.
-Ennodia lets your primary agent ask the installed agent CLIs you already have,
-track every child task, and use model-led Compare to surface agreements,
-disagreements, blind spots, and one synthesized 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.
 
-The subscription-pool idea is secondary: if you already pay for Codex, Claude
-Code, Antigravity, OpenCode, and other local agent tools, Ennodia gives your
-main agent one MCP doorway to use them as an independent review panel. The
-experimental IO package exposes a small local HTTP subset for apps, but the
-supported first-class surface is MCP.
+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 to your primary agent and let it handle setup:
+Send this address to your primary agent:
 
 ```text
 try-ennodia.cherninlab.com
 ```
-Or run it directly as a stdio MCP server from npm:
 
-```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"]
+    }
+  }
+}
 ```
 
-Prefer a registry or client installer? Use the
-[Ennodia Smithery listing](https://smithery.ai/servers/cherninlab/ennodia).
-It uses the same stdio command from `smithery.yaml` (`npx -y ennodia`) and
-does not need Ennodia-specific configuration.
-
-Requires Bun `1.3.14` or newer — `npx` downloads Ennodia, Bun runs it. Prefer
-Bun directly? Use `bunx ennodia`. For manual setup, local development,
-or a full walkthrough, see
-[Quickstart](https://ennodia.cherninlab.com/docs/getting-started/).
+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`.
 
-## What Ennodia does
+[Get your first result](https://ennodia.cherninlab.com/docs/getting-started/) ·
+[Installation for agents](https://ennodia.cherninlab.com/docs/install/)
 
-- Discovers available local 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, timing, logs, and failures
-- Cancels tasks and runs explicitly
-- Compares multiple completed outputs
-- Synthesizes one answer from the comparison
+## Use your installed agents and skills
 
-The main entrypoint is `ennodia_run`: it plans, executes, optionally
-compares, and returns a run ID to poll with `ennodia_get_run`. See
-[MCP tools](https://ennodia.cherninlab.com/docs/reference/mcp-tools/) for the
-full tool and parameter reference.
+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 is for deliberation-class work: a run usually takes minutes, and Compare
-adds two serial model passes after the child agents finish.
+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.
 
-## Ennodia IO
+[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/)
 
-The separate `@cherninlab/ennodia-io` workspace package exposes a local HTTP and TypeScript interface for apps that want BYOK-style settings over installed local agents:
+## See it in practice
 
-```sh
-npx -y @cherninlab/ennodia-io
-```
-
-See [Ennodia IO](https://ennodia.cherninlab.com/docs/reference/ennodia-io/) for
-supported fields, auth behavior, CORS posture, and current limits.
+- [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.
 
-## Supported harnesses
+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/)
 
-- Codex CLI
-- Claude Code
-- OpenCode
-- Kilo Code
-- Kiro CLI
-- Cline CLI
-- Hermes Agent
-- Antigravity
+## Data and limits
 
-Adapters stay thin — shared routing, tracing, task state, recovery, and
-Compare logic live in core modules.
+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`.
 
-Evaluated-but-not-shipped candidates include Gemini CLI, GitHub Copilot CLI,
-Amp, Aider, Goose, Qwen Code, and Cursor CLI. They will be added only when a
-supported non-interactive prompt-in/text-out surface can be verified without
-permission-bypass flags or provider-private APIs.
+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.
 
-## Documentation
+[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/)
 
-- [Installation for Agents](https://ennodia.cherninlab.com/docs/install/) — the agent-driven setup path
-- [Quickstart](https://ennodia.cherninlab.com/docs/getting-started/) — manual setup 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/) — the 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
-- [Comparisons](https://ennodia.cherninlab.com/docs/comparisons/) — how Ennodia compares to adjacent tools
-- [Benchmarks](https://ennodia.cherninlab.com/docs/reference/benchmarks/) — deterministic bug-recall results
-- [Running Better Audits](https://ennodia.cherninlab.com/docs/guides/running-better-audits/) — prompt rubrics for Compare
+## Technical reference and contribution
 
-## Benchmarks
+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.
 
-The current benchmark is `multi-model-bug-recall`: small TypeScript review
-fixtures scored against 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.
-
-## Contributing
+### Experimental Pragmatic mode
 
-Ennodia is under active development. Bug reports and small, focused pull requests
-are welcome. 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/bench/README.md

@@ -1,7 +1,7 @@
 # Benchmarks
 
 Ennodia's first release-candidate benchmark is `multi-model-bug-recall`: small
-TypeScript review fixtures with committed oracles. It measures whether
+TypeScript review fixtures with committed oracles. It measures if
 parallel peer review plus Compare recovers more required findings than a solo
 harness answer.
 
@@ -11,8 +11,8 @@ The default command is deterministic and uses committed reference outputs:
 bun run bench:bug-recall
 ```
 
-The live command starts a fresh Ennodia MCP server and runs real harnesses. It
-is intentionally not part of `bun run verify`.
+The live command starts a fresh Ennodia Model Context Protocol (MCP) server and
+runs real harnesses. It is intentionally not part of `bun run verify`.
 
 ```sh
 bun run bench:bug-recall:live -- --fixture 001-missing-await
@@ -20,10 +20,12 @@ bun run bench:bug-recall:live -- --fixture 001-missing-await
 
 Useful flags:
 
-- `--fixture <id>` runs one fixture; repeat it to select several.
+- `--fixture <id>` runs one fixture. Repeat it to select multiple fixtures.
 - `--harness <id>` adds a solo baseline harness in live mode. Defaults to
   `codex` and `claude-code`.
-- `--judge-harness <id>` and `--synthesizer-harness <id>` pin Compare roles.
+- `--judge-harness <id>` and `--advisor-harness <id>` select Compare roles.
+- `--synthesizer-harness <id>` is a deprecated alias for
+  `--advisor-harness <id>`.
 - `--timeout-ms <ms>` sets the per-run timeout for live harness calls.
 - `--out <dir>` writes results to a specific directory.
 

package/bench/bug-recall/run.ts

@@ -21,7 +21,7 @@ type CliOptions = {
   timeoutMs: number;
   outDir?: string;
   judgeHarnessId?: string;
-  synthesizerHarnessId?: string;
+  advisorHarnessId?: string;
 };
 
 type McpTextContent = {
@@ -129,7 +129,7 @@ async function runLiveBenchmark(
         compare: true,
         timeoutMs: options.timeoutMs,
         judgeHarnessId: options.judgeHarnessId,
-        synthesizerHarnessId: options.synthesizerHarnessId,
+        advisorHarnessId: options.advisorHarnessId,
         maxOutputChars: 16_000,
       });
       outputs.push(runToOutput(
@@ -284,8 +284,16 @@ function parseArgs(args: string[]): CliOptions {
       options.outDir = requireValue(args, ++index, arg);
     } else if (arg === "--judge-harness") {
       options.judgeHarnessId = requireValue(args, ++index, arg);
-    } else if (arg === "--synthesizer-harness") {
-      options.synthesizerHarnessId = requireValue(args, ++index, arg);
+    } else if (
+      arg === "--advisor-harness" || arg === "--synthesizer-harness"
+    ) {
+      const value = requireValue(args, ++index, arg);
+      if (options.advisorHarnessId && options.advisorHarnessId !== value) {
+        throw new Error(
+          "--advisor-harness and --synthesizer-harness must match.",
+        );
+      }
+      options.advisorHarnessId = value;
     } else {
       throw new Error(`Unknown option: ${arg}`);
     }

package/bin/ennodia

@@ -1,2 +1,23 @@
-#!/usr/bin/env bun
-import "../src/cli.ts";
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const cliPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "src", "cli.ts");
+
+const bunCheck = spawnSync("bun", ["--version"], { stdio: "ignore" });
+
+if (bunCheck.error) {
+  process.stderr.write(
+    "Ennodia requires Bun (1.3.14 or newer) to run, but it wasn't found on your PATH.\n" +
+      "Install Bun from https://bun.sh, then try again:\n" +
+      "  curl -fsSL https://bun.sh/install | bash\n",
+  );
+  process.exit(1);
+}
+
+const result = spawnSync("bun", ["run", cliPath, ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+
+process.exit(result.status ?? 1);

package/docs/assets/agents/mcp.svg

@@ -1 +1 @@
-<svg fill="currentColor" fill-rule="evenodd" height="56" viewBox="0 0 24 24" width="56" xmlns="http://www.w3.org/2000/svg" style="flex: 0 0 auto; line-height: 1;"><title>ModelContextProtocol</title><path d="M15.688 2.343a2.588 2.588 0 00-3.61 0l-9.626 9.44a.863.863 0 01-1.203 0 .823.823 0 010-1.18l9.626-9.44a4.313 4.313 0 016.016 0 4.116 4.116 0 011.204 3.54 4.3 4.3 0 013.609 1.18l.05.05a4.115 4.115 0 010 5.9l-8.706 8.537a.274.274 0 000 .393l1.788 1.754a.823.823 0 010 1.18.863.863 0 01-1.203 0l-1.788-1.753a1.92 1.92 0 010-2.754l8.706-8.538a2.47 2.47 0 000-3.54l-.05-.049a2.588 2.588 0 00-3.607-.003l-7.172 7.034-.002.002-.098.097a.863.863 0 01-1.204 0 .823.823 0 010-1.18l7.273-7.133a2.47 2.47 0 00-.003-3.537z"></path><path d="M14.485 4.703a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a4.115 4.115 0 000 5.9 4.314 4.314 0 006.016 0l7.12-6.982a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a2.588 2.588 0 01-3.61 0 2.47 2.47 0 010-3.54l7.12-6.982z"></path></svg>
+<svg fill="currentColor" fill-rule="evenodd" height="56" viewBox="0 0 24 24" width="56" xmlns="http://www.w3.org/2000/svg" style="flex: 0 0 auto; line-height: 1;"><title>Model Context Protocol</title><path d="M15.688 2.343a2.588 2.588 0 00-3.61 0l-9.626 9.44a.863.863 0 01-1.203 0 .823.823 0 010-1.18l9.626-9.44a4.313 4.313 0 016.016 0 4.116 4.116 0 011.204 3.54 4.3 4.3 0 013.609 1.18l.05.05a4.115 4.115 0 010 5.9l-8.706 8.537a.274.274 0 000 .393l1.788 1.754a.823.823 0 010 1.18.863.863 0 01-1.203 0l-1.788-1.753a1.92 1.92 0 010-2.754l8.706-8.538a2.47 2.47 0 000-3.54l-.05-.049a2.588 2.588 0 00-3.607-.003l-7.172 7.034-.002.002-.098.097a.863.863 0 01-1.204 0 .823.823 0 010-1.18l7.273-7.133a2.47 2.47 0 00-.003-3.537z"></path><path d="M14.485 4.703a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a4.115 4.115 0 000 5.9 4.314 4.314 0 006.016 0l7.12-6.982a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a2.588 2.588 0 01-3.61 0 2.47 2.47 0 010-3.54l7.12-6.982z"></path></svg>

package/docs/assets/orchestration-pipeline.svg

@@ -1,6 +1,6 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="1100" height="500" viewBox="0 0 1100 500" role="img" aria-labelledby="title desc">
   <title id="title">Ennodia orchestration pipeline</title>
-  <desc id="desc">A code-review request is classified, routed through project rules to Claude Code and Codex CLI, compared, resolved, and returned as a final review.</desc>
+  <desc id="desc">Ennodia classifies a code-review request. It routes the request to Claude Code and Codex. The Judge and Result Advisor return a review.</desc>
   <defs>
     <marker id="arrow" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
       <path d="M 0 0 L 10 5 L 0 10 z" fill="#7aa7ff" />
@@ -61,7 +61,8 @@
   <g>
     <rect class="hub" x="890" y="207" width="130" height="86" rx="14" />
     <text class="label" x="955" y="242" text-anchor="middle">Compare</text>
-    <text class="small" x="955" y="267" text-anchor="middle">judge + synth</text>
+    <text class="small" x="955" y="262" text-anchor="middle">Judge</text>
+    <text class="small" x="955" y="280" text-anchor="middle">Result Advisor</text>
   </g>
 
   <path class="line" d="M 955 293 V 342" />
@@ -70,5 +71,5 @@
     <text class="label" x="955" y="394" text-anchor="middle">Review</text>
   </g>
 
-  <text class="small" x="550" y="454" text-anchor="middle">Every child task remains visible: status, logs, ETA, failure state, and final synthesis.</text>
+  <text class="small" x="550" y="454" text-anchor="middle">Every child task remains visible: status, logs, ETA, failure state, Judge findings, and recommended answer.</text>
 </svg>

package/docs/comparisons/agent-frameworks.md

@@ -7,12 +7,13 @@ General agent frameworks help developers build custom agent systems. They can
 offer roles, graphs, memory, tool routing, state, persistence, deployment
 patterns, and application-specific control.
 
-Ennodia is less general on purpose. It gives a primary agent a small MCP surface
-for asking other installed local agents for help and inspecting the result.
+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
 
-- You are designing the agent workflow yourself.
+- 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.
@@ -21,17 +22,21 @@ for asking other installed local agents for help and inspecting the result.
 
 - You do not want to build an agent system.
 - You want a local MCP tool that works with installed agent CLIs.
-- You want async task state, run history, failures, budget estimates, and
-  model-led Compare.
+- You want asynchronous task state, run history, failures, budget
+  estimates, and
+  Judge + Result Advisor Compare.
+- You want an optional Plan Advisor to suggest a bounded team while execution
+  remains a separate, validated action.
 - You want the primary agent to remain in charge.
 
 ## Key Difference
 
-Agent frameworks are construction kits. Ennodia is an orchestration helper for
-an already-running agent.
+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
 
-Do not claim Ennodia is more powerful than a framework. It is deliberately
-smaller. The benefit is that the user can add multi-agent review to an existing
-local workflow without designing an entire framework application.
+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
+does not require a complete framework application.

package/docs/comparisons/autogen.md

@@ -3,35 +3,40 @@ title: Ennodia vs AutoGen
 description: How Ennodia differs from AutoGen and programmable multi-agent application frameworks.
 ---
 
-[AutoGen](https://microsoft.github.io/autogen/stable/index.html) is a
-programming framework for building conversational single-agent and multi-agent
-applications, with an event-driven core for scalable multi-agent systems.
+[AutoGen](https://microsoft.github.io/autogen/stable/index.html) is a programming
+framework. Developers use it to create conversational single-agent and
+multi-agent applications. It has an event-driven core for scalable multi-agent
+systems.
 
-Ennodia is not a framework for authoring a new multi-agent application. It is a
-local MCP server that an existing agent can call.
+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
 
-- You want to build a multi-agent system in application code.
+- 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
 
-- The primary workflow already happens in Codex, Claude Code, OpenCode,
+- The primary workflow uses Codex, Claude Code, OpenCode,
   Antigravity, or another MCP-capable client.
-- You want to reuse installed local CLIs and subscriptions.
-- You want task traces, status, budget checks, and Compare without designing a
-  full multi-agent runtime.
+- You want to reuse installed local command-line interfaces (CLIs) and
+  subscriptions.
+- You want task traces, status, budget checks, and Compare without a full
+  multi-agent runtime.
+- You want a Plan Advisor to suggest explicit harness, model, and skill
+  assignments. Plan Advisor has no execution control.
 
 ## Key Difference
 
-AutoGen is for building multi-agent applications. Ennodia is for letting one
-agent ask other already-installed agents for help.
+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
 
-Do not compare them only by "number of agents." The important question is where
-the orchestration lives: inside a custom application framework, or inside a
-local MCP tool called by the user's existing agent.
+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
+local MCP tool.