@iowarp/clio-coder 0.4.1 → 0.4.3

package/docs/README.md

@@ -2,103 +2,198 @@
   <img src="../assets/clio-coder-logo-128.webp" alt="Clio Coder logo" width="96" height="96" />
 </p>
 
-# Clio Coder Documentation
+# Clio Coder documentation
 
-These pages document `v0.4.0` of Clio Coder, an open-source coding orchestrator within the [IOWarp](https://iowarp.ai) scientific computing platform, created by the [Gnosis Research Center](https://grc.iit.edu) at the [Illinois Institute of Technology](https://www.iit.edu).
+> **Visual blueprint:** The source checkout includes the complete
+> [Clio Coder documentation visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/readme_blueprint.html).
 
-They are source-aligned guides: when prose and source disagree, prefer the
-current source, tests, and `CHANGELOG.md`.
+This is the documentation map for Clio Coder. Start with the path closest to
+what you are trying to do; the deeper references are here when you need exact
+schemas, wire contracts, or architectural invariants.
 
-## Start Here
+The guides track the current source tree. Released behavior is fixed by the
+corresponding Git tag and [changelog](../CHANGELOG.md). If prose and the checked
+source disagree, treat source, schema validation, and contract tests as
+authoritative—and please fix or report the documentation drift.
 
-| Need | Guide |
+The reference is organized by purpose:
+
+```text
+docs/
+├── guide/          Operator and user workflows
+├── architecture/   Runtime contracts and design
+├── process/        Development, validation, and release practice
+├── history/        Dated records that are not current guidance
+└── html/           Source-checkout visual blueprints
+```
+
+## Start here
+
+| Goal | Guide |
 | --- | --- |
-| Commands, slash commands, operating posture, keybindings, dispatch, verification, and troubleshooting | [commands-and-modes.md](commands-and-modes.md) ([Interactive Blueprint](html/commands_blueprint.html)) |
-| Context window resolution, per-model probe capabilities, token accounting, per-turn snapshots, compaction, and context priming | [context-engine.md](context-engine.md) ([Interactive Blueprint](html/context_blueprint.html)) |
-| Non-destructive working-set eviction, markers, eviction policies, recall by ref, and the `contextEviction` / `contextRecall` records | [context-working-set.md](context-working-set.md) |
-| Runtime targets, local model configuration, fleet profiles, and auth | [configuration-and-targets.md](configuration-and-targets.md) ([Interactive Blueprint](html/configuration_blueprint.html)) |
-| Every environment variable the runtime reads: guardrail overrides, directory layout, debug toggles, and internal plumbing | [environment-variables.md](environment-variables.md) ([Interactive Blueprint](html/environment_blueprint.html)) |
-| Argonne ALCF Sophia/Metis inference targets over Globus OAuth | [alcf-provider.md](alcf-provider.md) ([Interactive Blueprint](html/alcf_blueprint.html)) |
-| Installation, upgrade, reset, uninstallation, configuration folders, and permissions | [installation-and-lifecycle.md](installation-and-lifecycle.md) ([Interactive Blueprint](html/lifecycle_blueprint.html)) |
-| Safety posture, default-deny Bash, project policy, damage-control rules, and typed validation | [safety-model.md](safety-model.md) ([Interactive Blueprint](html/safety_blueprint.html)) |
-| Source layout, compile-time boundaries, domain loading, and runtime data flow | [architecture.md](architecture.md) ([Interactive Blueprint](html/architecture_blueprint.html)) |
-| Why the dispatch domain is not split, which invariants cross the obvious seams, and why direct subpath imports are permitted | [dispatch-architecture-rationale.md](dispatch-architecture-rationale.md) ([Interactive Blueprint](html/dispatch_rationale_blueprint.html)) |
-| Typed dispatch intent: the producer and persisted-contract compatibility tables, refusal reason codes, and the legacy-inference retirement criterion | [dispatch-typed-intent.md](dispatch-typed-intent.md) |
-| Prompt envelope reuse, provider tool delivery, and bounded tool results | [prompt-envelope-and-tools.md](prompt-envelope-and-tools.md) ([Interactive Blueprints: prompt_envelope](html/prompt_envelope_blueprint.html), [tools](html/tools_blueprint.html)) |
-| In-depth reference for all 20 worker tools: parameters, typical payloads, and error examples | [tool-usage.md](tool-usage.md) ([Interactive Blueprint](html/tool_usage_blueprint.html)) |
-| Developer guide to implementing custom model runtimes and inference server integrations | [provider-adapter-cookbook.md](provider-adapter-cookbook.md) ([Interactive Blueprint](html/provider_adapter_blueprint.html)) |
-| Built-in agent recipes, discovery roots, frontmatter schema, and dispatch admission | [built-in-agents.md](built-in-agents.md) ([Interactive Blueprint](html/agents_blueprint.html)) |
-| Artifact browsing, receipt verification, dispatch diagnostics, and observability routing | [observability.md](observability.md) ([Interactive Blueprint](html/observability_blueprint.html)) |
-| Evidence-aware Git commit role trailers, managed-hook safety, and how platforms render the identity | [git-commit-provenance.md](git-commit-provenance.md) |
-| Where every generated file lands: the working tree, `.clio-coder/`, and the XDG dirs, by audience | [artifact-placement.md](artifact-placement.md) ([Interactive Blueprint](html/artifact_placement_blueprint.html)) |
-| Evidence directory structures, findings, and operator-approved memory retrieval | [evidence-and-memory.md](evidence-and-memory.md) ([Interactive Blueprint](html/memory_blueprint.html)) |
-| Local YAML eval suites, reports, comparisons, and command evidence | [eval-runner.md](eval-runner.md) ([Interactive Blueprint](html/eval_blueprint.html)) |
-| Prompt and skill resources, extension manifests, and portable share archives | [extensions-and-sharing.md](extensions-and-sharing.md) ([Interactive Blueprint](html/extensions_blueprint.html)) |
-| Skills Hub marketplace discovery, install actions, and publishing flow | [skills-marketplace.md](skills-marketplace.md) ([Interactive Blueprint](html/skills_blueprint.html)) |
-| Runtime model refresh, catalog sources, local/cloud model quirks, and benchmarking notes | [model-catalog.md](model-catalog.md) ([Interactive Blueprint](html/models_blueprint.html)) |
-| Active component snapshots and the experimental middleware hook/effect contract | [middleware-and-components.md](middleware-and-components.md) ([Interactive Blueprint](html/middleware_blueprint.html)) |
-| Advisory validation-contract patterns for scientific artifacts and HPC assumptions | [scientific-validation.md](scientific-validation.md) ([Interactive Blueprint](html/validation_blueprint.html)) |
-| Falsifiable Change Manifest JSON templates, auditability, and `clio-coder evolve` | [evolution.md](evolution.md) ([Interactive Blueprint](html/evolution_blueprint.html)) |
-| Source-first docs workflow, mapping matrix, and alpha wording guidance | [documentation-guide.md](documentation-guide.md) ([Interactive Blueprint](html/documentation_blueprint.html)) |
-| Typed resource catalogs, private synchronization, installation roots, and library CLI | [resource-library.md](resource-library.md) |
-| Interface layout, colors palette, Unicode character vocabulary, and drawing choreography | [tui-design.md](tui-design.md) ([Interactive Blueprint](html/tui_design_blueprint.html)) |
-| NDJSON parent-child socket protocols, watchdog timers, and exit status mapping | [worker-dispatch-mechanics.md](worker-dispatch-mechanics.md) ([Interactive Blueprint](html/worker_dispatch_blueprint.html)) |
-| Multi-node fleet dispatch: process-safe admission, attested workers, measured routing, activation, agent automation, topologies, and receipts | [fleet-dispatch.md](fleet-dispatch.md) ([Interactive Blueprint](html/fleet_dispatch_blueprint.html)) |
-| Multi-process capacity leases, heartbeat TTLs, cross-process locks, and cluster drain controls | [capacity-and-scheduling.md](capacity-and-scheduling.md) ([Interactive Blueprint](html/capacity_scheduling_blueprint.html)) |
-| Executable multi-node demo with reviewer gate and receipt provenance walkthrough | [fleet-demo-runbook.md](fleet-demo-runbook.md) |
-| Session lifecycle, on-disk ledger format v4, `/tree` active-path lineage, `/fork`, `/resume`, checkpoints, and recovery | [session-lifecycle.md](session-lifecycle.md) ([Interactive Blueprint](html/session_lifecycle_blueprint.html)) |
-| Agent Client Protocol (ACP) server over stdio, tool mediation, non-stall permissions, and error taxonomy | [acp.md](acp.md) ([Interactive Blueprint](html/acp_blueprint.html)) |
-| Version registry and migration policies for all 9 serialized artifact schemas | [artifact-versions.md](artifact-versions.md) ([Interactive Blueprint](html/artifact_versions_blueprint.html)) |
-| Process exit code taxonomy, `--help` standard, machine-readable JSON streaming, and headless output contracts | [exit-codes-and-output.md](exit-codes-and-output.md) ([Interactive Blueprint](html/exit_codes_blueprint.html)) |
-| Actionable error remediation and diagnostics keyed by exact user-facing messages | [troubleshooting.md](troubleshooting.md) ([Interactive Blueprint](html/troubleshooting_blueprint.html)) |
-| Canonical definitions of 45 core architectural concepts mapped to `src/` types | [glossary.md](glossary.md) ([Interactive Blueprint](html/glossary_blueprint.html)) |
-| Complete source-to-documentation mapping matrix and subsystem coverage status | [documentation-coverage.md](documentation-coverage.md) |
-| Issue-driven development lifecycle: file-ticket through release, label taxonomy, and dogfooding setup | [development-pipeline.md](development-pipeline.md) |
-| Proactive task memory architecture, session task bank, intervention rules, and handoff carrying | [proactive-memory.md](proactive-memory.md) ([Interactive Blueprint](html/memory_blueprint.html)) |
-| WAL SQLite trace mirror database schema, rowid cursor queries, rebuildability, and CLI trace subcommands | [trace-store.md](trace-store.md) ([Interactive Blueprint](html/trace_blueprint.html)) |
-| Private context index determinism and target smoke matrices | [evals-internal.md](evals-internal.md) ([Blueprint](html/evals_internal_blueprint.html)) |
-| Point-in-time inventory of legacy environment variables (Historical Appendix) | [config-knobs-audit.md](config-knobs-audit.md) ([Interactive Blueprint](html/config_knobs_audit_blueprint.html)) |
-| Clock and timestamp conventions: durations, instants, ordering, and formatting | [time-conventions.md](time-conventions.md) ([Interactive Blueprint](html/time_conventions_blueprint.html)) |
-| Correct render, PTY, startup, compile-cache, and import-graph measurement endpoints and the 0.3.3 baseline | [performance-methodology.md](performance-methodology.md) |
-| Pi SDK boundary: upstream primitives, attribution, and Clio-owned product policies | [pi-boundary.md](pi-boundary.md) ([Interactive Blueprint](html/pi_boundary_blueprint.html)) |
-
-Every project Clio works in gets its context from a local `CLIO-CODER.md`,
-bootstrapped and maintained by `clio-coder context init`. It's human-owned and
-versioned by default; this repo's own root `CLIO-CODER.md` is the exception,
-gitignored here for dogfooding so this checkout's copy doesn't collide with
-Clio's own committed docs. Run `clio-coder context init` in this checkout to
-generate one for Clio's own source.
-
-## Developer Quick Start
+| Install Clio and connect the first model | [Installation and Lifecycle](guide/installation-and-lifecycle.md) → [Configuration and Targets](guide/configuration-and-targets.md) |
+| Learn the interactive session and CLI | [Commands and Modes](guide/commands-and-modes.md) |
+| Understand what Clio may read, change, or execute | [Safety Model](architecture/safety-model.md) |
+| Diagnose a problem by its exact message | [Troubleshooting](guide/troubleshooting.md) |
+
+A minimal first run is:
+
+```bash
+npm install -g @iowarp/clio-coder
+clio-coder configure
+cd /path/to/your/project
+clio-coder
+```
+
+Use `clio-coder --help` for the installed command surface and `/help` inside an
+interactive session. `clio-coder doctor` is a read-only installation check;
+`doctor --fix` performs only the repairs it reports.
+
+## Using Clio day to day
+
+| Topic | Guide |
+| --- | --- |
+| Targets, providers, auth, settings v2, routing, and fleet profiles | [Configuration and Targets](guide/configuration-and-targets.md) |
+| Every settings key, environment variable, flag, and project-file key with its default and precedence | [Configuration Reference](guide/configuration-reference.md) |
+| Runtime discovery, model capabilities, local overlays, and field notes | [Model Catalog](architecture/model-catalog.md) |
+| Argonne ALCF Sophia and Metis targets over Globus OAuth | [ALCF Provider](architecture/alcf-provider.md) |
+| Project handbooks, context windows, accounting, compaction, and indexing | [Context Engine](architecture/context-engine.md) |
+| Non-destructive working-set eviction, markers, and recall | [Context Working Set](architecture/context-working-set.md) |
+| Session ledgers, branches, checkpoints, resume, and recovery | [Session Lifecycle](architecture/session-lifecycle.md) |
+| Proactive task memory, interventions, and handoffs | [Proactive Memory](guide/proactive-memory.md) |
+| Skills discovery, marketplace safety, installation, and publishing | [Skills Marketplace](guide/skills-marketplace.md) |
+| Agents, prompts, extensions, and portable share archives | [Extensions and Sharing](guide/extensions-and-sharing.md) |
+| Private resource catalogs and synchronization | [Resource Library](guide/resource-library.md) |
+| TUI layout, responsive behavior, colors, and interaction rules | [TUI Design](architecture/tui-design.md) |
+| Terminal panes beside a session and the files pane: install, keys, settings, doctor, troubleshooting | [Panes and the Files Pane](guide/panes-and-files.md) |
+
+## Safety, evidence, and reproducibility
+
+| Topic | Guide |
+| --- | --- |
+| Autonomy, default-deny execution, project policy, and damage-control rules | [Safety Model](architecture/safety-model.md) |
+| Receipts, run inspection, costs, and observability routing | [Observability](architecture/observability.md) |
+| Durable evidence bundles, findings, and reviewed memory | [Evidence and Memory](architecture/evidence-and-memory.md) |
+| SQLite trace mirror, schemas, cursors, and rebuildability | [Trace Store](architecture/trace-store.md) |
+| Where generated files live and who should read them | [Artifact Placement](architecture/artifact-placement.md) |
+| Evidence-aware Git role trailers and managed-hook safety | [Git Commit Provenance](process/git-commit-provenance.md) |
+| Advisory scientific validation contracts and HPC assumptions | [Scientific Validation](process/scientific-validation.md) |
+| Versioned artifact schemas and migration policy | [Artifact Versions](architecture/artifact-versions.md) |
+
+Receipts establish what Clio observed and did. They do not replace domain
+validation, reference data, or human scientific judgment.
+
+## Delegation and fleets
+
+| Topic | Guide |
+| --- | --- |
+| Built-in worker recipes, discovery, frontmatter, and admission | [Built-in Agents](guide/built-in-agents.md) |
+| Local and multi-node fleet execution, placement, gates, and receipts | [Fleet Dispatch](guide/fleet-dispatch.md) |
+| An executable multi-node walkthrough with a reviewer gate | [Fleet Demo Runbook](process/fleet-demo-runbook.md) |
+| Capacity leases, heartbeats, locks, and node drain control | [Capacity and Scheduling](architecture/capacity-and-scheduling.md) |
+| Worker process protocol, watchdogs, steering, and exit mapping | [Worker Dispatch Mechanics](architecture/worker-dispatch-mechanics.md) |
+| Typed dispatch intent and compatibility boundaries | [Dispatch Typed Intent](architecture/dispatch-typed-intent.md) |
+| Why dispatch remains one domain and where its seams actually are | [Dispatch Architecture Rationale](architecture/dispatch-architecture-rationale.md) |
+
+## Automation and integration
+
+| Topic | Guide |
+| --- | --- |
+| Agent Client Protocol server, stdio transport, and permission mediation | [ACP](architecture/acp.md) |
+| Prompt-envelope reuse, provider tool delivery, and bounded results | [Prompt Envelope and Tools](architecture/prompt-envelope-and-tools.md) |
+| All built-in worker tools, arguments, outputs, and error examples | [Tool Usage](guide/tool-usage.md) |
+| Implementing a runtime or inference-server adapter | [Provider Adapter Cookbook](architecture/provider-adapter-cookbook.md) |
+| Middleware hooks, effects, budgets, and component snapshots | [Middleware and Components](architecture/middleware-and-components.md) |
+| Process exit codes, stdout/stderr rules, JSONL, and `--help` contracts | [Exit Codes and Output](guide/exit-codes-and-output.md) |
+| Environment overrides, directory controls, and debug toggles | [Environment Variables](guide/environment-variables.md) |
+
+## Evaluation and measurement
+
+| Topic | Guide |
+| --- | --- |
+| Local Suite v2 files, artifacts, reports, comparisons, and gates | [Eval Runner](process/eval-runner.md) |
+| Private suite handling and measurement design | [Internal Evals](process/evals-internal.md) |
+| Correct render, startup, import-graph, and streaming measurements | [Performance Methodology](process/performance-methodology.md) |
+| Falsifiable change manifests and `clio-coder evolve` | [Evolution](process/evolution.md) |
+
+Reviewable reference suites ship under [`evals/`](../evals/). They are explicit
+operator measurements, not hidden CI steps. Private prompts, credentials,
+endpoints, raw campaign artifacts, and proprietary datasets belong outside the
+repository.
+
+## Architecture and contributing
+
+| Topic | Guide |
+| --- | --- |
+| Source layout, compile-time boundaries, domain loading, and runtime flow | [Architecture](architecture/architecture.md) |
+| Pi framework boundary and Clio-owned policy | [Pi Boundary](architecture/pi-boundary.md) |
+| Documentation style and source-alignment workflow | [Documentation Guide](process/documentation-guide.md) |
+| Source-to-guide ownership map | [Documentation Coverage](process/documentation-coverage.md) |
+| Issue-driven development and release workflow | [Development Pipeline](process/development-pipeline.md) |
+| Clock, duration, timestamp, and ordering conventions | [Time Conventions](architecture/time-conventions.md) |
+| Core terms mapped to source concepts | [Glossary](guide/glossary.md) |
+
+The [configuration-knob audit](history/config-knobs-audit.md) is a dated historical
+inventory, not the current settings reference. The
+[v0.4.1 release-cut checklist](history/release-cut-checklist.md) is retained as release
+engineering history and must not be reused unchanged for a future release.
+
+## Developer quick start
 
 ```bash
 git clone https://github.com/iowarp/clio-coder.git
 cd clio-coder
+npm ci
+npm run build
+node dist/cli/index.js --help
+```
+
+For a persistent local command:
+
+```bash
 npm run install:local
+export PATH="$HOME/.local/bin:$PATH"
 hash -r
 clio-coder --version
 ```
 
-The local symlink executes `dist/cli/index.js`. If you edit TypeScript files
-under `src/`, run `npm run build` again or keep `npm run dev` running.
+Use `npm run dev` for a watch build. Before handing back a change, run the
+focused test while iterating and `npm run ci` for the deterministic repository
+gate. Maintainers use `npm run ci:release` to add the distribution and package
+audit.
+
+## Project context in a source checkout
 
-## Release Notes
+Projects can keep human-owned guidance in `CLIO-CODER.md`, generated with
+`clio-coder context init`. This repository gitignores its own generated copy so
+local dogfooding instructions do not collide with public documentation. If the
+file exists in your checkout, read it before making changes; if it does not,
+the architecture guide and `CONTRIBUTING.md` are the public starting points.
+
+## Interactive blueprints
+
+Every Markdown page has a dedicated visual blueprint under `docs/html/`, and
+the separate `docs/html/index.html` landing page mirrors this documentation
+tree. Blueprint links use the public repository so they still work when a guide
+is read from the npm package. From a source checkout, serve the same files
+locally with:
+
+```bash
+clio-coder docs
+```
 
-The release entry point is [../README.md](../README.md); detailed release
-history lives in [../CHANGELOG.md](../CHANGELOG.md). For v0.4.0 the supported
-install paths are `npm install -g @iowarp/clio-coder` and a source checkout
-through `npm run install:local`, the deterministic release gate is
-`npm run ci:release`, and live model smoke validation is local/manual and
-opt-in through `npm run live:smoke -- --target <id>` (add `--delegation`
-for opencode/copilot checks).
+The Markdown pages are the portable reference and ship with the npm package.
+The HTML blueprints are development aids and are not required for the runtime.
 
-## Writing Documentation
+## Writing documentation
 
-Guidance for doc authors lives in
-[documentation-guide.md](documentation-guide.md). The short version:
+Follow [Documentation Guide](process/documentation-guide.md). In particular:
 
-- State alpha status plainly; do not imply npm publication, production
-  stability, or universal local-model behavior without current proof.
-- Prefer command examples that are valid against
-  `node dist/cli/index.js --help`.
-- Keep the README short; detailed command explanations belong in these pages.
+- Verify commands against the built binary rather than copying an old example.
+- Use current, canonical settings paths; describe legacy names only in a
+  clearly marked migration or historical section.
+- Separate deterministic contracts from model-dependent observations.
+- Put release chronology in the [CHANGELOG](../CHANGELOG.md), not in the
+  product README or an evergreen task guide.
+- Link to the detailed contract instead of duplicating a large schema in
+  several places.

package/docs/{acp.md → architecture/acp.md}

@@ -1,6 +1,9 @@
 # Agent Client Protocol (ACP) Server
 
-This document defines the architecture, transport protocols, tool mediation layers, permission handling, and error taxonomy for Clio Coder's Agent Client Protocol (ACP) server implementation in `v0.4.0`.
+> **Visual blueprint:** The source checkout includes the complete
+> [Agent Client Protocol (ACP) Server visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/acp_blueprint.html).
+
+This document defines the architecture, transport protocols, tool mediation layers, permission handling, and error taxonomy for Clio Coder's Agent Client Protocol (ACP) server implementation in the current source tree.
 
 Source implementations: `src/engine/acp/` and `src/cli/acp.ts`.
 
@@ -22,7 +25,7 @@ graph LR
     client[External ACP Client] <-->|JSON-RPC 2.0 / stdio| server[Clio ACP Server]
     server --> mediator[Tool Mediator & Safety Net]
     mediator --> engine[Clio Execution Engine]
-    mediator --> session[Session Ledger v3]
+    mediator --> session[Session Ledger v4]
 ```
 
 ---
@@ -40,7 +43,7 @@ both spellings reach the same command dispatcher, option parser, stdout guard,
 and server boot path.
 
 - `--cwd PATH`: Workspace root the server boots in. The path is resolved and then canonicalized with `fs.realpath`, so a symlinked launch root, a trailing slash, and a `/.` suffix all name the same workspace. Clio changes into that canonical path before it reads settings, builds project context, or opens a session ledger, so a session opens at that root. A path that does not exist or that the process cannot enter exits 2 without starting the server. The canonical path is the server's workspace identity for its whole life: `session/new` must carry a `cwd` that canonicalizes to the same path, and nothing after boot ever changes the process directory.
-- `--permission-timeout MS`: The server-side fail-safe ceiling for one mediated permission request, as a whole number from 1 through Node's maximum schedulable timer delay (`2147483647`) milliseconds. Values outside that range are refused before the protocol server starts. If the timer wins, the approval expires, the active turn is aborted, every parked call for that turn is settled only so execution can unwind, and `session/prompt` fails with `permission_expired`. Expiry is audited as `expired`, never as a human denial, and no denial result is fed into a continuing model loop. The flag overrides `delegation.defaults.permissionTimeoutMs` for this server only, which itself defaults to `DEFAULT_DELEGATION_PERMISSION_TIMEOUT_MS = 120000` (`src/core/defaults.ts:149`). The shipped Workbench treats the remaining ACP request window as a hard ceiling on its own approval budget, projects that duration onto the Workbench clock, escalates immediately when the remaining window is shorter than its escalation delay, and cancels without publishing a card if the window has already elapsed. Other clients may enforce a shorter operator-facing policy by sending ordinary `session/cancel`.
+- `--permission-timeout MS`: The server-side fail-safe ceiling for one mediated permission request, as a whole number from 1 through Node's maximum schedulable timer delay (`2147483647`) milliseconds. Values outside that range are refused before the protocol server starts. If the timer wins, the approval expires, the active turn is aborted, every parked call for that turn is settled only so execution can unwind, and `session/prompt` fails with `permission_expired`. Expiry is audited as `expired`, never as a human denial, and no denial result is fed into a continuing model loop. The flag overrides `integrations.externalAgents.defaults.permissionTimeoutMs` for this server only, which itself defaults to `DEFAULT_DELEGATION_PERMISSION_TIMEOUT_MS = 120000` (`src/core/defaults.ts:290`). The source-checkout Workbench treats the remaining ACP request window as a hard ceiling on its own approval budget, projects that duration onto the Workbench clock, escalates immediately when the remaining window is shorter than its escalation delay, and cancels without publishing a card if the window has already elapsed. Other clients may enforce a shorter operator-facing policy by sending ordinary `session/cancel`.
 
 Transport frames are JSON-RPC 2.0 messages serialized over `stdin`/`stdout`. All logging and diagnostic output is strictly routed to `stderr` to preserve standard I/O framing integrity.
 
@@ -67,7 +70,7 @@ These are every method the server answers (`src/engine/acp/server.ts`). Anything
 | `clio-coder/targets/list` | Client → Server | Lists bounded, credential-free target/model summaries from configuration and the in-memory cache without network traffic. |
 | `clio-coder/targets/probe` | Client → Server | Explicitly probes one configured target through the provider domain and returns only a closed health result. |
 | `session/request_permission` | Server → Client | Requests permission from the client for a gated tool operation. |
-| `clio-coder/event` | Server → Client | Sends a versioned extension event only to a client that opted into a recognized kind. The v1 allowlist is `safety.loopBlocked` plus `dispatch.enqueued`, `dispatch.started`, `dispatch.progress`, `dispatch.completed`, and `dispatch.failed`. |
+| `clio-coder/event` | Server → Client | Sends a versioned extension event only to a client that opted into a recognized kind. The v1 allowlist is `safety.loopBlocked` plus `dispatch.enqueued`, `dispatch.started`, `dispatch.progress`, `dispatch.completed`, `dispatch.failed`, and `accountability.evidenceReady`. |
 
 `agentCapabilities.loadSession` is `true`. All non-standard methods are advertised only under `agentCapabilities._meta`; a strict generic ACP v1 client sees the standard new/load/prompt/cancel/permission surface, ignores namespaced result metadata, and receives no non-standard notification unless it explicitly opts into a recognized event kind.
 
@@ -86,7 +89,7 @@ JSON-RPC layer codes stay standard: `-32700` parse, `-32600` invalid request, `-
  "data":{"_meta":{"clio-coder/error":{"version":1,"code":"<closed-set string>","reason":"<optional>","supported":[1]}}}}
 ```
 
-`data` never carries a stack, an echoed frame, a filesystem path, provider text, or a secret. Neither does `message`. Every message on the wire is authored by this process: `turn_failed` is always the fixed string `the prompt turn failed`, `internal_error` is always the fixed string `internal error`, and `method_not_found` is always the fixed string `method not found`, whatever the underlying failure said and whatever the peer called. A provider or engine failure body legitimately quotes the request URL it used, the settings file it read a credential from, or the credential itself, and bounding that text to one line still ships the secret. The client branches on `data._meta`'s `code`; the original message, bounded to one line, goes to stderr prefixed with `[clio:acp]`. The `code` values are a closed set:
+`data` never carries a stack, an echoed frame, a filesystem path, provider text, or a secret. Neither does `message`. Every message on the wire is authored by this process: `turn_failed` is always the fixed string `the prompt turn failed`, `internal_error` is always the fixed string `internal error`, and `method_not_found` is always the fixed string `method not found`, whatever the underlying failure said and whatever the peer called. A provider or engine failure body legitimately quotes the request URL it used, the settings file it read a credential from, or the credential itself, and bounding that text to one line still ships the secret. The client branches on `data._meta`'s `code`; the original message, bounded to one line, goes to stderr prefixed with `[clio-coder:acp]`. The `code` values are a closed set:
 
 | `data.code` | When |
 | :--- | :--- |
@@ -146,8 +149,8 @@ Every replay notification precedes the `session/load` response and carries `para
 `clio-coder/settings/get_safe` accepts `{}` and returns exactly:
 
 ```json
-{"settings":{"orchestrator":{"target":null,"model":null,"thinkingLevel":"off"},"autonomy":"auto-edit"},
- "editable":["orchestrator.target","orchestrator.model","orchestrator.thinkingLevel","autonomy"]}
+{"settings":{"chat":{"target":null,"model":null,"thinkingLevel":"off"},"safety":{"autonomy":"auto-edit"}},
+ "editable":["chat.target","chat.model","chat.thinkingLevel","safety.autonomy"]}
 ```
 
 The values above are illustrative. Thinking is one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. No other settings leaf, URL, auth fact, credential reference, path, header, provider reason, or provider error crosses the wire. The method is legal before an opener and during a prompt.
