ennodia 0.4.0 → 0.5.0

package/CONTRIBUTING.md

@@ -122,6 +122,12 @@ the root install. `bun run release:check` enforces these rules.
 The workflow passes it to npm as `NODE_AUTH_TOKEN`. JSR uses GitHub Actions
 OpenID Connect (OIDC) without a JSR token.
 
+Both npm packages publish with `--provenance` from the GitHub-hosted runner.
+The existing `id-token: write` permission lets npm attach a signed record of
+the source and build. This requires a public repository matching each
+package's `repository.url`. Previously published versions keep their
+original metadata. Provenance takes effect on the next new version.
+
 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

package/README.md

@@ -3,32 +3,42 @@
   <img alt="Ennodia" src="docs/assets/logo.svg" width="235" height="50">
 </picture>
 
-**Keep your agent. Get another way forward.**
+**Ennodia isn't another agent. It connects the agents you use.**
 
-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.
+Stay in Codex, Claude Code, or any agent you like.
+When a task needs another model, your agent hands that part over through Ennodia and brings the answer back.
+Ennodia runs on your computer, and each agent uses your own account.
 
 ```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.
+Have Gemini listen to meeting.mp3 through Ennodia and tell me what was decided.
 ```
 
-## When it helps
+## Why use it
 
-- 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.
+- **Keep the app you like.** Ennodia has no window of its own. You work in your agent as before, and it can now reach the others.
+- **Your agents work together.** Any agent can hand part of a task to any other and get the answer back in your chat.
+- **Nothing to pay, nothing to join.** Ennodia is free and open source, with no account. It uses the agents and plans you have.
+- **It grows with your agents.** It is a set of tools, not a framework or a method. Each new model one agent gains becomes an ability for all of them.
+- **It stays on your computer.** Every handoff leaves a receipt there: who did the work, how long it took, and what came back.
+- **Less to keep up with.** You don't need to follow every new model. Name the task, and your agent hands it to one that can do it.
 
