ennodia 0.2.0 → 0.3.0-rc.2

package/docs/guides/agent-skills.md

@@ -3,14 +3,15 @@ title: Agent Skills
 description: Install bundled Ennodia skills in native harness locations and tell child agents to use them during a run.
 ---
 
-Ennodia uses native Agent Skills. A skill is a folder that contains `SKILL.md`.
-Install it where each harness can find skills.
+A new Agent Skill can help a task, add irrelevant advice, or make no difference.
+Try the skill in a separate Ennodia task and bring useful findings back to your main conversation.
 
-Ennodia does not use a private skill format. It does not put the full skill
-instructions in each delegated prompt.
+A skill is a folder containing `SKILL.md` in a native agent location.
+Ennodia discovers that folder and requests the selected skill by name.
+It does not inline the full instructions into each delegated prompt.
 
-Ennodia installs or discovers the native skill folder. It then passes the
-selected `skillIds` into the run.
+The primary agent can keep useful partial findings without adopting every recommendation.
+The [skill trial example](/docs/evidence/skill-trial/) shows a controlled small exercise.
 
 ## List Available Skills
 
@@ -53,8 +54,10 @@ Review the planned paths. If they are correct, repeat with `dryRun: false`.
   "tool": "ennodia_run",
   "arguments": {
     "prompt": "Audit this documentation against the linked sources and recommend exact edits.",
-    "mode": "parallel",
-    "compare": true,
+    "harnessId": "codex",
+    "mode": "single",
+    "compare": false,
+    "cwd": "/absolute/path/to/project",
     "skillIds": ["source-grounded-audit"]
   }
 }
@@ -63,6 +66,11 @@ Review the planned paths. If they are correct, repeat with `dryRun: false`.
 Task and run views include selected skill metadata in `appliedSkills`, so the
 primary agent can see which skills were requested.
 
+Native agents can self-select other skills from their environment.
+An empty requested skill list does not guarantee a skill-free control.
+`appliedSkills` records the request, not verified execution of the skill’s instructions.
+A permission denial can prevent the worker from loading the skill.
+
 Bundled skills include:
 
 | Skill | Use it for |
@@ -84,3 +92,9 @@ Bundled skills include:
 
 See [Model Context Protocol (MCP) Tools](/docs/reference/mcp-tools/) for the
 exact tool parameters.
+
+## Main-agent delegation skill
+
+The bundled `pragmatic` skill guides the main agent through bounded delegation and result verification.
+Install it using `skillIds: ["pragmatic"]`. Do not pass it to workers through run `skillIds`.
+See [Pragmatic mode](/docs/guides/pragmatic-mode/) for the experimental recipes.

package/docs/guides/budgets-and-limits.md

@@ -95,7 +95,7 @@ supported quota surface.
 
 ## Practical Defaults
 
-- For a first documentation or code audit, start with two or three harnesses.
+- Start with one agent and a narrow task. Add attempts when they address a specific uncertainty.
 - Use `maxOutputChars` to keep Compare input bounded.
 - Keep `maxChildTasks` set when the prompt may route to many adapters.
 - Treat unknown subscription-limit status as a transparency signal, not proof

package/docs/guides/pragmatic-mode.md

