ennodia 0.2.0 → 0.3.0

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

package/docs/reference/mcp-tools.md

@@ -40,6 +40,7 @@ as native Agent Skills: folders containing `SKILL.md`, installed in paths
 supported by each harness. It does not inline full skill content into the
 delegated prompt. Task and run views include selected skill metadata in
 `appliedSkills`.
+This metadata records the request. It does not prove that the native agent loaded or followed the skill.
 
 `ennodia_estimate_budget`, `ennodia_estimate_compositional_budget`,
 `ennodia_start`, `ennodia_run`, `ennodia_start_compare`,
@@ -50,6 +51,10 @@ tokens, cache behavior, harness-internal context, or private subscription quota.
 
 ### Routing hints
 
+Development versions of `ennodia_run` and `ennodia_start` accept optional `reasoningEffort` for Codex workers, forwarded through the native `model_reasoning_effort` configuration. Other adapters reject an explicit setting. Omission preserves native defaults. This field does not configure comparison agents.
+
+Task and run views record the requested value. Model and CLI support remain authoritative.
+
 Ennodia uses `category` before keyword classification. Valid categories are
 `code`, `research`, `browser`, `image`, and `general`. The fallback classifier
 uses strong browser, image, code, and research signals. Bare words such as
@@ -75,13 +80,51 @@ Fields named `maxOutputChars`, `maxAnswerChars`, or `maxCandidateChars` bound
 returned text. `0` omits that text while still returning status, IDs, timing,
 and character counts.
 
