ennodia 0.1.1 → 0.2.0

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,90 +1,103 @@
 <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> 
+  <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>
 </a>
 
-<p><strong>MCP server for multi-agent review with Compare and traceable receipts</strong></p>
+<p><strong>Model Context Protocol (MCP) server for multi-agent review with Compare and traceable receipts</strong></p>
 
 <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" />
+  <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>
 
 <p align="center">
-  <img alt="Ennodia terminal comparing three completed AI reviews" src="docs/assets/terminal.png" width="600">
+  <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>
 
 </div>
 
-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.
+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.
 
-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.
+Before work, an optional Plan Advisor can propose a bounded set of harnesses,
+models, and skills. It does not start the proposed work.
 
 ## Install
 
-Send this to your primary agent and let it handle setup:
+Send this address to your primary agent. The agent can then complete the
+installation:
 
 ```text
 try-ennodia.cherninlab.com
 ```
-Or run it directly as a stdio MCP server from npm:
+To run Ennodia directly as a standard input/output (stdio) MCP server, use:
 
 ```sh
 npx -y ennodia
 ```
+To use Bun directly, run `bunx 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.
+For a registry or client installer, use the
+[Ennodia Smithery page](https://smithery.ai/servers/cherninlab/ennodia).
 
-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
+For manual installation or local development, see
 [Quickstart](https://ennodia.cherninlab.com/docs/getting-started/).
 
 ## What Ennodia does
 
-- Discovers available local AI tools
+- 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, timing, logs, and failures
+- Shows status, elapsed time, logs, and failures
 - Cancels tasks and runs explicitly
-- Compares multiple completed outputs
-- Synthesizes one answer from the comparison
+- 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
 
-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.
+`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 is for deliberation-class work: a run usually takes minutes, and Compare
-adds two serial model passes after the child agents finish.
+See [MCP tools](https://ennodia.cherninlab.com/docs/reference/mcp-tools/) for
+the full tool and parameter reference.
+
+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.
+
+## Judge, Plan Advisor, and Result Advisor
+
+Each role has limited responsibilities:
+
+- **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.
 
 ## Ennodia IO
 
-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:
+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
 ```
 
 See [Ennodia IO](https://ennodia.cherninlab.com/docs/reference/ennodia-io/) for
-supported fields, auth behavior, CORS posture, and current limits.
+supported fields, authentication behavior, cross-origin resource sharing
+rules, and current limits.
 
 ## Supported harnesses
 
@@ -97,30 +110,33 @@ supported fields, auth behavior, CORS posture, and current limits.
 - Hermes Agent
 - Antigravity
 
-Adapters stay thin — shared routing, tracing, task state, recovery, and
-Compare logic live in core modules.
+Adapters stay thin. Core modules contain shared routing, trace data, task state,
+recovery, and Compare logic.
+
+Evaluated candidates include Gemini CLI, GitHub Copilot CLI, Amp, Aider, Goose,
+Qwen Code, and Cursor CLI. Ennodia does not include these candidates.
 
-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 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/) — 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
+- [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`: small TypeScript review
-fixtures scored against committed bug oracles. Run the deterministic suite with:
+The current benchmark is `multi-model-bug-recall`. It uses small TypeScript
+review fixtures and committed bug oracles. Run the deterministic suite with:
 
 ```sh
 bun run bench:bug-recall
@@ -133,8 +149,8 @@ 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
+## Contribute
 
-Ennodia is under active development. Bug reports and small, focused pull requests
-are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the local verification
-workflow.
+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.

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.