@@ -0,0 +1,85 @@
+---
+title: Pragmatic mode
+description: Delegate bounded investigation and patch proposals to one explicitly selected model.
+---
+
+Pragmatic mode is experimental in `0.3.0-rc.2`, available through `ennodia@next`.
+It helps your main agent delegate bounded work without loading entire logs or files into the main conversation.
+It does not guarantee lower costs or select the cheapest model automatically.
+
+## Start a bounded task
+
+Use this prompt in your main agent:
+
+```text
+Use Ennodia MCP in Pragmatic mode to investigate the failing requests in /absolute/path/to/server.log.
+Select a supported lower-cost model from my configured harnesses.
+Return the affected timestamps, exact errors, likely cause, and evidence locations.
+Keep the full log outside this conversation. Verify the decisive evidence before recommending a fix.
+```
+
+The main agent can call the existing run tool:
+
+```json
+{
+  "tool": "ennodia_run",
+  "arguments": {
+    "harnessId": "claude-code",
+    "model": "<supported-model-from-your-configuration>",
+    "cwd": "/absolute/path/to/project",
+    "prompt": "Find the cause of failed requests in /absolute/path/to/server.log between 10:00 and 10:10. Do not modify files.",
+    "pragmatic": {
+      "recipe": "investigate",
+      "acceptanceCriteria": "Cite exact errors and timestamps. Distinguish confirmed causes from hypotheses. Report any unread ranges."
+    },
+    "timeoutMs": 120000,
+    "budget": { "maxChildTasks": 1 }
+  }
+}
+```
+
+Replace the model placeholder with a supported identifier before calling the tool.
+The caller supplies both `harnessId` and `model`.
+The run uses `mode: single` and `compare: false`, including when these fields are omitted or set to `auto`.
+Explicit parallel execution or comparison is rejected before workers start.
+
+## Get findings or a patch
+
+| Recipe | Worker instruction | Main agent responsibility |
+| --- | --- | --- |
+| `investigate` | Return cited findings, small excerpts, coverage limits, and unresolved questions | Verify decisive evidence |
+| `patch` | Return a complete unified diff proposal without applying it | Review, apply, and test the patch |
+
+Both recipes instruct workers to avoid file changes, side effects, recursive delegation, and repeated failed approaches.
+These are worker instructions, not an enforced permission sandbox.
+Native harness permissions remain authoritative.
+A worker can fail to follow instructions, so use appropriate native permissions for sensitive work.
+
+Patch results distinguish executed checks from proposed checks.
+Check `finalAnswerChars` and request a larger answer if the response was truncated.
+Do not apply an incomplete diff.
+Patch runs fail when the child answer was truncated before reaching the run. Submit a smaller assignment in that case.
+
+For authorized file edits, use a normal run in a separate checkout with appropriate native permissions.
+The experimental recipes do not grant edit permissions.
+Temporary `isolateCwd` copies are deleted when tasks finish and cannot serve as persistent patch artifacts.
+
+## Inspect the work
+
+Use `ennodia_get_run` for status, requested `model`, `pragmatic` settings, elapsed time, events, and child task IDs.
+Inspect child tasks for output and adapter-reported usage when available.
+Missing usage is unknown, not zero.
+Persisted run records are bounded and can omit output.
+
+Use `ennodia_estimate_budget` with the same `pragmatic` settings and model to include worker instructions in the preflight estimate.
+Estimates do not measure total task spend, internal tool reads, or subscription quota consumption.
+
+The foundation does not retry automatically or track retries across separate runs.
+Escalate unresolved work in a separate run after inspecting its evidence.
+Compare total elapsed time, verified outcomes, and all reported usage across attempts before claiming savings.
+
+## Install the main-agent skill
+
+The bundled `pragmatic` skill guides delegation from your main conversation.
+Install it through [Agent Skills](/docs/guides/agent-skills/) using `skillIds: ["pragmatic"]`.
+Do not request this skill on workers through run `skillIds`.

package/docs/guides/recipes.md

