ennodia 0.1.1 → 0.2.0

package/docs/comparisons/chathub.md

@@ -3,26 +3,28 @@ title: Ennodia vs ChatHub
 description: How Ennodia differs from ChatHub and other side-by-side chatbot comparison tools.
 ---
 
-[ChatHub](https://doc.chathub.gg/introduction) is a human-facing app for using
-multiple AI chatbots side by side. Its core experience is chatbot comparison
-through a web app or browser extension.
+[ChatHub](https://doc.chathub.gg/introduction) is an app for people who use
+multiple artificial intelligence (AI) chatbots side by side. It provides
+web, browser extension, desktop, and mobile access.
 
-Ennodia is not a chat UI. It is meant to be called by an AI agent while that
-agent is already working.
+Ennodia is not a chat user interface (UI). An AI agent calls Ennodia during a
+task.
 
 ## Choose ChatHub When
 
 - A human wants to compare chatbot answers visually.
-- The main workflow is interactive chat, not local MCP tool orchestration.
+- The main workflow is interactive chat, not local Model Context Protocol (MCP)
+  tool orchestration.
 - You want a polished multi-chat interface across hosted chatbots.
 
 ## Choose Ennodia When
 
-- A primary agent needs help during a task and can call MCP tools.
-- You want local agent CLIs to run as child tasks.
-- You want task state, stdout, stderr, failures, and Compare state captured.
-- You want the final answer synthesized for the user instead of asking the user
-  to manually grade a side-by-side wall of responses.
+- A primary agent needs help and can call MCP tools.
+- You want local agent command-line interfaces (CLIs) to run as child tasks.
+- You want task state, standard output, standard error, failures, and Compare
+  state captured.
+- You want a Judge to map the differences. You want a Result Advisor to
+  recommend an answer. The user does not need to grade all responses.
 
 ## Key Difference
 
@@ -31,6 +33,5 @@ work to other local agents and inspect what happened.
 
 ## Common Mistake
 
-Do not pitch Ennodia as "ChatHub for agents" unless you immediately explain the
-missing piece: Ennodia has task orchestration and traces, not a human chat
-comparison interface.
+Do not call Ennodia "ChatHub for agents." Explain that Ennodia provides task
+orchestration and traces. It does not provide a human chat comparison interface.

package/docs/comparisons/index.md

@@ -3,25 +3,30 @@ title: Comparisons
 description: How Ennodia compares to model routers, chat comparison tools, agent frameworks, ensembles, model merging, and adjacent multi-agent ideas.
 ---
 
-Ennodia is a local capability layer for installed agent CLIs. Through MCP, it
-lets a primary agent ask those local agents for help, then inspect child task
-status, raw outputs, failures, budget assumptions, and model-led Compare
-results. Through experimental IO, apps can discover local provider options and
-send a small OpenAI-compatible chat-completions subset to those same agents.
+Ennodia is a local capability layer for installed agent command-line interfaces
+(CLIs). Through Model Context Protocol (MCP), a primary agent can request help
+from those local agents.
 
-This section exists because several adjacent tools sound similar from far away.
-They are usually optimized for different jobs.
+The primary agent can inspect child task status, raw outputs, failures, budget
+assumptions, and model-led Compare results.
+
+Through experimental Ennodia IO, apps can discover local provider options. Apps
+can send a small OpenAI-compatible chat-completions application programming
+interface (API) subset to the same agents.
+
+Some adjacent tools have similar descriptions. They usually have different
+purposes.
 
 ## Choose the Right Page
 
-| If you are asking... | Read |
+| Question | Page |
 | --- | --- |
 | Is Ennodia a hosted multi-model API? | <span class="agent-logo agent-logo--openrouter" aria-hidden="true"></span>[Ennodia vs OpenRouter](./openrouter/) |
-| Is Ennodia a side-by-side chatbot UI? | [Ennodia vs ChatHub](./chathub/) |
+| Is Ennodia a side-by-side chatbot user interface (UI)? | [Ennodia vs ChatHub](./chathub/) |
 | Is Ennodia a graph runtime for agents? | <span class="agent-logo agent-logo--langgraph" aria-hidden="true"></span>[Ennodia vs LangGraph](./langgraph/) |
 | Is Ennodia like AutoGen? | [Ennodia vs AutoGen](./autogen/) |
 | Is Ennodia a general-purpose agent framework? | [Ennodia vs Agent Frameworks](./agent-frameworks/) |
-| Is Ennodia an ensemble or Mixture-of-Agents system? | [Ennodia vs MoA and Ensembles](./mixture-of-agents/) |
+| Is Ennodia an ensemble or Mixture-of-Agents system? | [Ennodia vs Mixture-of-Agents and Ensembles](./mixture-of-agents/) |
 | Is Ennodia model merging? | [Ennodia vs Model Merging](./model-merging/) |
 | What is the broader pattern? | [Second Opinions as Infrastructure](/docs/concepts/second-opinions/) |
 
@@ -30,13 +35,16 @@ They are usually optimized for different jobs.
 Ennodia is:
 
 - a local MCP server
-- an experimental local IO surface for app-facing provider options
-- a way for a primary agent to ask other installed local agents for help
+- an experimental local IO surface for provider options in apps
+- a way for a primary agent to request help from other installed local agents
 - a runner for real local agent CLIs, not only raw model APIs
-- a visible trace of child task IDs, status, stdout, stderr, failures, final
-  answers, and terminal run history
+- a visible trace of child task identifiers (IDs), status, standard output,
+  standard error, failures, final answers, and terminal run history
 - a preflight budget estimate and local limit check before expensive runs
-- a model-led Compare workflow over successful outputs
+- an optional Plan Advisor that proposes a validated, inert work plan and never
+  executes it
+- a model-led Compare workflow where the Judge maps successful outputs and the
+  Result Advisor recommends an answer
 - a native Agent Skills bridge for harnesses that support `SKILL.md` folders
 
 ## What Ennodia Is Not
@@ -52,8 +60,8 @@ Ennodia is not:
 - a replacement for a primary agent
 - proof that multi-agent review improves every task
 
-Durable model and skill preference memory is roadmap work. Terminal run history
-is persisted locally by default; in-progress run and task state remains
+Durable model and skill preference memory is roadmap work. By default, Ennodia
+stores terminal run history locally. In-progress run and task state remains
 process-local.
 
 ## Other Related Work
@@ -63,9 +71,9 @@ Some related ideas do not need a full page yet:
 | Category | Examples | How Ennodia differs |
 | --- | --- | --- |
 | Model councils | [karpathy/llm-council](https://github.com/karpathy/llm-council) | Ennodia adapts council-like review to local agent CLIs, MCP task state, failures, and traces. |
-| Evaluator-optimizer loops | Generator/evaluator workflows | Ennodia can support review loops, but its core unit is delegation to installed local agents. |
-| Consensus and voting | Majority, quorum, or weighted-vote schemes | Ennodia Compare judges and synthesizes; it does not implement formal voting rules. |
-| Inference optimization proxies | [optillm](https://github.com/algorithmicsuperintelligence/optillm) | Ennodia runs installed local agents and exposes a small local IO subset; it is not a hosted inference optimization proxy. |
+| Evaluator-optimizer loops | Generator/evaluator workflows | Ennodia can support review loops, but its principal operation delegates work to installed local agents. |
+| Consensus and voting | Majority, quorum, or weighted-vote schemes | Ennodia Compare uses a Judge and Result Advisor. It does not implement formal voting rules. |
+| Inference optimization proxies | [optillm](https://github.com/algorithmicsuperintelligence/optillm) | Ennodia runs installed local agents and exposes a small local IO subset. It is not a hosted inference optimization proxy. |
 
-Use another tool when that tool's job is the job you need. Use Ennodia when the
-primary agent is already working and needs visible help from other local agents.
+Use another tool if its purpose matches your task. Use Ennodia when a primary
+agent needs visible help from other local agents.

package/docs/comparisons/langgraph.md

@@ -4,33 +4,40 @@ description: How Ennodia differs from LangGraph's programmable graph runtime for
 ---
 
 [LangGraph](https://docs.langchain.com/oss/python/langgraph/overview) is a
-low-level orchestration framework and runtime for building, managing, and
-deploying long-running, stateful agents.
+low-level orchestration framework and runtime. Developers use it to build,
+manage, and deploy long-running, stateful agents.
 
-Ennodia is intentionally narrower. It does not ask you to define a custom graph,
+Ennodia is intentionally narrower. It does not require a custom graph,
 state machine, durable agent state, or application runtime.
 
 ## Choose LangGraph When
 
-- You are building an agentic application.
+- You create an agentic application.
 - You need custom graph nodes, edges, state, persistence, or deployment control.
 - You want to model a workflow as programmable application infrastructure.
 - You own the application code and want a framework embedded in that code.
 
 ## Choose Ennodia When
 
-- You already have a primary agent working in an MCP client.
-- You want that agent to ask other installed local agent CLIs for help.
-- You want visible child runs, failures, ETA, and final synthesis.
-- You want a small MCP surface instead of a full application framework.
+- You have a primary agent in a Model Context Protocol (MCP) client.
+- You want that agent to request help from other installed local agent
+  command-line interfaces (CLIs).
+- You want visible child runs, failures, estimated completion time, Judge
+  findings, and a Result Advisor answer.
+- You want optional team advice. The advice remains inert until an explicit,
+  validated start request.
+- You want a small MCP surface without a full application framework.
 
 ## Key Difference
 
-LangGraph is for building agent systems. Ennodia is for delegating work from one
-agent to other local agents during a task.
+LangGraph helps developers create agent systems. Ennodia lets one agent delegate
+work to other local agents during a task.
+
+Plan Advisor does not change this boundary: it can propose explicit worker
+assignments, but it cannot define arbitrary graph behavior or execute the plan.
 
 ## Common Mistake
 
 Do not treat Ennodia as a lighter LangGraph runtime. Ennodia does not replace a
-programmable graph framework; it gives an existing agent a simple way to request
-outside review or assistance.
+programmable graph framework. It gives an active agent a simple way to request
+an independent review or other assistance.

package/docs/comparisons/mixture-of-agents.md

@@ -1,37 +1,40 @@
 ---
-title: Ennodia vs MoA and Ensembles
-description: How Ennodia differs from Mixture-of-Agents papers, LLM ensembles, majority voting, and benchmark-oriented aggregation.
+title: Ennodia vs Mixture-of-Agents and Ensembles
+description: How Ennodia differs from Mixture-of-Agents papers, large language model ensembles, majority voting, and benchmark-oriented aggregation.
 ---
 
-[Mixture-of-Agents](https://arxiv.org/abs/2406.04692) explores layered LLM
-aggregation, where models use outputs from previous layers to improve the final
-answer. Other ensemble work studies majority rules, voting, or task-specific
-aggregation over multiple model outputs.
+[Mixture-of-Agents](https://arxiv.org/abs/2406.04692) explores layered large
+language model aggregation. Models use outputs from previous layers to
+improve the final answer. Other ensemble work studies majority rules, voting,
+or task-specific aggregation over multiple model outputs.
 
-Ennodia is adjacent, but it is not primarily a benchmark ensemble or formal
-voting engine.
+Ennodia uses some related ideas, but it is not primarily a benchmark ensemble
+or formal voting engine.
 
-## Choose MoA or an Ensemble When
+## Choose Mixture-of-Agents or an Ensemble When
 
-- You are designing an inference strategy.
+- You define an inference strategy.
 - You want a repeatable aggregation method over model outputs.
 - You need benchmarked quality gains for a specific task family.
 - You want majority vote, quorum, weighting, or another formal decision rule.
 
 ## Choose Ennodia When
 
-- You want to run real local agent CLIs, not just raw model calls.
+- You want to run real local agent command-line interfaces (CLIs), not only raw
+  model calls.
 - You care about subprocess status, logs, failures, timeouts, and cancellation.
-- You want an agent to inspect candidate work and synthesize a result.
+- You want a Judge to inspect candidate work and a Result Advisor to recommend
+  a result.
 - You need practical local delegation more than a research-grade ensemble.
 
 ## Key Difference
 
-MoA and ensemble methods focus on output aggregation. Ennodia focuses on visible
-local agent orchestration, then uses model-led Compare when several answers are
-available.
+Mixture-of-Agents and ensemble methods focus on output aggregation. Ennodia
+focuses on visible local agent orchestration. It then uses model-led Compare
+when multiple answers are available.
 
 ## Common Mistake
 
-Do not describe Ennodia Compare as consensus. Compare judges and synthesizes
-outputs. It does not implement voting, quorum, or weighting rules.
+Do not describe Ennodia Compare as consensus. The Judge maps the candidate
+outputs, and the Result Advisor recommends an answer. It does not implement
+voting, quorum, or weighting rules.

package/docs/comparisons/model-merging.md

@@ -6,22 +6,24 @@ description: How Ennodia differs from model merging tools such as mergekit and o
 Model merging combines model weights or checkpoints into a new model artifact.
 [mergekit](https://github.com/arcee-ai/mergekit) is a toolkit for merging
 pretrained language models, and the [MergeKit paper](https://aclanthology.org/2024.emnlp-industry.36/)
-describes it as tooling for model-checkpoint merging strategies.
+describes it as tools for model-checkpoint merging strategies.
 
-Ennodia does not touch model weights.
+Ennodia does not change model weights.
 
 ## Choose Model Merging When
 
 - You control compatible model weights.
 - You want one merged model artifact.
 - You want changes to happen before inference.
-- You are evaluating merge recipes, checkpoints, or open-weight model behavior.
+- You evaluate merge recipes, checkpoints, or open-weight model behavior.
 
 ## Choose Ennodia When
 
 - You want separate agents to run at task time.
-- You want to keep provider subscriptions and installed CLIs separate.
-- You want traces, child task IDs, failure states, and Compare output.
+- You want to keep provider subscriptions and installed command-line interfaces
+  (CLIs) separate.
+- You want traces, child task identifiers (IDs), failure states, and Compare
+  output.
 - You do not want to produce or host a new model artifact.
 
 ## Key Difference

package/docs/comparisons/openrouter.md

@@ -1,34 +1,44 @@
 ---
 title: Ennodia vs OpenRouter
-description: How Ennodia differs from OpenRouter and other hosted multi-model API routers.
+description: How Ennodia differs from OpenRouter and other hosted multi-model application programming interface (API) routers.
 ---
 
-[OpenRouter](https://openrouter.ai/docs/quickstart) provides a unified hosted
-API for accessing many AI models through one endpoint. Its routing docs cover
-provider selection, model fallback, pricing, and other hosted API concerns.
+[OpenRouter](https://openrouter.ai/docs/quickstart) provides one hosted
+application programming interface (API). It gives access to many artificial
+intelligence (AI) models through one endpoint.
 
-Ennodia is not that. Current Ennodia releases do not sell hosted model access or
-abstract provider billing.
+Its routing documentation covers provider selection, model fallback, pricing,
+and other hosted API concerns.
 
-Ennodia IO exposes a small local HTTP interface for app-facing calls. It is
-still different from OpenRouter: Ennodia delegates to installed local agents
-rather than sell hosted model access or proxy provider billing.
+Ennodia is not a hosted multi-model API. Current Ennodia releases do not sell
+hosted model access or abstract provider billing.
+
+Ennodia IO exposes a small local Hypertext Transfer Protocol (HTTP) interface
+for app calls. It is still different from OpenRouter. Ennodia delegates to
+installed local agents.
+
+Ennodia does not sell hosted model access or proxy provider billing.
 
 ## Choose OpenRouter When
 
 - You want one hosted API for many models.
 - You want provider routing, fallback, and pricing controls behind one endpoint.
-- Your application code needs direct model responses, not local agent CLI runs.
-- You want to centralize hosted model access outside a local desktop agent setup.
+- Your application code needs direct model responses, not local agent
+  command-line interface (CLI) runs.
+- You want centralized hosted model access outside a local desktop agent installation.
 
 ## Choose Ennodia When
 
-- Your primary agent is already working in an MCP client.
-- You want that agent to ask installed local agent CLIs for help.
-- You want child task IDs, output previews, failures, ETA, and run history.
-- You want budget estimates and local limits before launching child tasks.
-- You want a model to compare agent answers instead of manually reading every
-  response yourself.
+- Your primary agent has a task in a Model Context Protocol (MCP) client.
+- You want that agent to request help from installed local agent command-line
+  interfaces (CLIs).
+- You want child task identifiers (IDs), output previews, failures, estimated
+  completion time, and run history.
+- You want budget estimates and local limits before child tasks start.
+- You want a Judge to map agent answers and a Result Advisor to recommend an
+  answer. You do not want to read each response.
+- You want an optional Plan Advisor to suggest a bounded local team without
+  automatic execution. Plan Advisor cannot start the proposal.
 - You want a local HTTP bridge over those same agent runs.
 
 ## Key Difference
@@ -36,12 +46,10 @@ rather than sell hosted model access or proxy provider billing.
 OpenRouter routes hosted model API calls. Ennodia coordinates local agent
 subprocesses and can expose that local orchestration through MCP or IO.
 
-That means OpenRouter is closer to infrastructure for application developers,
-while Ennodia is closer to a local collaboration tool for agents already inside
-your coding or research workflow.
+OpenRouter provides infrastructure for application developers. Ennodia is a
+local collaboration tool for agents in a code or research workflow.
 
 ## Common Mistake
 
 Do not describe Ennodia as a cheaper OpenRouter or an OpenRouter replacement.
-It solves a different problem: visible delegation to local agents you already
-have installed.
+It solves a different problem: visible delegation to installed local agents.

package/docs/concepts/compositional-audits.md

@@ -1,6 +1,6 @@
 ---
 title: Compositional Audits
-description: Split large reviews into focused slices, route them to local agents, and synthesize the results without losing traceability.
+description: Split large reviews into focused slices, route them to local agents, and combine the results without losing traceability.
 ---
 
 Large reviews work better when each agent gets a small, explicit slice. Ennodia
@@ -10,7 +10,7 @@ consistent rubric.
 
 ## When To Use It
 
-Use a compositional audit when the request mixes several risk types, such as:
+Use a compositional audit when the request mixes multiple risk types, such as:
 
 - product positioning and implementation architecture
 - website copy and protocol compatibility
@@ -18,17 +18,17 @@ Use a compositional audit when the request mixes several risk types, such as:
 - release readiness and future roadmap
 
 One broad prompt can make every reviewer repeat the same surface-level answer.
-Slices make each response easier to verify and easier to synthesize.
+Slices make each response easier to verify and combine.
 
 ## Good Slice Shape
 
 A useful slice includes:
 
 - one narrow question
-- the files or sources the reviewer should inspect
+- the files or sources for the reviewer to inspect
 - the harness or model to use, when that matters
 - the maximum answer length
-- the output shape expected by the synthesis pass
+- the output shape expected by the Result Advisor pass
 
 Example slice prompt:
 
@@ -71,7 +71,7 @@ Estimate the slice fan-out before starting child agents:
 {
   "tool": "ennodia_estimate_compositional_budget",
   "arguments": {
-    "prompt": "Synthesize these audit shards into the smallest safe next action.",
+    "prompt": "Combine these audit shards into the smallest safe next action.",
     "slices": [
       {
         "id": "docs-truth",
@@ -100,7 +100,7 @@ Then start the focused tasks:
 {
   "tool": "ennodia_start_compositional",
   "arguments": {
-    "prompt": "Synthesize these audit shards into the smallest safe next action.",
+    "prompt": "Combine these audit shards into the smallest safe next action.",
     "slices": [
       {
         "id": "docs-truth",
@@ -130,7 +130,7 @@ Each slice starts one task. Poll the returned task IDs with
 {
   "tool": "ennodia_get_compositional_status",
   "arguments": {
-    "prompt": "Synthesize these compositional audit shards into the smallest safe next action. Preserve disagreements and ignore non-signal shards.",
+    "prompt": "Combine these compositional audit shards into the smallest safe next action. Preserve disagreements and ignore non-signal shards.",
     "taskIds": ["task-id-1", "task-id-2", "task-id-3"]
   }
 }
@@ -143,7 +143,7 @@ When `compareReady` is true, pass the returned `readyTaskIds` to
 {
   "tool": "ennodia_start_compare",
   "arguments": {
-    "prompt": "Synthesize these compositional audit shards into the smallest safe next action. Preserve disagreements and ignore non-signal shards.",
+    "prompt": "Combine these compositional audit shards into the smallest safe next action. Preserve disagreements and ignore non-signal shards.",
     "taskIds": ["task-id-1", "task-id-2", "task-id-3"],
     "maxOutputChars": 12000
   }
@@ -155,13 +155,16 @@ When `compareReady` is true, pass the returned `readyTaskIds` to
 - Do not send the entire plan to every shard if the goal is faster, deeper review.
 - Do not mix unrelated evidence in one slice.
 - Do not treat failed, empty, or access-limited shard output as a normal review.
-- Do not claim that a synthesis is consensus when the shards disagree.
+- Do not claim consensus when the slices disagree.
 
 ## Current Boundary
 
 `ennodia_estimate_compositional_budget` resolves and budgets slices without
 starting child agents. `ennodia_start_compositional` starts and budgets the shard
 tasks. `ennodia_get_compositional_status` groups shard task states and identifies
-Compare-ready outputs. Synthesis stays explicit through `ennodia_start_compare`
-so long-running shard status, failed shards, and the final Compare step remain
-visible to the primary agent.
+Compare-ready outputs. The final recommendation stays explicit through
+`ennodia_start_compare`. This keeps task status, failed slices, and the final
+Compare step visible to the primary agent.
+
+During Compare, the Judge maps agreements and conflicts. The Result Advisor then
+recommends an answer.

package/docs/concepts/data-governance.md

@@ -10,20 +10,36 @@ configuration, subscriptions, and policies.
 
 ## What Ennodia Stores
 
-Live process state is held in memory while the server runs: run status, task
-IDs, command summaries, stdout/stderr captures, failures, timing, budget
-estimates, Compare analysis, and final answers.
+Live process state is held in memory while the server runs. It includes run
+status, task IDs, command summaries, stdout/stderr captures, failures, timing,
+and budget estimates. It also includes Plan Advisor proposals and validation
+state, Compare analysis, and final answers.
+
+When `isolateCwd` is enabled, Ennodia copies the requested working directory
+to an ephemeral operating-system temporary directory so concurrent workers do
+not overwrite one another. The copy excludes `.git` and `node_modules`, but it
+can include other ignored files and local secrets present in the working
+directory. Ennodia deletes this scratch copy after the task becomes terminal
+and retries cleanup during task pruning and graceful shutdown. The task's
+reported `cwd` remains an execution trace, not a persistent artifact path.
+
+After excluding `.git` and `node_modules` by name, isolation rejects any
+symbolic link in the remaining tree before spawning the task. This fail-closed
+rule prevents an isolated worker from following an absolute or parent-relative
+link back outside its scratch directory.
+An abrupt process or machine termination can still leave operating-system
+temporary files behind.
 
 Terminal run history is stored under `~/.ennodia/history/runs.jsonl` by default.
-Each snapshot contains the terminal run view (final answer capped at 80,000
-characters), task views with output capped at 20,000 characters per stream and
-the 50 most recent events, and Compare analysis/synthesis when Compare ran. It
-does not persist environment variables, provider credentials, or raw process
-environments.
+Each snapshot contains the terminal run view and bounded task views. The final
+answer is capped at 80,000 characters. Each task stream is capped at 20,000
+characters. Each snapshot keeps the 50 most recent events and Judge/Result
+Advisor output when Compare ran. It does not persist Plan Advisor requests,
+environment variables, provider credentials, or raw process environments.
 
-History writes are append-only with periodic compaction to the most recent 500
-runs. An interrupted write can lose at most the snapshot being written, never
-previously recorded history.
+History writes use an append-only hot path. Periodic compaction keeps the most
+recent 500 runs. An interrupted append can lose its current snapshot.
+A concurrent append in the short compaction window can also be lost.
 
 Set `ENNODIA_HISTORY=0` to disable durable history. Set
 `ENNODIA_HISTORY_DIR=/path/to/dir` to move the history file.
@@ -48,7 +64,7 @@ model text and environment metadata.
 
 ## Practical Guidance
 
-Use Ennodia for work you are already willing to send to the selected local agent
-CLIs. Use `cwd` deliberately, prefer short staged case files over broad prompts,
-and inspect `ennodia_list_harnesses` before sensitive work so the active local
-tools are clear.
+Use Ennodia for work that you are willing to send to the selected local agent
+CLIs. Use `cwd` deliberately. Prefer short staged case files over broad prompts.
+Inspect `ennodia_list_harnesses` before sensitive work so the active local tools
+are clear.