-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.
+Next on the [roadmap](https://ennodia.cherninlab.com/docs/roadmap/): Ennodia reads its receipts, so your agent stops repeating what failed.
+
+## What each agent adds
+
+No model leads every task, so each agent you connect brings an ability the others lack.
+
+- **Listen.** Gemini hears audio files. Codex hands it the file path and gets back what Gemini heard.
+- **Draw.** Codex draws with GPT Image. Claude Code can hand it a brief and get the images back.
+- **Review.** Two other agents review the same patch in fresh sessions. Compare maps where they agree and differ.
+- **Read.** Kimi K3 in OpenCode reads long documents. Your agent hands it a spec and gets back the rules, each with its line number.
+
+When your own agent has the ability, it does the task itself, with no handoff.
+[See each route](https://ennodia.cherninlab.com/#abilities) and the [public scores behind each strength](https://ennodia.cherninlab.com/#evidence).
 
 ## Install
 
-Send this address to your primary agent:
+Send this address to your agent:
 
 ```text
 try-ennodia.cherninlab.com
@@ -47,7 +57,8 @@ For manual setup, add this Model Context Protocol (MCP) server to your client:
 }
 ```
 
-Ennodia loads six core tools by default. Add `"--tools", "all"` to `args` for the [full tool set](https://ennodia.cherninlab.com/docs/reference/mcp-tools/#tool-sets).
+Ennodia loads eight core tools by default: about 13,000 characters of tool definitions in each session.
+Add `"--tools", "all"` to `args` for the [full tool set](https://ennodia.cherninlab.com/docs/reference/mcp-tools/#tool-sets).
 
 Requirements: Bun `1.3.14` or newer, a compatible MCP client, and a supported agent with working provider access.
 `npx` downloads Ennodia. Bun runs it. You can also use `bunx ennodia`.
@@ -55,11 +66,26 @@ Requirements: Bun `1.3.14` or newer, a compatible MCP client, and a supported ag
 [Get your first result](https://ennodia.cherninlab.com/docs/getting-started/) ·
 [Installation for agents](https://ennodia.cherninlab.com/docs/install/)
 
-## Use your installed agents and skills
+## How a handoff works
+
+1. Your agent calls `ennodia_run` with the task, the agent or model to use, and a time limit.
+2. Ennodia checks the selected route, then starts that agent's own command-line tool in a fresh session, with its own tools and your account for it.
+3. The answer comes back to your conversation, with its status and a receipt saved on your computer.
+
+Your conversation history stays in your agent.
+For two or more answers, Compare maps agreements, contradictions, and gaps.
+When one answer is complete as it stands, Compare can choose it, and `ennodia_run` returns it unchanged.
+
+Include relevant constraints and prior decisions in your task prompt under **Keep in mind**.
+Ennodia asks workers and Compare to return useful reminders with reasons and evidence.
+Your agent verifies them before carrying them into the next task.
+See [how to read these notes](https://ennodia.cherninlab.com/docs/guides/understand-results/#keep-in-mind).
+
+## Supported agents
 
-Supported agents: Codex CLI, Claude Code, OpenCode, Kilo Code, Kiro CLI, Cline, Hermes Agent, and Antigravity.
+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.
+Discovery reports native login checks and recovery actions. Before execution, Ennodia verifies each selected model route with a small request when recent success is unavailable.
 Codex workers use a read-only sandbox by default.
 
 Ennodia discovers native Agent Skills and can request them for specific tasks.
@@ -70,10 +96,11 @@ Native agents can also select unrequested skills from their own environment.
 [Using skills](https://ennodia.cherninlab.com/docs/guides/agent-skills/) ·
 [Understand results](https://ennodia.cherninlab.com/docs/guides/understand-results/)
 
-## See it in practice
+## Evidence
 
 - [Can Gemini hear this file?](https://ennodia.cherninlab.com/articles/can-gemini-hear-this-file/): a Codex conversation hands an audio file to Gemini through Antigravity.
-- [Measurement plan](https://ennodia.cherninlab.com/docs/evidence/measurement/): how Ennodia will compare single agents with teams on public benchmarks.
+- [Measurement plan](https://ennodia.cherninlab.com/docs/evidence/measurement/): how Ennodia compares single agents with teams on public benchmarks.
+- [Audio routing pilot](bench/audio-routing/pilot-2026-09-26.md): Codex got 10 of 10 speech questions right through Gemini, and 4 of 10 alone. Across all 30 clips the gain was not significant, and each answer took about twice as long.
 
 ## Data and limits
 
@@ -81,9 +108,10 @@ 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`.
 
+Each handoff costs time and uses your agents' own quotas and charges.
+General time or token savings have not been established.
 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.
 
 [Data governance](https://ennodia.cherninlab.com/docs/concepts/data-governance/) ·
 [Budgets](https://ennodia.cherninlab.com/docs/guides/budgets-and-limits/) ·
@@ -91,8 +119,8 @@ Automatic agent updates and recommendations learned from past results remain fut
 
 ## Technical reference and contribution
 
-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 main entry point is `ennodia_run`.
+The full tool set adds raw tasks, separate Compare calls, budget estimates, and the Plan Advisor, which proposes explicit tasks before execution.
 
 [MCP tools](https://ennodia.cherninlab.com/docs/reference/mcp-tools/) ·
 [Experimental Ennodia IO](https://ennodia.cherninlab.com/docs/reference/ennodia-io/) ·
@@ -105,7 +133,29 @@ bun run verify
 
 ### Experimental Pragmatic mode
 
-Version 0.3.0 supports independent model attempts, tailored planning, skill trials and evidence comparison.
-The published `ennodia@next` recipes retain the earlier single-worker restriction.
-[Pragmatic mode](docs/guides/pragmatic-mode.md) keeps bulky evidence outside the main conversation and returns findings for verification.
+[Pragmatic mode](docs/guides/pragmatic-mode.md) runs independent model attempts, tailored plans, and skill trials, then compares the evidence.
+It keeps bulky evidence outside the main conversation and returns findings for your agent to verify.
 Savings are not yet validated.
+
+## Login recovery and updates
+
+Ennodia checks selected workers, Judge, and Advisor routes before execution.
+Blocked routes return a native recovery action before reviewers start.
+Ennodia says nothing about its own status unless an agent you asked for is blocked.
+Rechecks, setup, and blocked starts include a setup panel with the exact fix.
+
+Your agent calls `ennodia_setup` to show each agent's status and fix in your current session.
+Hosts that render MCP Apps, such as Claude Desktop and Visual Studio Code, can show it as a card with check buttons.
+Other hosts, such as Codex and Claude Code, show the Markdown panel.
+
+Run that action in an interactive terminal, then call `ennodia_check_harnesses` with the same harness and model and `refresh: true, verify: true`.
+Run receipts keep missing reviewer coverage visible, including in compact responses.
+
+Supported harness upgrades run once per day on use while Ennodia has no active tasks.
+Set `ENNODIA_AUTO_UPDATE=false` to disable them.
+Use `ennodia_check_harnesses` with `upgrade: true` to update and recheck immediately.
+
+Ennodia also checks its own installation automatically. Run results report the loaded code location, version, runtime, and installation scope. The report checks required files, bundled skills, and storage access. The recheck tool refreshes this report. MCP startup instructions carry only installation problems.
+
+Mention installation limitations when they affect the request. Cache installs can change on a future unpinned launch. These local checks do not verify the latest registry version or provider access.
+See [recovery and updates](https://ennodia.cherninlab.com/docs/reference/supported-harnesses/#recovery-and-updates).

package/bin/ennodia

@@ -5,19 +5,30 @@ 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" });
+const bunCheck = spawnSync("bun", ["--version"], { encoding: "utf8", timeout: 5_000 });
 
-if (bunCheck.error) {
+if (bunCheck.error || bunCheck.status !== 0) {
   process.stderr.write(
-    "Ennodia requires Bun (1.3.14 or newer) to run, but it wasn't found on your PATH.\n" +
+    "Ennodia requires Bun (1.3.14 or newer). Bun wasn't available on PATH or failed its version check.\n" +
       "Install Bun from https://bun.sh, then try again:\n" +
       "  curl -fsSL https://bun.sh/install | bash\n",
   );
   process.exit(1);
 }
 
+const bunVersion = bunCheck.stdout.trim();
+const minimum = [1, 3, 14];
+const parsed = /^([0-9]+)\.([0-9]+)\.([0-9]+)(?:[-+].*)?$/.exec(bunVersion);
+const parts = parsed?.slice(1, 4).map(Number);
+const firstDifference = parts?.findIndex((part, index) => part !== minimum[index]);
+if (!parts || (firstDifference !== -1 && parts[firstDifference] < minimum[firstDifference]) || (firstDifference === -1 && bunVersion.split("+")[0].includes("-"))) {
+  process.stderr.write(`Ennodia requires Bun >=1.3.14; found ${bunVersion}. Upgrade Bun with bun upgrade, then restart Ennodia.\n`);
+  process.exit(1);
+}
+
 const result = spawnSync("bun", ["run", cliPath, ...process.argv.slice(2)], {
   stdio: "inherit",
+  env: { ...process.env, ENNODIA_LAUNCHER_PATH: fileURLToPath(import.meta.url) },
 });
 
 process.exit(result.status ?? 1);

package/docs/getting-started.md

@@ -31,8 +31,20 @@ Bring the findings back to this conversation.
 ```
 
 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.
+Ennodia checks each selected agent before execution. Your agent hears nothing about Ennodia's status unless an agent you requested is blocked.
+A blocked agent comes with its exact fix, such as a sign-in command.
+
+For setup or recovery, give your agent this request:
+
+```text
+Show Ennodia setup in this session. Help me fix the agent I choose.
+After I complete native sign-in or configuration, recheck that agent and continue my task.
+```
+
+Your agent calls `ennodia_setup` and shows you each agent's status, with the exact fix for blocked agents.
+Hosts that render MCP Apps can show it as a card with check buttons. A check sends at most one small model request.
+
+Complete sign-in and credential changes in the native tool. Keep credentials out of chat.
 
 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).
@@ -111,7 +123,7 @@ 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).
+Ennodia loads eight 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.

package/docs/guides/understand-results.md

@@ -27,6 +27,51 @@ When Judge output is unusable, the result exposes `analysisAvailable: false`.
 The Result Advisor can continue with `basis: "candidates-only"`.
 That result has less analysis behind it and needs corresponding scrutiny.
 
+## Keep in mind
+
+One agent can notice a constraint or gap that another agent misses.
+Put relevant known constraints and prior decisions in the normal task prompt under **Keep in mind**.
+For a task where the same function serves a web route and a command-line tool, a prompt could include:
+
+```text
+Review the proposed retry change.
+
+Keep in mind:
+- This function also serves the command-line tool. Preserve that behavior and check both callers.
+```
+
+Ennodia asks workers to return up to three concise, task-specific notes when useful and compatible with the requested answer format.
+Each note states what matters, why it matters, and what evidence supports it.
+This is prompt guidance. A worker can miss a useful note.
+
+Compare returns structured notes in `advisor.keepInMind`, for example:
+
+```json
+{
+  "keepInMind": [
+    {
+      "note": "Reviewer B reports running only the web-route test.",
+      "whyItMatters": "A passing web-route test does not cover that caller.",
+      "evidence": "Reviewer B reports running only the web-route test.",
+      "sourceIds": ["review-b"],
+      "status": "reported"
+    }
+  ]
+}
+```
+
+`reported` attributes a point to a candidate. It does not prove the point.
+`inferred` marks a conclusion drawn from the available answers.
+`unverified` marks a point that still needs evidence.
+Source IDs identify the candidates behind a note.
+An empty list can identify coverage that no candidate supplied.
+
+The list is empty when Compare has no useful notes.
+Run results also expose nonempty notes as `keepInMind`, including in compact output.
+This field stays separate from `finalAnswer` so a chosen file or patch stays unchanged.
+The primary agent checks each note and carries only relevant ones into the next assignment.
+Notes do not grant permissions, trigger another run, or create memory across runs.
+
 ## Read the attempt record
 
 Task records include the selected agent, requested skills, status, elapsed time, and bounded output.

package/docs/install.md

@@ -70,7 +70,7 @@ 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).
+Ennodia loads eight 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.
@@ -79,10 +79,16 @@ Tell the user which step is needed before trying to call Ennodia.
 
 ## Get one useful result
 
+Ennodia includes an installation self-check in run results and rechecks. Its MCP startup instructions carry only installation problems. It uses the loaded code location to identify a source checkout, project-local dependency, global installation, package cache, or unknown scope. It checks the Bun version, package version, core files, bundled skills, and filesystem access for temporary workspaces, history, and harness update receipts. Development files are not required for a packaged install. The npm launcher stops before startup if Bun is too old.
+
+Tell the user about reported installation problems before the first run. Call `ennodia_check_harnesses` with `refresh: true` to refresh the installation report and native harness status after a repair. Filesystem access checks do not prove free disk space or future writes. They do not verify provider access or the latest published package version. A global install gives no extra permissions. The user's normal permissions still apply.
+
+The report also identifies compiled code. A compiled executable does not need separate source entrypoints. Missing bundled skills remain a reported limitation. Compilation is currently an experimental build path.
+
 After the client exposes Ennodia's tools, start with one small task:
 
-1. Call `ennodia_list_harnesses` with `refresh: true`.
-2. Choose one available worker for a focused, read-only check from the user's current task.
+1. Call `ennodia_setup`. Show the user its panel: which agents are ready, and the exact fix for each blocked agent.
+2. Choose one ready or unchecked worker for a focused, read-only check from the user's current task.
 3. Call `ennodia_run` with `prompt`, `harnessId`, `mode: "single"`, `compare: false`, and the relevant `cwd`.
 4. Poll `ennodia_get_run` with the returned `id` as `runId`.
 5. Stop when the status is `succeeded`, `failed`, or `cancelled`.

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 eight core tools add about 3,250 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/mcp-tools.md

@@ -11,8 +11,8 @@ events, child task IDs, Judge + Result Advisor state, and the final answer.
 ## Tool sets
 
 An agent loads every tool definition into each session where Ennodia is configured, even when the session never calls Ennodia.
-By default, Ennodia loads six core tools, about 10,000 characters of definitions.
-They cover handing work to one agent or a team, Compare, waiting, cancelling, and run history.
+By default, Ennodia loads eight core tools, about 13,000 characters of definitions.
+They cover handing work to one agent or a team, Compare, waiting, cancelling, run history, and harness recovery.
 
 The full set adds 20 tools for raw tasks, compositional slices, Plan Advisor, budget estimates, separate Compare calls, and skill installation.
 It loads about 46,000 characters of definitions.
@@ -50,7 +50,9 @@ This setting approves Ennodia runs only. Codex's sandbox and its other tools kee
 
 | Goal | Tool sequence | Tool set |
 | --- | --- | --- |
-| Check local setup | `ennodia_list_harnesses` | core |
+| Show agent status and fixes in this session | `ennodia_setup` | core |
+| Recheck an agent after a fix | `ennodia_check_harnesses` | core |
+| List agents for routing | `ennodia_list_harnesses` | core |
 | Start a visible end-to-end run | `ennodia_run` -> `ennodia_get_run` | core |
 | Inspect terminal receipts after restart | `ennodia_history` | core |
 | Preview route and cost | `ennodia_estimate_budget` | full |
@@ -172,6 +174,9 @@ Version probes have bounded deadlines. A failed probe appears in adapter notes w
 | --- | --- | --- |
 | `refresh` | `false` | Ignore the short discovery cache and re-scan. |
 
+The result is JSON only. Agents call this tool for routing, so it carries no setup panel.
+Use `ennodia_setup` to show the user each agent's status and fix.
+
 Use this first when a client setup, command path, or adapter is not behaving as
 expected.
 
@@ -238,6 +243,8 @@ arguments, permissions, isolation, timeouts, retries, or budgets.
 Harness inventory entries preserve optional `inputGuidance: string[]` from discovery.
 Plan Advisor treats this bounded guidance as observations, not proof of native media support.
 Slices execute concurrently. For unverified native access, its instructions request a probe-only plan, followed by a new plan after the probe.
+Plan Advisor also asks each slice prompt to carry relevant constraints and prior decisions from the original task under **Keep in mind**.
+This guidance does not pass one independent candidate's findings to another.
 
 The lifecycle is deliberately two-phase: request and inspect advice first, then
 launch the exact validated plan in a separate call. Ennodia rejects invalid
@@ -419,6 +426,12 @@ It also returns the final answer when available. The important value is `id`.
 Poll it with
 `ennodia_get_run`.
 
+Include relevant constraints and prior decisions under **Keep in mind** in the normal `prompt`.
+There is no separate input field.
+Workers are asked to return up to three useful notes with reasons and evidence when the requested answer format permits.
+For compared runs, nonempty Result Advisor notes appear in `keepInMind`, separate from `finalAnswer`.
+Normal and compact run views preserve this field.
+
 ### `ennodia_get_run`
 
 Returns the current run state. Set `waitMs` to wait for completion without repeated immediate polls. A wait timeout leaves the run running.
@@ -615,6 +628,23 @@ blind spots, and risks. The Result Advisor uses that analysis plus the original
 candidates to return a typed answer, basis, confidence, and open questions.
 This is model-led comparison, not formal voting.
 
+The Result Advisor also returns `keepInMind`: up to three task-specific notes that the receiving agent could overlook.
+The field defaults to `[]` when omitted or when no useful notes are available.
+Each note has these fields:
+
+| Field | Meaning |
+| --- | --- |
+| `note` | Constraint, connection, assumption, or gap to carry forward (at most 1000 characters). |
+| `whyItMatters` | Effect on the task or next decision (at most 1000 characters). |
+| `evidence` | Supporting observation or explicit evidence gap (at most 2000 characters). |
+| `sourceIds` | Up to 64 listed candidate IDs supporting the note. A `reported` note requires a source. Use `[]` for inferred or unverified missing coverage. |
+| `status` | `reported` for an attributed candidate report, `inferred` for a conclusion from available answers, or `unverified` for a point that needs evidence. |
+
+A `reported` note is not independent proof.
+Invalid optional notes are omitted with an `advisor-notes-ignored` event. The valid answer and candidate choice are preserved.
+The primary agent verifies notes and carries only relevant ones into later prompts.
+These notes do not change permissions, start another run, or create memory across runs.
+
 When one candidate fully answers the prompt as it stands, such as a complete
 file, the Result Advisor names it in `chosenSourceId`. A caller can then use
 that candidate's own text, not a rewrite. `ennodia_run` does this for you: its
@@ -768,3 +798,62 @@ Preserve full patch artifacts and verify them before application.
 A later Compare call and its Judge and Result Advisor have separate limits.
 `includeCompareEstimate` includes an estimate, not a reserved spending balance.
 Count these stages, retries and verification when reporting whole-task cost.
+
+### `ennodia_setup`
+
+Show the user each agent's status and the exact fix for blocked agents.
+The tool takes no input. It refreshes native sign-in status without a model request.
+It declares `readOnlyHint`, so clients such as Codex run it without an approval prompt.
+
+The result has the same JSON shape as `ennodia_check_harnesses`, plus the `ennodia://setup` panel.
+Hosts that render MCP Apps show the [setup card](#setup-card) in place of the panel.
+Sign-in and credential changes stay in each agent's own CLI.
+
+#### Setup card
+
+`ennodia_setup` and `ennodia_check_harnesses` name the `ui://ennodia/setup.html` resource in `_meta.ui.resourceUri`.
+The resource uses the MCP Apps type `text/html;profile=mcp-app`.
+Hosts that render MCP Apps show the card inside the conversation. Other hosts ignore it and keep the Markdown panel.
+
+The card lists agents that need the user first, with the next step for each.
+A login blocker shows its sign-in command with a copy button.
+Each check button calls `ennodia_check_harnesses` for that agent and model with `verify: true`.
+A check sends at most one small model request.
+When an agent becomes ready, the card can send a short note to the chat.
+
+The card loads no external code and makes no network requests.
+It never collects credentials.
+
+### `ennodia_check_harnesses`
+
+`ennodia_check_harnesses` is part of the default tool set.
+
+The result includes `installation`, a local self-check of Ennodia's loaded code root, version, installation scope, Bun runtime, core files, bundled skills, and storage access. MCP initialization sends only its problems to the host, and a healthy installation adds nothing. `ennodia_run` and `ennodia_get_run` include the full report even in compact results. Mention its limitations when they affect the request.
+
+`refresh: true` refreshes installation evidence as well as harness readiness. Scope remains `unknown` when filesystem evidence is insufficient. The report does not verify registry freshness, provider access, disk capacity, or future writes.
+
+It accepts `harnessIds`, `model`, `cwd`, `refresh`, `verify`, and `upgrade`.
+Native status checks are the default. `verify: true` makes a bounded real model request.
+
+`unverified` means unchecked. `ennodia_run` verifies its selected routes automatically.
+Use targeted `harnessIds` for recovery checks. Unrelated blockers do not prevent work on usable requested routes.
+
+Rechecks, `ennodia_setup`, and blocked preflight responses include an embedded `ennodia://setup` resource with `text/markdown` content.
+The JSON text response keeps its existing shape.
+
+The panel is a table of agents, with agents that need the user first. Each row gives the status in plain words and the next step.
+Sign-in commands follow the table, for login blockers only. Key expiry and quota blockers name their own recovery.
+Show the panel when the host displays no setup card. Recheck the same harness and model after recovery, then resume the original task.
+
+`upgrade: true` runs supported updaters before rediscovery and recheck.
+This tool can change installed software and call providers, so it does not declare `readOnlyHint`.
+
+Present `actionRequired` immediately, including on partial success.
+Do not wait for an explicit user question about missing reviewers.
+Run preflight errors return `isError`, recovery actions, and zero started reviewers.
+Run receipts retain `preflight`, `coverage`, and `actionRequired` in compact responses.
+Use the matching native recovery action, then recheck the same route.
+
+An expired provider API key returns `credentials-expired` and requires key replacement.
+Depleted credits return `quota-exhausted` and require capacity recovery.
+See [Recovery and updates](/docs/reference/supported-harnesses/#recovery-and-updates).

package/docs/reference/supported-harnesses.md

@@ -7,6 +7,12 @@ Ennodia coordinates local agents through thin adapters. Each harness uses a
 local command-line interface (CLI). Use `ennodia_list_harnesses` to see what is
 installed and runnable on the current machine.
 
+On macOS, discovery checks the existing `PATH` first, then `/opt/homebrew/bin`,
+`/usr/local/bin`, and `~/.local/bin`. This covers restricted GUI and MCP launch
+paths without changing the selected account, model, or child process environment.
+Explicit command paths and routes with no command candidates stay unchanged.
+Restart the MCP server after updating Ennodia to load discovery changes.
+
 ## Adapter IDs
 
 | ID | Tool | Notes |
@@ -32,15 +38,18 @@ installed and runnable on the current machine.
 ```
 
 The response reports availability, runnable state, command path, version,
-capabilities, adapter notes, and optional `inputGuidance`.
+capabilities, adapter notes, optional `inputGuidance`, and `readiness`.
 
 `inputGuidance` is a bounded `string[]` of adapter observations and input advice.
 It does not guarantee media support, authentication, or access to a requested model.
 Plan Advisor receives this guidance in its harness inventory.
 
-Discovery checks installed commands, not active authentication or model access.
-A stalled version probe stops at its deadline and adds an adapter note.
-Use a small real task to check the selected agent before sending larger work.
+Discovery checks installation and native login status through supported commands.
+Model access remains unverified until a small real request or a recent successful task returns an answer.
+A stalled check stops at its deadline and reports a blocker.
+Ennodia checks selected worker, Judge, and Advisor routes before execution.
+Known blockers prevent requested work from starting.
+Automatic routing excludes blocked routes and reports missing coverage.
 
 ## Media inputs
 
@@ -110,6 +119,75 @@ agy --version
 agy models
 ```
 
-If the shell cannot find `agy` at all, open Antigravity and use its supported
-CLI install or shell-integration flow first. Then restart the Model Context
+If neither `PATH` nor the native install roots contain `agy`, open Antigravity
+and use its supported CLI install or shell-integration flow first. Then restart the Model Context
 Protocol (MCP) client and call `ennodia_list_harnesses` again.
+
+## Recovery and updates
+
+Run the native command returned in `readiness.recovery` in an interactive terminal.
+Keep the intended account, provider, and model.
+Call `ennodia_check_harnesses` after sign-in:
+
+```json
+{
+  "harnessIds": ["codex"],
+  "refresh": true,
+  "verify": true
+}
+```
+
+Pass the same `model` and `cwd` when rechecking an explicit route.
+The check returns `actionRequired` for login, setup, model, capacity, and connectivity blockers.
+A missing CLI requires installation. A capacity failure requires capacity recovery.
+Neither is fixed by repeated sign-in.
+
+`credentials-expired` means the configured provider API key has expired.
+Replace the key through the native credential flow for the intended provider.
+Signing in again does not renew an expired API key.
+`quota-exhausted` includes depleted credits.
+Restore credits or quota through the intended provider before rechecking.
+Ennodia reads terminal-formatted native errors and returns the matching recovery action.
+
+Hermes uses the full `hermes chat` CLI. The legacy `hermes-agent` executable is not compatible.
+
+Native checks cache for 30 seconds. Verified routes cache for five minutes.
+A native authentication failure invalidates the route immediately.
+Concurrent checks of the same route share one request.
+
+`unverified` means unchecked. It does not mean a failed harness.
+`ennodia_run` verifies its selected routes before launching workers.
+Checking every supported harness is not a prerequisite for a run.
+
+Unrelated harness blockers do not prevent work on a usable requested route.
+A verified default route does not prove access to other models.
+Use the existing user authorization and the host approval policy.
+Ennodia does not require an additional approval step.
+
+Model probes run in an empty temporary directory with normal native permissions.
+A temporary directory is not a security sandbox.
+
+Probes use provider capacity and reserve 256 input tokens per route for budget checks.
+The reserve is an estimate, not a measurement of provider usage.
+Probe calls count toward `maxChildTasks`. Usage remains unknown when the provider reports no measurement.
+
+Before ordinary execution, Ennodia attempts supported upgrades once per day while no Ennodia task is active.
+Homebrew installations use their installed formula or cask.
+An npm Codex installation uses its supported npm update command.
+Other supported installations use native updaters.
+
+Updates preserve the installed distribution and channel and use no force flags.
+Pinned or unsupported installations and failed updates require native maintenance.
+Updater success is not proof of model readiness.
+Ennodia rediscovers the version and rechecks the route.
+
+Set `ENNODIA_AUTO_UPDATE=false` in the MCP server environment to disable automatic upgrades.
+Call `ennodia_check_harnesses` with `upgrade: true` for an immediate update attempt and recheck.
+The response includes `readiness.upgrade` with the update result and native command.
+Approved Advisor plans do not upgrade during execution, so their frozen inventory remains stable.
+Automatic updates run on use.
+Ennodia does not install a background daemon.
+
+Report `actionRequired` and reduced `coverage` to the user on the first response that contains them.
+Compact run responses retain these fields.
+MCP clients control how those responses appear in the conversation.