@@ -0,0 +1,56 @@
+---
+title: Recipes
+description: Three small ways to get useful help from Ennodia.
+---
+
+# Start with one useful attempt
+
+A focused request is easier to check and integrate.
+Give your primary agent the relevant files, attempted fixes, and the result you need.
+
+## A task is stuck
+
+```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 concrete check for it.
+Keep the review read-only and return the findings here.
+```
+
+A useful result names a different hypothesis and a way to test it.
+Repeating the same suggestion is a result to record, not a reason to restart the whole conversation.
+
+## A skill might help
+
+```text
+Use Ennodia MCP to try an installed review skill on this change in a separate task.
+Keep the review read-only. Bring back useful findings and unsupported suggestions.
+Show which skill and model were requested and what remains unverified.
+```
+
+Check native installation with your agent before the task starts.
+A requested skill is not proof that the worker loaded it.
+Use the [small skill trial](/docs/evidence/skill-trial/) to practice comparing two attempts.
+
+## Two answers disagree
+
+```text
+Use Ennodia MCP to compare these two answers.
+Identify the assumption behind each disagreement and the evidence for each side.
+Recommend the smallest check that can settle it.
+Keep useful partial findings even if neither answer solves the whole task.
+```
+
+Compare adds a Judge pass and a Result Advisor pass.
+Use it when those additional checks are useful for your next decision.
+Your primary agent can directly inspect one short worker answer without Compare.
+
+## Agent implementation notes
+
+`ennodia_run` starts a tracked run. For one explicit attempt, use `mode: "single"`, a discovered `harnessId`, and `compare: false`.
+Use `ennodia_get_run` to inspect the result.
+The [tool reference](/docs/reference/mcp-tools/) contains exact parameters.
+
+For independent work on the same files, use separate checkouts or `isolateCwd: true`.
+Ennodia refuses symbolic links in copied directories. It deletes each temporary copy when the task ends.
+Save required changes before relying on a temporary directory as an output artifact.

package/docs/guides/troubleshooting.md

@@ -0,0 +1,48 @@
+---
+title: Troubleshooting
+description: Resolve failed starts without confusing configuration errors with model quality.
+---
+
+# When an attempt cannot finish
+
+Start with the task’s failure reason and captured output.
+Use `ennodia_get_task` for details and `ennodia_list_harnesses` to inspect supported commands.
+
+## The agent is listed, but cannot run the task
+
+Discovery establishes command availability. It does not establish login state, available models, or remaining provider quota.
+Run a small task to check the selected configuration.
+
+For an expired login, sign in through the affected agent’s supported command-line interface (CLI).
+For an unavailable model, check that agent’s model list and configured provider.
+Do not interpret either failure as evidence that the model could not solve the task.
+
+## The worker cannot read or edit
+
+Codex workers use a read-only sandbox by default.
+Other agents retain their native permission rules.
+Non-interactive agents can deny operations that require an interactive permission prompt.
+
+Use accessible source material and the agent’s normal permission configuration.
+Request a proposed patch when direct editing is unavailable.
+Do not disable permission checks to make an example appear successful.
+
+## Isolation rejects a symbolic link
+
+`isolateCwd: true` copies a working directory and rejects symbolic links before launch.
+Use a small self-contained fixture or an explicit separate checkout when the project contains such links.
+Ennodia deletes its temporary copied directory after the task ends.
+Use a persistent separate checkout for implementation work that you need to integrate.
+
+## A task reaches its timeout
+
+Inspect the partial output first. It can contain useful findings or only setup activity.
+Narrow the next request or change its execution configuration when appropriate.
+More time is useful only when the progress supports that choice.
+Cancel unwanted tasks explicitly with `ennodia_cancel_task` or `ennodia_cancel_run`.
+
+## A skill was requested but did not load
+
+Check `ennodia_list_skills` for the selected agent’s native installation.
+Then inspect the worker’s tool access and output.
+The `appliedSkills` field records the request. It does not independently verify every action inside the worker.

package/docs/guides/understand-results.md

@@ -0,0 +1,41 @@
+---
+title: Understand results
+description: Distinguish useful findings, disagreement, missing evidence, and failed execution.
+---
+
+# Understand the result
+
+Process completion is one signal. A useful answer also needs evidence that fits your task.
+
+| Result | Meaning | Next step |
+| --- | --- | --- |
+| Useful finding | A concrete claim, correction, or test you can examine. | Verify it and integrate the useful part. |
+| Disagreement | Different assumptions or conclusions remain. | Check the evidence that can distinguish them. |
+| Unhelpful answer | The attempt ran but did not move the task forward. | Record the conditions and change the approach. |
+| Failed login or unavailable model | The requested model could not be evaluated. | Repair access or select another available configuration. |
+| Timeout | The attempt did not finish within its limit. | Inspect progress before narrowing or repeating it. |
+| Missing tool permission | The worker could not perform a required operation. | Review normal tool permissions or provide accessible material. |
+
+An unsuccessful attempt does not prove that every model would fail.
+It can remove the need to repeat that same attempt under the same conditions.
+
+## Compare is advice
+
+Compare uses a Judge to examine answers and a Result Advisor to recommend a next answer.
+Agreement is not proof of correctness.
+The primary agent still checks code, sources, tests, and important assumptions.
+
+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.
+
+## Read the attempt record
+
+Task records include the selected agent, requested skills, status, elapsed time, and bounded output.
+Run history preserves terminal run snapshots locally.
+It does not yet learn which model or skill to choose next.
+
+`remainingMs` with `etaConfidence: "timeout-budget"` reports time left before the deadline.
+It is not a prediction of model completion time.
+Input-token estimates also exclude work inside the agent.
+Unknown provider usage must remain unknown.