+For task views, `maxOutputChars` bounds each of `stdout`, `stderr`, and `finalMessage`.
+`includeOutput: false` omits their text. `hasOutput` and `finalMessageChars` remain available in compact views.
+`hasOutput` includes captured diagnostic output. It does not establish correctness or a useful answer.
+
+On macOS and Linux, tasks own process groups. Cancellation sends TERM, then KILL after a bounded grace period.
+Cleanup also removes descendants that remain in the owned group after the parent exits.
+Processes that create a separate session can escape that group.
+On Windows, cleanup signals the direct child process.
+Closing the MCP input stream shuts down active work.
+
+Raw and compositional batch starts cancel earlier workers if a later spawn fails.
+Active runs retain child evidence until comparison and receipt capture finish.
+
+### Media review
+
+Ennodia transports text prompts with local file paths. Native media inspection depends on the selected harness, model, available tools, and permissions.
+Discovery and Plan Advisor expose optional, bounded `inputGuidance: string[]` for adapter observations and input advice.
+This guidance does not guarantee successful ingestion or model access.
+
+Media prompts also receive preparation guidance at worker launch, recorded by an `input-guidance` task event.
+Budget estimates include this added prompt text.
+Automatic native-audio routes suggest one worker without comparison. Keyword routing does not verify the worker's native access.
+For Antigravity, see [supported harnesses](/docs/reference/supported-harnesses/#antigravity) for the text-only wire format and scoped native-media observations.
+
+1. Run a small native-media probe before launching a larger review or comparison.
+2. Include exact local files, requested ranges, and the reference in each worker prompt.
+3. Match excerpts, playback level, and reference material across audio candidates.
+4. Request the model, inspected files and ranges, native tool results, errors, and excerpt-specific findings.
+5. Retain task IDs and available terminal history receipts with the final assessment.
+
+Successful media ingestion and excerpt-specific observations support a native listening claim.
+Transcription, digital signal processing (DSP), and text-only judges provide separate evidence. Label each method and any fallback explicitly.
+A Judge's comparison of written reports does not establish that the Judge inspected the source media.
+Task output and history receipts are bounded. They do not provide complete transcripts or a permanent audit record.
+
 ## Discovery and planning
 
 ### `ennodia_list_harnesses`
 
 Detects supported local artificial intelligence (AI) tools and reports
 availability, runnable state, command path, version, capabilities, and adapter
-notes.
+notes. Optional `inputGuidance` contains a bounded string array of input advice and scoped observations.
+
+Version probes have bounded deadlines. A failed probe appears in adapter notes without blocking other discoveries.
+`runnable` means Ennodia found an executable adapter. Authentication and requested model access still require a real task.
 
 | Input | Default | Meaning |
 | --- | --- | --- |
@@ -150,6 +193,10 @@ limits. It can propose only explicit worker slices containing a prompt, harness,
 optional model, and skill IDs. It cannot choose `cwd`, environment variables,
 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.
+
 The lifecycle is deliberately two-phase: request and inspect advice first, then
 launch the exact validated plan in a separate call. Ennodia rejects invalid
 Plan Advisor output as a whole and revalidates the plan digest and current inventory
@@ -332,12 +379,13 @@ Poll it with
 
 ### `ennodia_get_run`
 
-Returns the current run state.
+Returns the current run state. Set `waitMs` to wait for completion without repeated immediate polls. A wait timeout leaves the run running.
 
 | Input | Default | Meaning |
 | --- | --- | --- |
 | `runId` | required | ID returned by `ennodia_run`. |
-| `includeEvents` | `true` | Include run event history. |
+| `waitMs` | `0` | Wait up to 300000 milliseconds for a terminal state. Does not cancel or extend the run. Longer waits require a client tool timeout greater than this value. |
+| `includeEvents` | `true` | Include run event history. Set false for compact waiting responses. |
 | `maxEvents` | `100` | Maximum run events to return. Capped at 300. |
 | `maxAnswerChars` | `80000` | Maximum final-answer characters. Capped at 200000. |
 
@@ -447,8 +495,8 @@ successful non-empty task IDs ready for a Judge + Result Advisor comparison.
 | `taskIds` | required | Shard task IDs returned by `ennodia_start_compositional`. |
 | `prompt` | none | Optional comparison prompt included in `compareNext` when the minimum outputs are ready. |
 | `minSuccessfulTasksForCompare` | `2` | Minimum successful non-empty outputs required for `compareReady`. |
-| `includeOutput` | `false` | Include bounded stdout and stderr previews for known tasks. |
-| `maxOutputChars` | `2000` | Maximum stdout and stderr characters per task when output is included. |
+| `includeOutput` | `false` | Include bounded stdout, stderr, and finalMessage previews for known tasks. |
+| `maxOutputChars` | `2000` | Maximum characters per task output field when output is included. |
 
 The response includes `readyTaskIds`, `runningTaskIds`, `failedTaskIds`,
 `cancelledTaskIds`, `emptySucceededTaskIds`, and `missingTaskIds`. It includes
@@ -462,13 +510,14 @@ Returns task status, captured output, events, timing, and ETA.
 | Input | Default | Meaning |
 | --- | --- | --- |
 | `taskId` | required | ID returned by a raw, compositional, advised-plan, run, Plan Advisor, or Compare start. |
-| `includeOutput` | `true` | Include bounded stdout and stderr. |
+| `includeOutput` | `true` | Include bounded stdout, stderr, and finalMessage. |
 | `includeEvents` | `true` | Include bounded task events. |
-| `maxOutputChars` | `20000` | Maximum stdout and stderr characters. Capped at 200000. |
+| `maxOutputChars` | `20000` | Maximum characters per output field. Capped at 200000. |
 | `maxEvents` | `100` | Maximum task events. Capped at 300. |
 
 A task is terminal only after the child process exits and stdout/stderr have
-drained or timed out visibly.
+drained or timed out visibly. Final-message collection and adapter error checks complete before terminal status becomes visible.
+Antigravity's explicit no-output error is a failure even when its command exits with code zero.
 
 ### `ennodia_cancel_task`
 
@@ -485,9 +534,9 @@ returns a compact view. Request output or events only when you need them.
 
 | Input | Default | Meaning |
 | --- | --- | --- |
-| `includeOutput` | `false` | Include bounded stdout and stderr previews for each task. |
+| `includeOutput` | `false` | Include bounded stdout, stderr, and finalMessage previews for each task. |
 | `includeEvents` | `false` | Include bounded task events for each task. |
-| `maxOutputChars` | `4000` | Maximum stdout and stderr characters per task. Capped at 200000. |
+| `maxOutputChars` | `4000` | Maximum characters per task output field. Capped at 200000. |
 | `maxEvents` | `25` | Maximum events per task. Capped at 300. |
 
 ## Judge + Result Advisor
@@ -557,3 +606,111 @@ server process.
 | `includeEvents` | `false` | Include bounded Judge and Result Advisor events. |
 | `maxCandidateChars` | `2000` | Maximum characters per candidate. Capped at 200000. |
 | `maxEvents` | `25` | Maximum events per comparison. Capped at 300. |
+
+## Pragmatic run settings
+
+In version 0.3.0, `ennodia_run`, `ennodia_estimate_budget`, `ennodia_start_compositional` and `ennodia_estimate_compositional_budget` accept optional `pragmatic: {recipe, acceptanceCriteria}`. Model and harness overrides remain optional.
+Recipes are `investigate` and `patch`. Both instruct workers to avoid file changes.
+
+Pragmatic preserves routing and comparison choices for one or more independent workers. Plan Advisor can propose tailored model and skill assignments. Retries are not automatic. Native harness permissions still apply.
+
+Run views include the requested `model` and `pragmatic` settings.
+See [Pragmatic mode](/docs/guides/pragmatic-mode/) for examples, evidence retrieval, and measurement limits.
+
+### Execution deadlines
+
+Task receipts include `deadlineAt` and `timeoutSource` (`caller` or
+`task-manager-default`). The deadline is the process cutoff, not a prediction
+of completion. Every child prompt receives its execution allowance and source.
+It asks for useful partial findings before the cutoff and reports of
+missing tools or permissions. Caller tools are not
+automatically inherited. This notice does not grant access or extend deadlines.
+
+A timed-out task is an interrupted attempt. Review its captured
+output, events, partial changes, scope, and access before deciding how to proceed.
+A timeout does not establish model inability.
+
+Opt-in Codex continuation is described below.
+
+Cancellation is visible immediately. In version 0.3.0, the history snapshot
+is saved after child processes finish and their output drains. Use a bounded
+`ennodia_get_run.waitMs` call when you need to wait for the saved evidence.
+The wait limit does not stop the child process or extend its execution limit.
+
+### Persistent Codex workers
+
+Set `persistSession: true` on `ennodia_run` to retain a native Codex session.
+Use an explicit `harnessId: "codex"` and a persistent working directory.
+Persistence cannot be combined with `isolateCwd`, parallel mode, or comparison.
+The Codex adapter defaults to its read-only sandbox on each turn.
+
+After the worker settles, inspect its task receipt. If `canContinue` is true,
+pass that task ID as `continueTaskId` in the next run. The follow-up keeps the
+harness and directory. It inherits the model and reasoning effort unless you
+supply new values. Each follow-up has a new task ID and execution allowance.
+An earlier turn cannot be used once a follow-up has started.
+
+Continuation requires a task still held by the same running Ennodia server.
+It does not import arbitrary native session IDs or restore ownership after
+a server restart. Native session files remain under the harness's retention
+policy. Ordinary runs remain ephemeral.
+
+Preflight input estimates exclude the retained native context. Use each
+turn's reported usage to assess cost. Persistence does not prove a cache hit
+or a cost saving. An interrupted session may fail to resume, so preserve its
+partial findings and files as evidence too.
+
+### Compact status reads
+
+Set `compact: true` on `ennodia_get_run` to omit the routing plan, budget
+explanation, prompt preview, and skill metadata from repeated status reads.
+Status, timing, task IDs, answers, errors, and diagnoses remain available.
+The existing answer and event limits still apply. Use `compact: false` for
+the full receipt. The default remains false.
+
+For pending runs, use `waitMs: 30000`, `compact: true`, and
+`includeEvents: false` when the installed schema supports these options.
+A compact response is not a summary of the worker's findings. Inspect the
+answer and any partial task evidence before drawing conclusions.
+
+### Native subagent controls
+
+`ennodia_run` and `ennodia_start` accept `nativeSubagents: "disabled"` for Codex
+workers. Codex receives native feature flags disabling its built-in subagent
+tools. Task receipts record the setting, and persistent follow-ups inherit it.
+Other harnesses reject this setting before workers start. Omitting it preserves
+native defaults. Judge and Advisor tasks do not receive this worker setting.
+
+This controls built-in delegation tools. It does not prevent a shell command
+from starting another program, grant file permissions, or account for nested
+agent usage. Do not infer a complete cost total from a parent-only receipt.
+
+
+### Native worker permissions
+
+Set `nativeSandbox: "workspace-write"` on a normal Codex worker run only
+when its assignment permits edits. Use `nativeSandbox: "read-only"` for
+investigation. Omission defaults to read-only on every turn, including
+continuations of write-enabled sessions. Write access is not inherited.
+
+The setting uses the supported Codex sandbox option. Native configuration
+still defines sandbox behavior and writable locations. This option does
+not grant caller tools, deployment access, or permission bypasses.
+Other adapters reject explicit sandbox settings. Pragmatic recipes reject
+workspace-write. Judge and Advisor tasks keep their existing defaults.
+
+Task receipts record the selected sandbox. Run receipts record the requested
+setting.
+
+### Evidence and operation limits in version 0.3.0
+
+Compositional status separates lost stream capture (`captureTruncated`) from shortened output previews (`outputTruncated`).
+Lost captures are listed in `truncatedTaskIds` and excluded from ready task IDs.
+A compact preview can omit a complete retained answer without making the task unready.
+Compare metadata identifies truncated evidence, including its prompt limit.
+Preserve full patch artifacts and verify them before application.
+
+`maxChildTasks` limits workers selected by the current operation.
+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.

package/docs/reference/supported-harnesses.md

@@ -32,7 +32,27 @@ installed and runnable on the current machine.
 ```
 
 The response reports availability, runnable state, command path, version,
-capabilities, and adapter notes.
+capabilities, adapter notes, and optional `inputGuidance`.
+
+`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.
+
+## Media Inputs
+
+Ennodia sends a text prompt through the selected CLI. Include local file paths and requested ranges in that prompt.
+The harness must read those files through its available tools and normal permissions.
+Model application programming interface (API) capabilities do not establish support through a harness's input transport or file tools.
+Run a small native-media probe before a larger review or comparison.
+
+Record the files, ranges, model, tool results, errors, and task IDs.
+For audio comparisons, match excerpts, playback level, and reference material across candidates.
+Native audio findings need evidence of successful media ingestion and observations tied to the requested excerpt.
+Transcription, digital signal processing (DSP), and text-only judging provide distinct evidence. Label each method explicitly.
 
 ## Claude Code Models
 
@@ -57,6 +77,25 @@ such as `opencode-go/kimi-k2.7-code`.
 
 ## Antigravity
 
+An explicit `jetski: no output produced` error is treated as a failed task even if the command exits with code zero.
+Check the requested tool access in normal Antigravity settings. A denied read does not measure the model or skill's quality.
+
+Ennodia uses `agy --print` with a text prompt containing local paths.
+Antigravity's documented stream input accepts text blocks only. It rejects media blocks.
+Use native `view_file` inspection when the selected harness and model expose it.
+Check the tool result before claiming native audio, image, video, or document inspection.
+See [headless input](https://antigravity.google/docs/cli/headless/#send-a-prompt) and the [CLI changelog](https://antigravity.google/changelog).
+
+A September 10, 2026 probe used `agy` 1.2.0 with Gemini 3.8 Flash Medium:
+
+- An eight-second MP3 native probe succeeded.
+- FLAC sent as `audio/x-flac` was rejected.
+- One comparison with four WAV samples timed out. This outcome leaves WAV support unresolved.
+
+These observations apply to that run configuration. They do not define a universal format blacklist.
+The CLI changelog records audio attachment support and media-type normalization fixes.
+Gemini API audio support uses a separate interface. Its [format list](https://ai.google.dev/gemini-api/docs/audio) does not guarantee `view_file` compatibility.
+
 Antigravity can fail setup when the `agy` CLI is not on `PATH`. Tell the user or
 primary agent to verify:
 

package/docs/roadmap.md

@@ -0,0 +1,25 @@
+---
+title: Roadmap
+description: Reduce the work of choosing, trying, and maintaining agent tools.
+---
+
+# Make the next useful attempt easier
+
+The roadmap follows the work a user wants to avoid.
+Future items are proposals, not available behavior or release dates.
+
+| Stage | User outcome | Product work |
+| --- | --- | --- |
+| Current | Try another agent or skill from the same conversation. | Discovery, focused tasks, explicit choices, optional team advice, Compare, and local history. |
+| Next release candidate | Trust the reported outcome and recover from failed attempts. | Process cleanup, valid comparison evidence, safer local server requests, clearer errors, and task-based guides. |
+| Next | Avoid repeating unsuccessful attempts. | Local outcome notes with task, model, version, skill, and relevant conditions. |
+| Later | Spend less time inspecting tool configuration. | Supported version and capability checks, clearer execution settings, and useful progress checkpoints. |
+| Later | Get useful suggestions for the next attempt. | Recommendations grounded in recorded outcomes, with reasons and uncertainty. |
+| Later | Reduce routine tool maintenance. | Configured updates through supported interfaces, version pinning, and recovery. |
+
+A failed login must not become a negative model rating.
+One unsuccessful attempt must not permanently exclude a model or skill.
+Recorded outcomes need a way to inspect, correct, and delete them.
+
+The [measurement plan](/docs/evidence/measurement/) covers task correctness, time, resources, and human work.
+General savings claims will need comparative evidence.

package/examples/docs-drift/README.md

@@ -0,0 +1,8 @@
+# Small Service
+
+This is an intentionally inconsistent documentation fixture for Ennodia.
+
+The current default port is 3000. Configure another port with `PORT`.
+The readiness response is `{ "status": "ok" }`.
+
+The [migration record](./archive/migration.md) describes the previous release.

package/examples/docs-drift/archive/migration.md

@@ -0,0 +1,4 @@
+# Migration record — previous release
+
+The previous release used port 3000, the `PORT` variable, and `{ "status": "ok" }`.
+This file is a historical record, not a current configuration guide.

package/examples/docs-drift/check.ts

@@ -0,0 +1,7 @@
+import assert from "node:assert/strict";
+import { DEFAULT_PORT, readPort, readiness } from "./config";
+assert.equal(DEFAULT_PORT, 4545);
+assert.equal(readPort({ APP_PORT: "5050" }), 5050);
+assert.equal(readPort({ PORT: "5050" }), 4545);
+assert.deepEqual(readiness(), { ready: true });
+console.log("Current behavior verified. Compare README claims with config.ts; preserve the labeled migration record.");

package/examples/docs-drift/config.ts

@@ -0,0 +1,8 @@
+export const DEFAULT_PORT = 4545;
+export function readPort(env: Record<string, string | undefined>): number {
+  const value = env.APP_PORT;
+  return value === undefined ? DEFAULT_PORT : Number(value);
+}
+export function readiness(): { ready: boolean } {
+  return { ready: true };
+}

package/examples/docs-drift/demo.ts

@@ -0,0 +1,54 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { resolve } from "node:path";
+
+// Opt-in live example. This starts one real agent and uses its configured access.
+if (!process.argv.includes("--live")) {
+  console.log("Run: bun examples/docs-drift/demo.ts --live <harness-id>");
+  console.log("Example: bun examples/docs-drift/demo.ts --live antigravity");
+  process.exit(0);
+}
+const harnessId = process.argv[process.argv.indexOf("--live") + 1];
+if (!harnessId) throw new Error("Select an installed, authenticated harness ID.");
+const root = resolve(import.meta.dir, "../..");
+const client = new Client({ name: "ennodia-docs-demo", version: "1" });
+const transport = new StdioClientTransport({
+  command: "bun", args: ["run", "src/cli.ts"], cwd: root, stderr: "pipe",
+});
+async function call(name: string, args: Record<string, unknown>) {
+  const result = await client.callTool({ name, arguments: args });
+  const text = (result.content as { type: string; text?: string }[])
+    .filter((item) => item.type === "text").map((item) => item.text).join("\n");
+  if (result.isError) throw new Error(text);
+  return JSON.parse(text);
+}
+try {
+  console.log("Ennodia live example: find stale documentation");
+  console.log(`Agent: ${harnessId}; configured default model; no model override.`);
+  console.log("Read-only task: check README against config.ts; preserve labeled history.");
+  await client.connect(transport);
+  const run = await call("ennodia_run", {
+    harnessId, mode: "single", compare: false, cwd: import.meta.dir, timeoutMs: 120000,
+    prompt: "Read only README.md, config.ts, and archive/migration.md. Compare current README claims with config.ts. Return each conflict and its correction in plain text, with relative file names only. Explain if the labeled historical migration record needs changes. Do not read other files or edit anything. Keep the response under 180 words.",
+  });
+  console.log(`Run: ${run.id}\nStatus: ${run.status}`);
+  const deadline = Date.now() + 135000;
+  for (;;) {
+    await Bun.sleep(2000);
+    const result = await call("ennodia_get_run", { runId: run.id, includeEvents: false, maxAnswerChars: 5000 });
+    if (["succeeded", "failed", "cancelled"].includes(result.status)) {
+      console.log(`Status: ${result.status}\nElapsed: ${result.elapsedMs} ms`);
+      console.log(result.finalAnswer || JSON.stringify(result.diagnosis ?? "No answer returned."));
+      console.log("Check each finding against config.ts before using it.");
+      console.log("This is one live attempt, without a speed or cost comparison.");
+      if (result.status !== "succeeded") process.exitCode = 1;
+      break;
+    }
+    if (Date.now() > deadline) {
+      await call("ennodia_cancel_run", { runId: run.id });
+      throw new Error("The bounded demo wait expired.");
+    }
+  }
+} finally {
+  await client.close();
+}

package/examples/docs-drift/recorded-run.json

@@ -0,0 +1,16 @@
+{
+  "recordedAt": "2026-09-06",
+  "kind": "single development trial",
+  "harness": "antigravity",
+  "model": "Configured default; exact model not established",
+  "runId": "d3e36bf1-07dd-4912-af33-b5c904603b44",
+  "taskIds": [
+    "e822af92-4410-4ed8-9382-f62a6f36a505"
+  ],
+  "status": "succeeded",
+  "elapsedMs": 13272,
+  "output": "* **Default Port Conflict**: [README.md:L5](../docs-drift/README.md#L5) claims the default port is `3000`, but [config.ts:L1](../docs-drift/config.ts#L1) defines [`DEFAULT_PORT`](../docs-drift/config.ts#L1) as `4545`.\n* **Port Environment Variable Conflict**: [README.md:L5](../docs-drift/README.md#L5) instructs users to configure ports using `PORT`, whereas [`readPort`](../docs-drift/config.ts#L2-L5) in [config.ts:L3](../docs-drift/config.ts#L3) reads `APP_PORT`.\n* **Readiness Response Conflict**: [README.md:L6](../docs-drift/README.md#L6) states the readiness response is `{ \"status\": \"ok\" }`, but [`readiness`](../docs-drift/config.ts#L6-L8) in [config.ts:L6-L7](../docs-drift/config.ts#L6-L7) returns `{ ready: true }`.\n* **Archive Status**: [archive/migration.md](../docs-drift/archive/migration.md#L1-L5) does **not** need changes; as stated in [archive/migration.md:L3-L4](../docs-drift/archive/migration.md#L3-L4), it is explicitly labeled as a historical migration record of the previous release rather than active configuration documentation.",
+  "edits": "Local file URL prefixes normalized to fixture-relative paths.",
+  "verification": "Primary agent checked all three conflicts and the historical distinction against the fixture.",
+  "limitation": "Known-answer fixture. No control run or speed or cost advantage established."
+}

package/examples/skill-trial/README.md

@@ -0,0 +1,8 @@
+# Try a review skill on one small function
+
+Compare `retry.ts` with `contract.md`. The function has deliberate defects.
+Run a plain review and a review with a native installed skill in separate tasks.
+Use the same model, files, and request. Save both findings before opening `check.ts`.
+
+The evaluator contains the expected cases. Keep it out of the review material.
+This example demonstrates the workflow. It does not establish that a skill improves quality.

package/examples/skill-trial/check.ts

@@ -0,0 +1,15 @@
+import { retryDelaySeconds } from "./retry";
+const cases: [string | null, number][] = [
+  [null, 30], ["0", 0], ["12", 12], ["120", 120], ["", 30], [" ", 30],
+  ["1.5", 30], ["-1", 30], ["121", 30], ["1e2", 30], ["0x10", 30],
+];
+let failures = 0;
+for (const [input, expected] of cases) {
+  const actual = retryDelaySeconds(input);
+  if (actual !== expected) {
+    failures += 1;
+    console.log(`${JSON.stringify(input)}: expected ${expected}, received ${actual}`);
+  }
+}
+console.log(`${cases.length - failures}/${cases.length} contract cases passed.`);
+process.exitCode = failures ? 1 : 0;

package/examples/skill-trial/contract.md

@@ -0,0 +1,7 @@
+# Retry delay contract
+
+- A missing value uses 30 seconds.
+- A decimal integer from 0 through 120 specifies the delay in seconds.
+- Zero is valid and means retry immediately.
+- Empty values, whitespace, fractions, negative values, and values over 120 use 30 seconds.
+- The function must not accept numeric notation such as `1e2` or `0x10`.

package/examples/skill-trial/recorded-trial.json

@@ -0,0 +1,42 @@
+{
+  "recordedAt": "2026-09-06",
+  "kind": "inconclusive native skill trial",
+  "harness": "antigravity",
+  "model": "Configured default; exact model not established",
+  "plain": {
+    "taskId": "125ffd40-c224-4615-a441-f31154a26096",
+    "status": "succeeded",
+    "elapsedMs": 18023,
+    "requestedSkills": [],
+    "output": "Contract violations identified in [`retryDelaySeconds`](./retry.ts#L2) based on [contract.md](./contract.md):\n\n* **Zero input (`\"0\"`)**: Returns `30` instead of `0` because `Number(\"0\")` evaluates to `0`, which is falsy in `0 || 30`.\n* **Values exceeding upper bound (`\"121\"`)**: Returns `121` instead of `30` because there is no `> 120` boundary check.\n* **Negative values (`\"-1\"`)**: Returns `-1` instead of `30` because negative numbers are truthy and not checked against `< 0`.\n* **Fractions (`\"1.5\"`)**: Returns `1.5` instead of `30` because `Number(\"1.5\")` parses floats without integer validation.\n* **Scientific notation (`\"1e2\"`)**: Returns `100` instead of `30`, directly violating the rule disallowing numeric notation like `1e2`.\n* **Hexadecimal notation (`\"0x10\"`)**: Returns `16` instead of `30`, directly violating the rule disallowing numeric notation like `0x10`.\n* **Binary / octal notation (`\"0b10\"`)**: Returns `2` instead of `30` because `Number()` parses alternative radix notations instead of strictly decimal integers.\n"
+  },
+  "requestedSkill": {
+    "taskId": "233ba69d-b691-4e34-94db-c3fa03a759bb",
+    "reportedStatus": "succeeded",
+    "observedOutcome": "No answer; required read_file access denied",
+    "exitCode": 0,
+    "elapsedMs": 17290,
+    "requestedSkills": [
+      {
+        "id": "source-grounded-audit",
+        "name": "source-grounded-audit",
+        "version": "local",
+        "hash": "87366950aa303123d38f7d97cd6cc01a842ca7cc18ffc41f75653bec76fe9cfa",
+        "source": "project",
+        "harnessIds": [
+          "antigravity",
+          "claude-code",
+          "codex",
+          "installable",
+          "opencode"
+        ],
+        "native": true
+      }
+    ],
+    "stderrExcerpt": "jetski: no output produced — a tool required the \"read_file\" permission that headless mode cannot prompt for, so it was auto-denied.",
+    "output": ""
+  },
+  "edits": "Local file URL prefixes normalized; CLI remediation instructions omitted from the diagnostic excerpt.",
+  "verification": "Plain findings checked against the contract and evaluator. This denied attempt cannot measure skill effectiveness.",
+  "limitation": "Uncontrolled native skill inventory; loading not verified. The zero-exit false success is fixed in the release candidate."
+}

package/examples/skill-trial/retry.ts

@@ -0,0 +1,4 @@
+// Deliberately incomplete implementation for a review exercise.
+export function retryDelaySeconds(value: string | null): number {
+  return Number(value) || 30;
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "ennodia",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "mcpName": "io.github.cherninlab/ennodia",
-  "description": "Local MCP server for AI team advice, multi-agent review, Compare, and traceable receipts",
+  "description": "Try other agents, models, and skills from your familiar AI workflow through a local MCP server",
   "license": "MIT",
   "type": "module",
   "packageManager": "bun@1.3.14",
@@ -35,6 +35,7 @@
     "bench/bug-recall/scorer.ts",
     "bench/fixtures/**/*",
     "bench/results/.gitkeep",
+    "examples/**/*",
     "src/cli.ts",
     "src/advisor.ts",
     "src/budget.ts",
@@ -46,7 +47,9 @@
     "src/history.ts",
     "src/index.ts",
     "src/internal.ts",
+    "src/pragmatic.ts",
     "src/planner.ts",
+    "src/process.ts",
     "src/plan-advice.ts",
     "src/priority.ts",
     "src/runs.ts",