@@ -162,7 +165,7 @@ The values above are illustrative. Thinking is one of `off`, `minimal`, `low`, `
 
 A client opts into the first extension event with `initialize.params.clientCapabilities._meta["clio-coder/events"]={version:1,kinds:["safety.loopBlocked"]}`. The kinds array has at most 16 strings, each at most 64 UTF-8 bytes and C0/DEL-free; a malformed opt-in is ignored. Unknown bounded versions and kinds are ignored. Without a recognized opt-in, no `clio-coder/event` notification is sent.
 
-The v1 notification is `{version,workspaceInstanceId,sessionId,turnId,sequence,kind,terminal,payload}`. `workspaceInstanceId` is one opaque process UUID advertised at initialize, and `sequence` increases monotonically within it. The only kind is `safety.loopBlocked`, is emitted only during the hosted active prompt, and has `terminal:false`. Its payload is `{toolCallId:null,tool,repeatCount,blocksThisTurn,budget,disposition,interrupted,shape:null}`. Disposition is `block`, `lockout`, or `stop`, and `interrupted` is true exactly for `stop`. The detector fires before the blocked call executes, so no honest ACP tool-call id exists; the bus has no disclosure-safe normalized shape. Both fields therefore remain null rather than being fabricated.
+The v1 notification is `{version,workspaceInstanceId,sessionId,turnId,sequence,kind,terminal,payload}`. `workspaceInstanceId` is one opaque process UUID advertised at initialize, and `sequence` increases monotonically within it. Recognized kinds are `safety.loopBlocked`, `dispatch.enqueued`, `dispatch.started`, `dispatch.progress`, `dispatch.completed`, `dispatch.failed`, and `accountability.evidenceReady`. A loop-blocked event is emitted only during the hosted active prompt and has `terminal:false`. Its payload is `{toolCallId:null,tool,repeatCount,blocksThisTurn,budget,disposition,interrupted,shape:null}`. Disposition is `block`, `lockout`, or `stop`, and `interrupted` is true exactly for `stop`. The detector fires before the blocked call executes, so no honest ACP tool-call id exists; the bus has no disclosure-safe normalized shape. Both fields therefore remain null rather than being fabricated. Dispatch events carry bounded run and agent identity plus the small lifecycle counters or terminal taxonomy appropriate to their kind; completed and failed events set `terminal:true`. Enqueued and started events may include `taskPreview`, a control-character-stripped prefix bounded to 160 UTF-8 bytes. The exact task and raw progress or failure prose never cross this boundary. An `accountability.evidenceReady` event follows the terminal event of a run whose evidence bundle has landed and sets `terminal:true`. Its payload is `{runId,evidenceId,firstPassSuccess,findingCount,tags}`, the same summary the observability projection attaches to the run, published once by the observability extension on the `accountability.evidenceReady` bus channel. Tags are at most 32 bounded identifiers of at most 64 bytes; the bundle's findings and overview prose never cross. A run whose build failed sends nothing, so the absence of the event means only that no bundle is ready.
 
 ### Prompt input
 
@@ -176,14 +179,14 @@ Every frame the server writes is bounded (`src/engine/acp/types.ts`). Every cap
 - Tool `content` text is truncated at 16 KiB with a trailing `…[truncated]`.
 - Live tool titles are at most 512 UTF-8 bytes. The bound applies identically to `tool_call`, `tool_call_update`, and `session/request_permission`; replay titles retain their stricter 64-byte stored-data bound.
 - Every string inside `rawInput` and `rawOutput` is truncated at 4 KiB with the same marker, and the walk stops at depth 8, replacing anything deeper with `"[depth]"`. The marker is reserved inside the cap, so a truncated value is at most the cap itself. If the bounded record still serializes past 32 KiB of UTF-8 it becomes `{"truncated":true,"bytes":<serialized UTF-8 length>}`, where the length is the record's serialization before any bounding, so the figure names the payload the engine produced rather than the shortened copy that was not sent. A record that does not serialize at all reports the bounded copy's length, or `0` when neither form serializes.
-- Every `toolCallId` is at most 128 UTF-8 bytes. An engine id longer than that, a missing one, or one that collides with an alias this turn already minted is replaced by a per-turn `clio-tool-<n>` alias, and the same alias is used for the call's `tool_call`, its `tool_call_update`, and its permission request, so one call never splits into two identities on the client. Identity runs one way: each engine tool-call id maps to exactly one emitted call. A turn that starts a second call under an engine id it already used mints a fresh alias for it rather than reusing the earlier wire id, so two calls never merge into one, and a `tool_execution_end` closes that id's most recently opened call first. An end that names an engine id is confined to that engine id's own calls: an id this turn never started binds to nothing, and the end is dropped and reported on the stderr tail rather than borrowing another call's wire id, which reported one tool's result under another tool's identity and closed a call that was still running. Every wire id receives exactly one terminal update. Once a `tool_call_update` with `completed` or `failed` has gone out for an id, the cancel/fail sweep included, that id never receives another, and a late or duplicate end for it is dropped and reported on the stderr tail instead of overwriting the result the client already rendered. An end arriving with no engine id binds to the most recently opened call still running, which is what makes a nested lifecycle close correctly: with an outer and an inner call open and the inner one already ended, the next unidentified end is the outer call's. With nothing still open it binds to the most recently emitted call of the turn, which drops it when that call is already terminal, and an end arriving before the turn has emitted any `tool_call` is dropped outright. Nothing on the end path mints a wire id, so a `tool_call_update` never announces an id the client never saw start.
+- Every `toolCallId` is at most 128 UTF-8 bytes. An engine id longer than that, a missing one, or one that collides with an alias this turn already minted is replaced by a per-turn `clio-coder-tool-<n>` alias, and the same alias is used for the call's `tool_call`, its `tool_call_update`, and its permission request, so one call never splits into two identities on the client. Identity runs one way: each engine tool-call id maps to exactly one emitted call. A turn that starts a second call under an engine id it already used mints a fresh alias for it rather than reusing the earlier wire id, so two calls never merge into one, and a `tool_execution_end` closes that id's most recently opened call first. An end that names an engine id is confined to that engine id's own calls: an id this turn never started binds to nothing, and the end is dropped and reported on the stderr tail rather than borrowing another call's wire id, which reported one tool's result under another tool's identity and closed a call that was still running. Every wire id receives exactly one terminal update. Once a `tool_call_update` with `completed` or `failed` has gone out for an id, the cancel/fail sweep included, that id never receives another, and a late or duplicate end for it is dropped and reported on the stderr tail instead of overwriting the result the client already rendered. An end arriving with no engine id binds to the most recently opened call still running, which is what makes a nested lifecycle close correctly: with an outer and an inner call open and the inner one already ended, the next unidentified end is the outer call's. With nothing still open it binds to the most recently emitted call of the turn, which drops it when that call is already terminal, and an end arriving before the turn has emitted any `tool_call` is dropped outright. Nothing on the end path mints a wire id, so a `tool_call_update` never announces an id the client never saw start.
 - `locations` carries the absolute path for the built-in path-bearing tools (`read`, `write`, `edit`, `ls`, `grep`, `find`) when the arguments name one, resolved against the pinned workspace and deliberately not realpath'ed, since an `edit` or `write` target may not exist yet. Each emitted path is at most 4 KiB of UTF-8, with `…[truncated]` inside that budget when the resolved value is longer. The exact bounded snapshot is reused by `session/request_permission`. When there is no recognizable path the field is omitted entirely rather than sent as `null` or `[]`.
 - A live prompt emits at most 128 `tool_call` starts. On the next start the server emits no 129th call, cancels the underlying Clio turn, suppresses subsequent chat events, terminally fails every already-rendered open call, and resolves `session/prompt` with standard stop reason `max_turn_requests`. This stop reason is emitted by the ACP bridge only for that presentation ceiling; Clio's separate configurable execution guard remains an engine policy rather than a wire-cardinality promise.
 - A cancelled or failed turn synthesizes a `tool_call_update` with `status: "failed"` for every call that received a `tool_call` and no terminal update, before the prompt request settles.
 
 ### Admission failure
 
-A prompt Clio cannot start fails with `prompt_not_admitted` and zero preceding `session/update` notifications. `data.reason` is one of `orchestrator-not-configured`, `target-unknown`, `target-not-configured`, `target-not-found`, `runtime-not-registered`, `model-not-configured`, `chat-unsupported`, `streaming-unsupported`, or the catch-all `admission-failed`. That list is closed and the server enforces it: the engine's runtime-resolution diagnostics are a larger and faster-moving vocabulary (`runtime-target-unsupported`, `runtime-use-unsupported`, `required-capability-missing`, and others), and any reason outside the list is reported as `admission-failed` rather than teaching clients a code the profile never promised. The two halves of an unconfigured orchestrator are distinguished: no `orchestrator.target` reports `orchestrator-not-configured`, and a configured target with no `orchestrator.model` reports `model-not-configured`, so a client is pointed at the half of the settings that is actually missing. The message is a sanitized one-line sentence and never contains the settings path. A failure after admission fails with `turn_failed` instead. Readiness before the first prompt is unchanged and lives in the CLI: `paths --json` for home identity, `doctor --json` for installation sanity, and `targets --json [--probe]` for target, auth, and health. `--probe` performs a request to the configured endpoint, so the client decides when that is allowed.
+A prompt Clio cannot start fails with `prompt_not_admitted` and zero preceding `session/update` notifications. `data.reason` is one of `orchestrator-not-configured`, `target-unknown`, `target-not-configured`, `target-not-found`, `runtime-not-registered`, `model-not-configured`, `chat-unsupported`, `streaming-unsupported`, or the catch-all `admission-failed`. That list is closed and the server enforces it: the engine's runtime-resolution diagnostics are a larger and faster-moving vocabulary (`runtime-target-unsupported`, `runtime-use-unsupported`, `required-capability-missing`, and others), and any reason outside the list is reported as `admission-failed` rather than teaching clients a code the profile never promised. The two halves of an unconfigured orchestrator are distinguished: no `chat.target` reports `orchestrator-not-configured`, and a configured target with no `chat.model` reports `model-not-configured`, so a client is pointed at the half of the settings that is actually missing. The message is a sanitized one-line sentence and never contains the settings path. A failure after admission fails with `turn_failed` instead. Readiness before the first prompt is unchanged and lives in the CLI: `paths --json` for home identity, `doctor --json` for installation sanity, and `targets --json [--probe]` for target, auth, and health. `--probe` performs a request to the configured endpoint, so the client decides when that is allowed.
 
 ### Permission requests
 
@@ -204,40 +207,53 @@ The shipped `clio-coder acp` composition supplies the session, settings, provide
 | `clio-coder/session` | `initialize` → `agentCapabilities._meta` | `{ close:true, list:true, label:true, delete:true, autonomy:true }` |
 | `clio-coder/settings` | `initialize` → `agentCapabilities._meta` | `{ get_safe:true, patch_safe:true }` |
 | `clio-coder/targets` | `initialize` → `agentCapabilities._meta` | `{ list:true, probe:true }` |
-| `clio-coder/events` | `initialize` → `agentCapabilities._meta` | `{ version:1, notification:"clio-coder/event", kinds:["safety.loopBlocked"], workspaceInstanceId }` |
+| `clio-coder/agent` | `initialize` → `agentCapabilities._meta` | `{ version:1, meta:"clio-coder/agent" }`, advertising per-frame agent attribution. |
+| `clio-coder/agent` | live and replayed `session/update.params._meta` | An array beginning with orchestrator attribution and including bounded delegated-agent attribution for a tool call when available. |
+| `clio-coder/events` | `initialize` → `agentCapabilities._meta` | `{ version:1, notification:"clio-coder/event", kinds:["safety.loopBlocked","dispatch.enqueued","dispatch.started","dispatch.progress","dispatch.completed","dispatch.failed","accountability.evidenceReady"], workspaceInstanceId }` |
 | `clio-coder/session` | `session/new` / `session/load` result `_meta` | Bind-time `{sessionId,target,model,autonomy,createdAt,resumed,replayed?}` attribution. |
 | `clio-coder/replay` | replayed `session/update.params._meta` | `{ turn }`; absent on live updates. |
 | `clio-coder/truncated` | `clio-coder/targets/list` or `clio-coder/session/list` result `_meta` | `true` only when that method's aggregate byte budget omitted a target/model entry or session row; absent otherwise. |
 | `clio-coder/tools` | `initialize` → `agentCapabilities._meta` | `"mediated"` |
-| `clio-coder/usage` | `session/prompt` result `_meta` | `{ input, output, cacheRead, cacheWrite, reasoning }` |
+| `clio-coder/usage` | `session/prompt` result `_meta` | `{ input, output, cacheRead, cacheWrite, reasoning, totalTokens, costUsd }` |
 | `clio-coder/error` | any `error.data._meta` | `{ version, code, reason?, supported? }` |
 
 ---
 
-## 5. Tool Mediation & Safety Governance
+## 5. Tool Presentation and Outbound Delegation Governance
 
-Tool execution entering through the ACP server is mediated by `src/engine/acp/tool-mediator.ts:createAcpToolMediator`.
+The hosted server presents ordinary Clio tool-registry activity to its client.
+Separately, when Clio delegates to an external ACP peer, it mediates that
+peer's permission requests before they can affect the workspace.
 
 ### Canonical Tool Mapping
 
-Clio tool names are mapped to the closed ACP `ToolKind` enumeration (`src/engine/acp/types.ts`):
+The hosted server maps Clio tool names to the closed ACP `ToolKind`
+enumeration in `src/engine/acp/server.ts`:
 
 | Clio Tool Name | ACP `ToolKind` | Primary Action Category |
 | :--- | :--- | :--- |
 | `read`, `ls`, `context` | `read` | Workspace inspection |
 | `write`, `edit`, `artifact` | `edit` | Workspace mutation |
 | `grep`, `find`, `code_nav` | `search` | Codebase exploration |
-| `bash`, `verify`, `git` | `execute` | Shell & command execution |
+| `bash`, `verify` | `execute` | Shell and verification execution |
 | `web_fetch` | `fetch` | Network retrieval |
-| Dynamic / MCP tools | `other` | Unmapped fallback |
+| `monitor` | `read` | Dispatch status inspection |
+| `git`, `dispatch`, `steer` | `other` | Specialized mapped tools |
+| `credential_present`, `tasks`, `ledger`, `panes`, `ask_user`, dynamic / MCP tools | `other` | Canonical or dynamic tools without a dedicated ACP mapping fall back to `other` |
 
-### Non-Stall Permission Mediation
+### Outbound Non-Stall Permission Mediation
 
-Under `clio-policy` governance:
+`src/engine/acp/adapter.ts` constructs `AcpToolMediator` when Clio acts as an
+ACP client for an outbound delegation. Under `clio-coder-policy` governance:
 1. Tool calls evaluate through the 10-step safety net policy engine.
 2. If the safety net or autonomy level yields an `ask` verdict (such as mutating actions at `suggest` level or unrecognized bash at `auto-edit` level), the mediator resolves the ask as a **non-stall denial** (`autonomyDenyRejection`).
 3. This non-stall behavior prevents external non-interactive client connections from hanging indefinitely while preserving safety boundaries.
 
+This outbound path is distinct from the hosted server's
+`installPermissionBridge`. The hosted server sends `session/request_permission`
+to its connected client and resumes a parked registry call when the client
+selects `allow-once`, subject to the timeout and binding rules above.
+
 ---
 
 ## 6. Security & Boundary Guarantees
@@ -254,7 +270,7 @@ The ACP boundary enforces strict isolation rules:
 
 The sections above describe Clio as an ACP server. In the other direction, Clio
 is an ACP client: `/delegate <agent-id> <task>` and any dispatch to an agent id
-configured under `delegation.agents` run the task on an external peer such as
+configured under `integrations.externalAgents.entries` run the task on an external peer such as
 `codex` or `opencode`.
 
 A delegated peer is a worker like any other on screen. The adapter maps the

package/docs/{alcf-provider.md → architecture/alcf-provider.md}

@@ -1,7 +1,7 @@
 # ALCF Inference Provider
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive target configurator and Globus OAuth flow diagram is located at [docs/html/alcf_blueprint.html](html/alcf_blueprint.html) (Version: 0.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [ALCF Inference Provider visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/alcf_blueprint.html).
 
 Clio can use Argonne's ALCF inference gateway as an OpenAI-compatible target
 backed by Globus OAuth. The runtime id is `alcf`; each configured target points
@@ -63,9 +63,12 @@ scientific apps:
 - `ProbeContext.authToken` carries a resolved stored/API/OAuth bearer into live
   probes so authenticated model discovery does not reach into auth storage.
 - ALCF rejects non-standard `chat_template_kwargs` request fields. The runtime
-  marks synthesized models with `clio.chatTemplateKwargsUnsupported`, and the
-  OpenAI-compatible engine adapter omits that field while still sending the
-  accepted top-level `reasoning_effort`.
+  currently marks synthesized models with
+  `clioCoder.chatTemplateKwargsUnsupported`, while the OpenAI-compatible engine
+  adapter still reads the released legacy `clio.chatTemplateKwargsUnsupported`
+  location. At this source revision the marker therefore does not guarantee
+  omission of `chat_template_kwargs`; the accepted top-level
+  `reasoning_effort` remains independent of that mismatch.
 
 Live model availability depends on which gateway jobs are running. The static
 model list is only a fallback for offline resolution; `clio-coder targets --probe`