package/docs/index.md

@@ -1,104 +1,41 @@
 ---
 title: What is Ennodia?
-description: Start here to understand Ennodia, select an installation path, and find the documentation page for your task.
+description: Try other agents, models, and skills while staying in your familiar conversation.
 ---
 
-Ennodia is a local Model Context Protocol (MCP) server for multi-agent review.
-Your primary artificial intelligence (AI) agent can request help from installed
-agent command-line interfaces (CLIs).
+# Keep your agent. Get another way forward.
 
-The primary agent can inspect the work. It can use a Judge and Result Advisor to
-compare the answers.
+Ennodia lets your primary artificial intelligence (AI) agent try another agent, model, or skill on a focused task.
+The findings return to your existing conversation.
 
-An optional Plan Advisor can first propose a bounded team. It cannot execute the
-proposal.
+You can explore another explanation for a bug, test a skill, or examine conflicting advice.
+Your primary agent keeps responsibility for checking and integrating the result.
+Even an unsuccessful attempt can show which approach was tested under the recorded conditions.
 
-Use Ennodia when one agent has a task that needs additional review, a plan, a
-diagnosis, or a comparison. A run usually takes minutes.
+## Start here
 
-Compare adds a serial Judge pass and a serial Result Advisor pass after the
-child agents finish.
+- [Get your first result](/docs/getting-started/).
+- [Choose a recipe](/docs/guides/recipes/).
+- [Understand the result](/docs/guides/understand-results/).
+- [Read a development case](/docs/evidence/building-ennodia/).
 
-## The Problem Ennodia Solves
+## Your existing tools
 
-Single-model judgment can be a single point of failure. One agent can miss a
-risky bug, accept a weak plan, or report false confidence.
+Ennodia runs as a local Model Context Protocol (MCP) server.
+It connects to supported installed agents through their public command-line interfaces (CLIs).
+Your configured providers supply the models. Existing subscriptions, usage limits, and permissions still apply.
 
-Important work can require independent second opinions and a record of each
-reviewer's work.
+Ennodia discovers native Agent Skills and can request a skill for a separate task.
+A native agent can also choose unrequested skills from its environment.
 
-Many developers have independent agent subscriptions. Examples include Codex,
-Claude Code, Antigravity, and OpenCode. Ennodia makes their installed CLIs a
-review panel for the primary agent.
+## Learn more
 
-This process does not require new accounts or a vendor migration. It does not
-require new application programming interface (API) keys.
+- [Agent skills](/docs/guides/agent-skills/)
+- [Troubleshooting](/docs/guides/troubleshooting/)
+- [Data movement and history](/docs/concepts/data-governance/)
+- [Examples and evidence](/docs/evidence/)
+- [Roadmap](/docs/roadmap/)
+- [Technical reference](/docs/reference/mcp-tools/)
 
-- Agents reach Ennodia through MCP, a protocol that the agents support.
-- A Plan Advisor can propose inert harness, model, and skill assignments. A
-  separate explicit call must launch the validated plan.
-- Model-led Compare uses a Judge for the disagreement map and a Result Advisor
-  for the recommended answer.
-- One shared core discovers harnesses, plans routes, checks local preflight
-  limits, tracks tasks, and keeps the trace visible.
-- The separate Ennodia IO package is an experimental appendix for apps.
-
-## Why People Use It
-
-Ennodia:
-
-- discovers supported local harnesses automatically
-- uses your installed CLIs, subscriptions, and model choices
-- estimates preflight input-token budgets and enforces local caps on that
-  estimate
-- keeps child task identifiers (IDs), status, estimated completion time,
-  output, failures, Compare state, and run
-  history visible
-- can retain terminal receipts across server restarts
-- lets a Judge inspect parallel answers and a Result Advisor combine the
-  findings
-- uses native Agent Skills through harness-visible `SKILL.md` folders
-
-Durable model and skill preference memory is roadmap work. By default, Ennodia
-stores terminal run history under `~/.ennodia/history/`. Live in-progress state
-remains process-local.
-
-## Choose Your Path
-
-| Task | Page |
-| --- | --- |
-| Request Ennodia installation from an agent | [Installation for Agents](./install/) |
-| Install it manually or work from a checkout | [Quickstart](./getting-started/) |
-| Estimate or limit a costly run | [Budgets and Limits](./guides/budgets-and-limits/) |
-| Install or use `source-grounded-audit` and other skills | [Agent Skills](./guides/agent-skills/) |
-| Understand the run lifecycle | [How Ennodia Works](./concepts/how-ennodia-works/) |
-| Request a bounded team proposal before work | [How Ennodia Works](./concepts/how-ennodia-works/#plan-advisor) |
-| Use panels for second opinions | [Second Opinions as Infrastructure](./concepts/second-opinions/) |
-| Understand local storage and data movement | [Data Governance](./concepts/data-governance/) |
-| Understand Core, <span class="agent-logo agent-logo--mcp" aria-hidden="true"></span>MCP, and experimental IO | [Interfaces and Core](./concepts/interfaces-and-core/) |
-| Split a large review into smaller shards | [Compositional Audits](./concepts/compositional-audits/) |
-| Call the exact <span class="agent-logo agent-logo--mcp" aria-hidden="true"></span>MCP tools | [MCP Tools](./reference/mcp-tools/) |
-| Call Ennodia from a local web app | [Ennodia IO](./reference/ennodia-io/) |
-| Check harness identifiers and installation notes | [Supported Harnesses](./reference/supported-harnesses/) |
-| Use the ASD-STE100 rules and approved Ennodia terms | [Controlled English](./reference/controlled-english/) |
-| Inspect benchmark receipts | [Benchmarks](./reference/benchmarks/) |
-| Decide if Ennodia fits your workflow | [Comparisons](./comparisons/) |
-| Get better output from model-led Compare | [Better Audits](./guides/running-better-audits/) |
-
-## First Useful Run
-
-1. Install Ennodia in your MCP client.
-2. Call `ennodia_list_harnesses`.
-3. Call `ennodia_estimate_budget` for the task.
-4. Start `ennodia_run`.
-5. Poll `ennodia_get_run` until it reaches `succeeded`, `failed`, or
-   `cancelled`.
-
-The user does not normally need to grade each child answer. The trace remains
-available for inspection.
-
-For a team proposal, call `ennodia_start_plan_advice`. Then poll
-`ennodia_get_plan_advice`. A ready result is only validated data.
-
-Call `ennodia_start_advised_plan` with the returned plan digest once to start the
-work.
+General speed or token savings have not been established.
+The examples distinguish useful contributions, incomplete attempts, and technical failures.

package/docs/install.md

@@ -3,8 +3,9 @@ title: Installation for Agents
 description: A copy-paste installation page for agents that install Ennodia in Codex, Claude Code, OpenCode, Antigravity, and other Model Context Protocol (MCP) clients.
 ---
 
-This page is for the agent that does the installation. Install Ennodia as a local Model
-Context Protocol (MCP) server. Then enable it in the user's MCP client.
+This page gives setup instructions to the user's agent.
+Install Ennodia as a local Model Context Protocol (MCP) server.
+Then connect it to the user's preferred compatible client.
 
 ## Copy-Paste Prompt
 
@@ -12,6 +13,24 @@ Context Protocol (MCP) server. Then enable it in the user's MCP client.
 try-ennodia.cherninlab.com
 ```
 
+The user can send this address in a new or existing agent conversation.
+The agent handles the setup steps below.
+
+## Check the Environment
+
+1. Identify the user's client and the machine where Ennodia will run.
+2. Check that the client can launch a local standard input/output (stdio) MCP server.
+3. Check for Bun `1.3.14` or newer in that environment.
+4. Check for a supported agent command-line interface (CLI) with working provider access.
+
+Use the client's supported configuration method and the tools' official installation instructions.
+Preserve existing server entries and unrelated settings.
+Use the client's normal permissions.
+
+If the current client cannot launch a local MCP server, explain the missing capability.
+Use a compatible local client for Ennodia.
+See [Supported Harnesses](/docs/reference/supported-harnesses/) for the worker agents Ennodia can call.
+
 ## Install Command
 
 Use the npm package for normal MCP client installation:
@@ -51,24 +70,38 @@ For a local Ennodia checkout, use:
 }
 ```
 
-## First Agent Checks
+The configuration above shows the server command and arguments.
+Adapt its format to the client's documented configuration method.
+Reload the tools or restart the client only when its setup instructions require this step.
+Tell the user which step is needed before trying to call Ennodia.
+
+## Get One Useful Result
+
+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.
+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`.
+6. Report the useful finding or the specific failure in the user's conversation.
 
-After MCP configuration, call these tools:
+For example, request a read-only check of one function or one documentation claim against its source.
+Include the relevant files or task details in the worker prompt.
+Request evidence the main agent can inspect.
 
-1. `ennodia_list_harnesses`
-2. `ennodia_estimate_budget`
-3. `ennodia_plan`
-4. `ennodia_run`
-5. `ennodia_get_run`
+Discovery checks installed commands, not active authentication, model access, or provider quota.
+A successful small run verifies the selected worker's configuration.
+If provider access is missing, identify the affected worker and its normal login or configuration step.
 
-`ennodia_list_harnesses` shows the available local tools. See the current
-adapter list and identifiers (IDs) in
-[Supported Harnesses](/docs/reference/supported-harnesses/).
+The first run does not require separate planning, budget estimation, or Compare calls.
+These tools remain available for larger tasks.
+See [MCP Tools](/docs/reference/mcp-tools/) for exact parameters and identifiers (IDs).
 
 ## Installed Components
 
 Ennodia is a local MCP server. It lets the user's main agent request help from
-other installed agent command-line interface (CLI) programs during the same task.
+other installed agent CLI programs during the same task.
 
 The number of agents is not the primary benefit. Ennodia uses current local
 installs, subscriptions, and model choices. It discovers supported CLI programs and
@@ -96,18 +129,18 @@ Use Ennodia when the user permits more model work to get a better answer than
 one agent usually gives.
 
 ```text
-Use Ennodia to request a review from multiple available agents.
+Use Ennodia MCP to request a review from multiple available agents.
 Compare the answers for this bug fix.
 Name the disagreements and return the highest-risk issue first.
 ```
 
 ```text
-Use Ennodia to plan this migration with Claude Code, OpenCode, and Antigravity.
+Use Ennodia MCP to plan this migration with Claude Code, OpenCode, and Antigravity.
 Compare the plans and tell me which assumptions each model made.
 ```
 
 ```text
-Use Ennodia twice.
+Use Ennodia MCP twice.
 Use source-grounded-audit for the first run, but not for the second run.
 Compare the results before you recommend the final documentation edit.
 ```

package/docs/reference/controlled-english.md

@@ -25,8 +25,8 @@ Keep this data exact, even when its text does not use controlled English.
 - Define a necessary abbreviation at its first use on each independent page.
 - Preserve exact product names, commands, paths, model IDs, and API fields.
 
-The landing page uses `AI makes mistakes` as an approved fixed tagline.
-Define `artificial intelligence (AI)` in the sentence directly below it.
+Marketing headlines can change with the product positioning.
+Keep supporting copy concrete and consistent with current product behavior.
 
 Automated checks can find some defects, but they cannot certify compliance.
 A human reviewer must confirm meaning, grammar, and correct technical use.
@@ -40,7 +40,6 @@ Use the listed meaning and part of speech.
 | --- | --- | --- |
 | Ennodia | technical noun | The software product in this repository. |
 | artificial intelligence (AI) | technical noun | Software that produces or evaluates model output. |
-| AI makes mistakes | approved tagline | The exact Ennodia landing-page headline. Keep this phrase unchanged. |
 | Model Context Protocol (MCP) | technical noun | The protocol that exposes Ennodia tools to a compatible client. |
 | command-line interface (CLI) | technical noun | A text interface that accepts commands. |
 | application programming interface (API) | technical noun | A defined interface that software uses to exchange data. |

package/docs/reference/ennodia-io.md

@@ -62,8 +62,25 @@ Environment variables:
 IO binds to loopback by default and refuses non-loopback hosts unless an API key
 is configured. Bearer tokens are compared with a timing-safe comparison.
 
+IO checks the `Host` header on every route. In the default loopback posture,
+the host must be `localhost`, `::1`, or an address in `127.0.0.0/8`. A forged
+`Host` header, such as one from Domain Name System (DNS) rebinding, gets a
+`403 invalid_host` error. An explicit non-loopback `--host` turns off this
+allowlist and requires the API key.
+
+IO checks the `Origin` header when a request carries one. Only loopback origins
+are accepted. A browser post from a non-loopback origin gets a `403 invalid_origin`
+error before any run starts. Clients that send no `Origin` header, such as
+local command-line tools, keep working.
+
+`POST /v1/chat/completions` requires a JSON media type such as
+`application/json`. Other media types get a `415 unsupported_media_type` error.
+This requirement stops simple-request browser posts, for example cross-site
+forms that send `text/plain`.
+
 IO intentionally sends no Cross-Origin Resource Sharing (CORS) headers by
-default. The browser blocks local apps unless they use their own local proxy.
+default. Browsers cannot read cross-origin responses or send cross-origin JSON posts
+unless their app uses an appropriate same-origin proxy.
 There is no `--cors-origin` flag. Add one only when an app needs that trust
 boundary.
 
@@ -75,7 +92,7 @@ boundary.
 | `GET /v1/provider-options` | Supported | Returns app-facing local provider options for settings screens. |
 | `GET /v1/byok-options` | Supported alias | Same response as provider options. |
 | `GET /v1/models` | Supported | Returns local virtual model IDs for compatible clients. |
-| `POST /v1/chat/completions` | Supported subset | Non-streaming text messages only. |
+| `POST /v1/chat/completions` | Supported subset | Non-streaming text messages only. Requires a JSON media type. |
 
 ## Provider Options
 
@@ -202,9 +219,15 @@ The response includes the normal OpenAI-style `choices[0].message.content` plus
 an `ennodia` object. The object contains the run ID, status, selected harnesses,
 task IDs, Compare ID when present, and budget estimate.
 
-Limits and failures are returned as JSON with `cache-control: no-store`:
+Handler errors use JSON with `cache-control: no-store`. The native server can
+reject a request before the handler runs, so clients must also handle an empty
+HTTP error response:
 
-- request body above the configured cap -> `413 request_too_large`
+- disallowed `Host` header or `Origin` header -> `403 invalid_host` or `403 invalid_origin`
+- non-JSON media type on chat completions -> `415 unsupported_media_type`
+- request body above the configured cap -> HTTP `413`. Bun can reject it with
+  an empty body before the handler runs. Requests rejected by the handler use
+  the JSON error `request_too_large`.
 - saturated chat completions -> `429 rate_limit_error` with `retry-after: 1`
 - client abort after the run starts -> `499 client_closed_request`. IO cancels
   the Ennodia run when Core exposes cancellation