@iowarp/clio-coder 0.4.7 → 0.4.9

package/dist/worker/entry.js

@@ -18,20 +18,25 @@ import {
   resolveDeliveryTools,
   sanitizeLockedSynthesisMessage,
   workerLoopBlockBudget
-} from "../chunk-CE64C5K5.js";
+} from "../chunk-ZF6CV4WZ.js";
 import {
   createMiddlewareContractFromSnapshot,
   createMiddlewareToolChoiceControl,
   shouldRequestStalledTurnContinuation
-} from "../chunk-MBJO5VNZ.js";
-import "../chunk-JABWPKFY.js";
+} from "../chunk-VPWGADBG.js";
 import {
   readLayeredSettings
-} from "../chunk-4MFBBY2Z.js";
-import "../chunk-CPXGJI2A.js";
-import "../chunk-MZHXENL7.js";
-import "../chunk-ZGIGW4ZG.js";
-import "../chunk-HRAKUPIH.js";
+} from "../chunk-W72LLZAV.js";
+import "../chunk-ACCECAH4.js";
+import "../chunk-HBJQQTKM.js";
+import "../chunk-JABWPKFY.js";
+import "../chunk-HCVKSGNZ.js";
+import "../chunk-PNJE7JPS.js";
+import "../chunk-L4RUTLRL.js";
+import "../chunk-PPIFDSBK.js";
+import "../chunk-TCUOGIL2.js";
+import "../chunk-PP23PZEV.js";
+import "../chunk-3A3CUMKA.js";
 import "../chunk-XCUDZQLX.js";
 import "../chunk-K2BLQC5E.js";
 import {
@@ -50,50 +55,13 @@ import {
   startAntigravityWorkerRun,
   startClaudeCodeWorkerRun,
   validateRehydratedWorkerRuntime
-} from "../chunk-NO7J45X6.js";
+} from "../chunk-4ATBOFRP.js";
 import {
   contextHash,
   messageToolCalls,
   seededWorkerMessages
-} from "../chunk-T4TY5GG3.js";
-import "../chunk-YPRSNUTC.js";
-import {
-  describeCallTarget
-} from "../chunk-2GPGAE5W.js";
-import "../chunk-OH3YYA3B.js";
-import "../chunk-24S3DN22.js";
-import "../chunk-SL2RDHKO.js";
-import "../chunk-YGDMBK7O.js";
-import "../chunk-V552WL53.js";
-import "../chunk-IZYTT3CD.js";
-import "../chunk-KECNXMDE.js";
-import "../chunk-WXA2CFJO.js";
-import "../chunk-GEVQNST4.js";
-import "../chunk-3LXJOICS.js";
-import "../chunk-L4N3DWNW.js";
-import "../chunk-BAU36233.js";
-import {
-  UNKNOWN_RESOURCE,
-  WORKER_PROTOCOL_VERSION,
-  WORKER_RESOURCE_LABEL_MAX,
-  WORKER_STDIN_FRAME_MAX_BYTES,
-  canonicalJson,
-  encodeControlFrame,
-  endpointIdentityHash,
-  knownResource,
-  parseAgentLedgerBody,
-  parseAgentLedgerEntry,
-  toolSignatureOf,
-  withinFrameBudget,
-  workerSpecDigest
-} from "../chunk-VQD7NH7Z.js";
-import {
-  deleteInjectedCompileCacheFrom
-} from "../chunk-CKK25WN3.js";
-import "../chunk-O3VV6IVK.js";
-import {
-  agentSkillToolPolicy
-} from "../chunk-KAFMW7WM.js";
+} from "../chunk-MO65K5CH.js";
+import "../chunk-KOAHT3N2.js";
 import {
   CONFIRMED_SCOPE,
   READONLY_SCOPE,
@@ -101,11 +69,18 @@ import {
   createLoopState,
   isSubset,
   observe
-} from "../chunk-BQQ5MXUC.js";
+} from "../chunk-AY4XE6GN.js";
+import "../chunk-555E2WVV.js";
+import "../chunk-OH3YYA3B.js";
+import "../chunk-6TKOFFGE.js";
 import {
-  createSafetyPolicyEngine
-} from "../chunk-DLIYANB7.js";
-import "../chunk-24TOGHPO.js";
+  effectiveToolCall
+} from "../chunk-2JBZYUPY.js";
+import {
+  describeCallTarget
+} from "../chunk-XNIZBOFV.js";
+import "../chunk-XZWSP67B.js";
+import "../chunk-H6IUCY6Q.js";
 import {
   FileKnowledgeBase,
   applyModelCapabilityPatch,
@@ -118,74 +93,63 @@ import {
   setGlobalDefaultMaxOutputTokens,
   setProtectedModelsProvider,
   setResidencyNoticeSink
-} from "../chunk-WT5TRMO4.js";
+} from "../chunk-4HFJKRGZ.js";
 import "../chunk-MCJKEGHO.js";
+import "../chunk-CTGZCEI6.js";
+import "../chunk-RL7LJYN4.js";
 import {
   estimateAgentContextBreakdown,
   estimateAgentMessageTokens
-} from "../chunk-77CZRFTE.js";
-import "../chunk-BO4XV5VX.js";
-import "../chunk-VTYHHQ57.js";
-import {
-  DEFAULT_AUTONOMY_LEVEL
-} from "../chunk-EM2WNQS2.js";
-import "../chunk-FQOOGXBH.js";
-import "../chunk-UHW5V7HC.js";
-import "../chunk-B6UM3OZC.js";
-import "../chunk-MYI32N4R.js";
-import "../chunk-KMF54VH3.js";
-import "../chunk-5A6XR3RJ.js";
+} from "../chunk-SJMNU4ZS.js";
+import "../chunk-W5RM7YAH.js";
 import "../chunk-EFSEIZE6.js";
-import "../chunk-B5ZTR6KZ.js";
-import "../chunk-6CB2IL4N.js";
-import "../chunk-3A3CUMKA.js";
-import {
-  registerBuiltinRuntimes
-} from "../chunk-SELG4SUR.js";
-import "../chunk-KS7ETA3P.js";
-import "../chunk-6TAATXXH.js";
-import "../chunk-VNBICSS2.js";
-import {
-  getRuntimeRegistry
-} from "../chunk-SRCEQKQS.js";
-import "../chunk-TN5FW4XY.js";
+import "../chunk-SL2RDHKO.js";
+import "../chunk-YGDMBK7O.js";
+import "../chunk-JURMQWVJ.js";
+import "../chunk-IZZI3SKQ.js";
+import "../chunk-ZKQ63XZ5.js";
 import {
-  engineStreamSimple,
-  registerFauxFromEnv
-} from "../chunk-5CMARGPF.js";
-import "../chunk-DXVMLM3Z.js";
-import "../chunk-SER7RRAE.js";
+  createSafetyPolicyEngine
+} from "../chunk-IC7JXLOM.js";
+import "../chunk-X6FLVUM5.js";
+import "../chunk-GHXGMFQ5.js";
+import "../chunk-KECNXMDE.js";
+import "../chunk-WXA2CFJO.js";
+import "../chunk-KP5BPXR3.js";
 import {
   RESULT_CONTRACT_REPAIR_LIMIT,
   parseWorkerResultContract,
   resultContractRepairMessages,
   validateResultContract
-} from "../chunk-34XHRVKG.js";
+} from "../chunk-I47EJPYL.js";
 import "../chunk-XW2UZICE.js";
 import {
   readSettings
-} from "../chunk-4QKAITQT.js";
+} from "../chunk-FPS4R2RN.js";
 import "../chunk-DVNAPPXU.js";
 import "../chunk-5EQO5NWP.js";
 import {
   classify
-} from "../chunk-HOX4YZ2K.js";
+} from "../chunk-H2WSCZZT.js";
 import {
   protectedArtifactMutationBlockReason
-} from "../chunk-2O2LVQQK.js";
+} from "../chunk-SQBT46OF.js";
 import "../chunk-KQ6IDQIB.js";
-import "../chunk-GH5ZR6JP.js";
+import "../chunk-L4N3DWNW.js";
+import "../chunk-YQYINEJI.js";
+import "../chunk-H72DCH3E.js";
+import "../chunk-2KUBKL63.js";
+import "../chunk-MYI32N4R.js";
 import "../chunk-R2P2U3ZS.js";
 import "../chunk-NTTS3O53.js";
 import "../chunk-M4KFUXS7.js";
 import {
   ToolNames
-} from "../chunk-WLHX3MM5.js";
-import "../chunk-GD55RTIW.js";
+} from "../chunk-V4XJWDHR.js";
 import {
-  readClioVersion
-} from "../chunk-E3LEPLQ2.js";
-import "../chunk-3XE4NRLF.js";
+  registerBuiltinRuntimes
+} from "../chunk-NPLLK3HO.js";
+import "../chunk-ZKJU55MX.js";
 import "../chunk-U2MSJ57E.js";
 import {
   configureGuardrails,
@@ -193,7 +157,38 @@ import {
   isWorkerToolCallCapExceededReason,
   isWorkerToolCallCapSynthesisReason
 } from "../chunk-C27U2TYG.js";
-import "../chunk-GJ24ODAX.js";
+import "../chunk-EM2DIQAJ.js";
+import "../chunk-ZKVMDNAN.js";
+import "../chunk-VNBICSS2.js";
+import "../chunk-B5GGDIHT.js";
+import {
+  getRuntimeRegistry
+} from "../chunk-SRCEQKQS.js";
+import "../chunk-JIYWMQZ5.js";
+import {
+  engineStreamSimple,
+  registerFauxFromEnv
+} from "../chunk-UIU7MGZ3.js";
+import "../chunk-DXVMLM3Z.js";
+import {
+  UNKNOWN_RESOURCE,
+  WORKER_PROTOCOL_VERSION,
+  WORKER_RESOURCE_LABEL_MAX,
+  WORKER_STDIN_FRAME_MAX_BYTES,
+  canonicalJson,
+  encodeControlFrame,
+  endpointIdentityHash,
+  knownResource,
+  parseAgentLedgerBody,
+  parseAgentLedgerEntry,
+  toolSignatureOf,
+  withinFrameBudget,
+  workerSpecDigest
+} from "../chunk-VQD7NH7Z.js";
+import {
+  deleteInjectedCompileCacheFrom
+} from "../chunk-CKK25WN3.js";
+import "../chunk-XTQ7MEJG.js";
 import {
   setGitCommitAttributionEnabled,
   withManagedGitCommitAttributionEnvironment
@@ -202,15 +197,30 @@ import "../chunk-6EXUUOSN.js";
 import {
   AI_AGENT_NAME
 } from "../chunk-ZTNFYMIO.js";
+import {
+  agentSkillToolPolicy
+} from "../chunk-NBPA5QM6.js";
+import {
+  DEFAULT_AUTONOMY_LEVEL
+} from "../chunk-EM2WNQS2.js";
+import "../chunk-O3VV6IVK.js";
 import "../chunk-DVJL77SO.js";
+import "../chunk-3RDHGNU7.js";
+import "../chunk-UHW5V7HC.js";
+import "../chunk-KMF54VH3.js";
+import "../chunk-SER7RRAE.js";
+import "../chunk-GH5ZR6JP.js";
 import "../chunk-TK2BMCBZ.js";
-import "../chunk-B5GGDIHT.js";
+import {
+  clioStateDir
+} from "../chunk-CTTI7G3T.js";
 import {
   safeResourceWrite
 } from "../chunk-ZZFWWYLX.js";
+import "../chunk-GD55RTIW.js";
 import {
-  clioStateDir
-} from "../chunk-CTTI7G3T.js";
+  readClioVersion
+} from "../chunk-E3LEPLQ2.js";
 import {
   init_esm_shims
 } from "../chunk-ECBHH7LU.js";
@@ -291,8 +301,9 @@ function createWorkerContextGuard(archive) {
         const projected = { ...message, content };
         replace(index, message, projected);
       } else if (message.role === "toolResult" && !message.isError) {
-        const name = toolCalls.get(message.toolCallId)?.name;
-        if (!name || !["read", "grep", "find", "ls", "code_nav", "web_fetch"].includes(name)) continue;
+        const call = toolCalls.get(message.toolCallId);
+        const name = call ? effectiveToolCall(call.name, call.arguments).toolName : void 0;
+        if (!name || !["read", "grep", "find", "ls", "code_nav", "web_read", "web_fetch"].includes(name)) continue;
         if (JSON.stringify(message.content).length < 1e3) continue;
         const ref = key(message);
         const file = archive(ref, structuredClone(message));
@@ -1343,6 +1354,9 @@ function startWorkerRun(input, emit) {
       correlationId: `worker-model-round-${workerModelRound}`,
       toolResultMaxBytes: workerSettings.context.toolResultMaxBytes,
       supportsImages: model.input.includes("image"),
+      // The admitted capability list, so the gateway calls only what the
+      // recipe declared: the same bound the attached schemas already honor.
+      allowedTools: input.allowedTools,
       ...agentSkillPolicy ? { pendingSkillPolicy: agentSkillPolicy } : {}
     })
   });

package/docs/README.md

@@ -4,9 +4,6 @@
 
 # Clio Coder documentation
 
-> **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).
-
 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.
@@ -23,8 +20,7 @@ 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
+└── history/        Dated records that are not current guidance
 ```
 
 ## Start here
@@ -36,7 +32,10 @@ docs/
 | 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:
+A minimal first run needs Node.js 22.19 or newer and a model to talk to: a
+local inference server such as Ollama or LM Studio, a lab gateway, or a cloud
+API. Quick Connect asks for the endpoint, a key when the server needs one, and
+a model.
 
 ```bash
 npm install -g @iowarp/clio-coder
@@ -184,15 +183,13 @@ Clio's documentation ships with Clio, not with your workspace. Everything below
 resolves from the installed package root (`resolvePackageRoot()`,
 `src/core/package-root.ts`), never from the directory you launched in.
 
-**What is indexed.** Every `.md` file under `<package-root>/docs/`, excluding
-`docs/html/`, plus root `README.md`, `CHANGELOG.md` and `CLIO-CODER.md` when each
-of those exists. The npm package ships `docs/**/*.md`, `README.md` and
-`CHANGELOG.md`; it does not ship `docs/html/` or a root `CLIO-CODER.md`, so in an
-npm install the blueprints are absent and the handbook is indexed only when you
-are running from a source checkout. The index is deterministic and needs no
+**What is indexed.** Every `.md` file under `<package-root>/docs/`, plus root
+`README.md`, `CHANGELOG.md` and `CLIO-CODER.md` when each exists. The npm package
+ships the Markdown reference used by both the application and agents. A root `CLIO-CODER.md` is indexed
+only when present, such as in a source checkout. The index is deterministic and needs no
 network or embedding service (`src/tools/context/docs-engine.ts`).
 
-**Searching and then reading.** `context(scope="docs", query="…")` returns
+**Searching and then reading.** `gateway(op="call", capability="clio_docs", args={query: "…"})` returns
 section headings with citations such as `docs/architecture/safety-model.md`.
 Citations are **package-relative**, and this is the step that matters when the
 workspace is someone else's repository: reading `docs/architecture/safety-model.md`
@@ -208,27 +205,31 @@ root**, which is that directory's parent. So when the prompt names `/pkg/docs`:
 Do not duplicate the `docs/` segment, and do not resolve a citation against the
 workspace. Omitting `query` lists the corpus instead of searching it.
 
-**The blueprint viewer.** `clio-coder docs` serves `docs/html/` from the package
-root on `127.0.0.1:<port>`. It does not look at your current directory and does
-not check whether you are in a Git checkout: the only question is whether the
-installed package has those files. When it does not, the command prints the
-packaged Markdown path and a link to the blueprints on GitHub instead of starting
-a server.
+**The web documentation.** `clio-coder docs` opens the documentation map in the
+Clio Coder web app. `clio-coder docs safety` opens the safety guide. It resolves
+content from the installed package, independent of your current project, and
+reuses this installation's background app when configured. Otherwise it starts
+a foreground loopback server; press Ctrl+C to stop. `--no-open` prints the private
+launch link without opening a browser. The command never installs a service.
+
+## Reading in the application
 
-## Interactive blueprints
+The GUI renders these Markdown sources directly with the application's theme,
+syntax highlighting, copy controls, tables and diagrams. Navigation groups come
+from this map, search indexes the same pages, and each page's outline is generated
+from its headings. Internal references stay in the application.
 
-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:
+Edit the Markdown once to update both human and agent documentation. There is
+no separate HTML source tree, document server, or alternate reading view.
 
 ```bash
 clio-coder docs
+clio-coder docs safety
+clio-coder docs guide/configuration-reference.md --no-open
 ```
 
-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.
+The Markdown files remain the portable reference for the CLI, agents, editors,
+and repository readers. Opening documentation does not require a model connection.
 
 ## Writing documentation
 

package/docs/architecture/acp.md

@@ -1,8 +1,5 @@
 # Agent Client Protocol (ACP) Server
 
-> **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`.
@@ -14,11 +11,10 @@ Source implementations: `src/engine/acp/` and `src/cli/acp.ts`.
 Clio Coder provides a native ACP server via the `clio-coder acp` command. The server implements the open Agent Client Protocol specification (ACP v1 / schema 0.4.5) over standard I/O JSON-RPC 2.0 transport (`src/engine/acp/transport.ts`).
 
 The ACP server allows external IDEs, editors (such as Zed), and automated orchestration engines to drive Clio Coder sessions over a structured protocol.
-The source tree includes the `apps/workbench` localhost desktop client. Its ACP
-adapter supports session browsing and deletion, safe settings, target probes,
-usage, recovery, evaluation inventory, routing and dispatch inspection, toolchain
-status, agent attribution, and the live fleet event strip. The workbench is a
-source application and is not included in the published CLI package.
+The source tree includes the `apps/clio-coder-web` application, which supervises
+ACP children and exposes session operations through authenticated local REST and
+SSE. The earlier `apps/workbench` client is retained as reference source and is
+excluded from workspace builds, publication, and product gates.
 
 ```mermaid
 graph LR
@@ -186,7 +182,7 @@ Every frame the server writes is bounded (`src/engine/acp/types.ts`). Every cap
 
 ### 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 `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.
+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`, `authentication-required`, 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. The server checks credential availability through the provider auth contract before admitting a prompt; `authentication-required` carries no environment-variable name, credential, or provider prose. A background service does not inherit terminal-only API keys: save the key with `clio-coder auth login <target>`, then close and reopen the session. Other readiness checks before the first prompt live 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
 

package/docs/architecture/alcf-provider.md

@@ -1,8 +1,5 @@
 # ALCF Inference Provider
 
-> **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
 at one gateway cluster URL, such as Sophia or Metis.

package/docs/architecture/architecture.md

@@ -1,8 +1,5 @@
 # Clio Coder Architecture and Boundaries
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Clio Coder Architecture and Boundaries visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/architecture_blueprint.html).
-
 Clio Coder is an experimental, terminal-first coding harness for the CLIO ecosystem. CLIO stands for Context Layer for Input/Output; the project is named for the Greek muse of history and developed by the Gnosis Research Center at Illinois Tech. Its architecture favors small, auditable subsystems over a single monolithic agent loop: CLI entry points, the interactive TUI, provider/runtime code, worker subprocesses, tools, and feature domains are kept separate so local-model support and scientific-software workflows can evolve without collapsing safety boundaries.
 
 This page is source-code aligned for the current source tree.

package/docs/architecture/artifact-placement.md

@@ -1,8 +1,5 @@
 # Artifact Placement
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Artifact Placement visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/artifact_placement_blueprint.html).
-
 Every file Clio generates has one home, decided by who reads it. The rule that
 follows from that: **the repo working tree holds files a human asked for.**
 Anything Clio produced on its own initiative lands in the project-local
@@ -38,6 +35,7 @@ Markdown.
 | Task-memory handoffs | `.clio-coder/handoffs/` | Agent-to-agent |
 | Dispatch proposals | `.clio-coder/proposals/` | Agent-to-agent |
 | Compete worktrees | `.clio-coder/worktrees/` | Agent-to-agent |
+| Script runs | `.clio-coder/runs/<runId>/` | Human transient and provenance |
 | Tool-result and harness scratch | XDG state `scratch/`, with tool offloads grouped by session | Agent-to-agent |
 | Evidence bundles | XDG data `evidence/` | Human transient (`clio-coder evidence`) |
 | Approved memory | XDG data `memory/` | Human transient (`clio-coder memory`) |
@@ -52,7 +50,7 @@ Markdown.
 
 ## The `artifact` tool default
 
-`artifact(kind: plan|review|report)` without a `path` writes to
+`gateway(op="call", capability="artifact", args={kind: "plan"|"review"|"report", content: ...})` without a `path` writes to
 `.clio-coder/artifacts/` under the workspace root. Passing `path` writes exactly
 there instead, working tree included, because a path the user named is a file
 the user asked for. A path that escapes the workspace is refused.
@@ -65,6 +63,16 @@ that prediction impossible and leave the safety layer guarding a path nobody
 writes. The consequence is one file per kind: a second report overwrites the
 first. Keep several by naming explicit paths.
 
+## Script run records and retention
+
+`run_script` creates `.clio-coder/runs/<runId>/` with `stdout.log`, `stderr.log`, and an atomically written `run.json` manifest (version 1). The id is a UTC timestamp plus six random hexadecimal characters. Source: `src/core/run-records.ts` and `src/tools/run-script.ts`.
+
+The manifest records script path, canonical path, byte size and SHA-256, interpreter name/resolved path/arguments, exact argv, workspace-relative cwd, timeout, start/end times and duration, environment key names, outcome, effective `exitCode`, observed `leaderExit`, signal, stream byte counts, log paths, input identities, output status, `cleanup`, and `pipeDrainIncomplete`. Environment values are never recorded there. Regular-file hashes cover at most 64 MiB; omitted hashes carry `too-large`, `cancelled`, or `unreadable`. These are observed identities, not immutable snapshots. Logs stream to disk and have no total byte ceiling; bounded terminal tails are not the full log.
+
+Failure does not erase partial logs or outputs. Outcomes include `cleanup-incomplete` and `pipe-drain-incomplete`, with effective failure even if the leader exited zero. The first means original-group teardown could not be confirmed; the second means the one-second post-exit drain bound expired. Escaped processes can remain alive and outputs can still change. See [execution and cleanup](../guide/tool-usage.md#run_script-stream-a-scientific-processing-step-to-disk).
+
+After each run, `sweepRunRecords` keeps the newest 100 completed records by completion time. Recent manifest-less directories are treated as active; those at least 24 hours old are orphan candidates. Retention reads at most 64 KiB per manifest in chunks of at most 8 KiB. Oversized or malformed regular manifests fall back to opened-file mtime for ordering. Nonregular manifests, symlinked run directories, changed identities, and inaccessible entries are explicitly skipped and counted, not followed or silently removed. The sweep reports `removed`, `kept`, `active`, and `skipped`. This bounds metadata reads, not total directory enumeration or disk usage. Preserve needed evidence outside this retention tree before it ages out.
+
 ## `.clio-coder/` and git
 
 `clio-coder context init` checks for a blanket `.clio-coder/` ignore. With

package/docs/architecture/artifact-versions.md

@@ -1,8 +1,5 @@
 # Artifact Versions & Serialization Contracts
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Artifact Versions & Serialization Contracts visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/artifact_versions_blueprint.html).
-
 This document is an operator-facing registry of compatibility-sensitive file
 formats, serialized structures, integrity digests, and migration rules in the
 current source tree. It is not an exhaustive inventory of every internal store

package/docs/architecture/capacity-and-scheduling.md

@@ -1,8 +1,5 @@
 # Capacity Leases & Fleet Scheduling
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Capacity Leases & Fleet Scheduling visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/capacity_scheduling_blueprint.html).
-
 This document specifies the multi-process capacity leasing protocols, node
 scheduling models, cross-process transaction locks, and failure recovery
 mechanics in the current source tree.

package/docs/architecture/context-engine.md

@@ -1,8 +1,5 @@
 # Context Engine
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Context Engine visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/context_blueprint.html).
-
 Clio Coder tracks context pressure, records per-turn snapshots, and protects the provider context with bounded tool results plus single-threshold compaction.
 
 Source of truth lives in `src/domains/session/context-accounting.ts`, `src/domains/session/context-ledger.ts`, `src/domains/session/compaction/`, `src/domains/context/working-set/`, `src/domains/session/migrations/index.ts`, and the chat-loop integration in `src/interactive/chat-loop.ts`.

package/docs/architecture/context-working-set.md

@@ -1,8 +1,5 @@
 # Working Set
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Working Set visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/context_working_set_blueprint.html).
-
 The working set is the part of the session ledger the model actually receives on the next request. When context pressure crosses `context.compaction.threshold`, Clio narrows that view before it considers summarizing anything: selected tool-result bodies and closed-turn thinking blocks stop being replayed, and a one-line marker takes each body's place. Nothing is deleted. The ledger keeps every byte the tools produced, the transcript keeps showing them, and the model can ask for any evicted body back by ref.
 
 Source of truth is `src/domains/context/working-set/` (`contract.ts`, `fold.ts`, `project.ts`, `marker.ts`, `protect.ts`, `engine.ts`, `recall.ts`, `policies/`), the ledger records in `src/domains/session/entries.ts`, and the compaction stage in `src/interactive/turn-context.ts` (`runAutoCompact`).

package/docs/architecture/dispatch-architecture-rationale.md

@@ -1,8 +1,5 @@
 # Dispatch Architecture Rationale
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Dispatch Architecture Rationale visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/dispatch_rationale_blueprint.html).
-
 Why `src/domains/dispatch/` is one domain, why one import out of it looks
 irregular and is allowed to, and why the repository has no barrel-only import
 convention. No code moved as a result of this document. It exists so that a

package/docs/architecture/dispatch-typed-intent.md

@@ -1,8 +1,5 @@
 # Typed Dispatch Intent: Migration and Refusal Policy
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Typed Dispatch Intent: Migration and Refusal Policy visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/dispatch_typed_intent_blueprint.html).
-
 Typed dispatch intent is the structured declaration of what a dispatched worker
 may read, may write, is expected to produce, and must verify. It replaces the
 practice of reconstructing that answer from optional `writeRoots` plus path-like

package/docs/architecture/evidence-and-memory.md

@@ -1,8 +1,5 @@
 # Evidence Corpus and Long-Term Memory
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Evidence Corpus and Long-Term Memory visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/memory_blueprint.html).
-
 Clio Coder treats run claims and agent lessons as structured artifacts to support reproducibility and scientific provenance. In evaluations such as [SWE-bench](https://www.swebench.com), capturing granular execution evidence is essential for validating agent claims. Evidence corpora are deterministic directories built from run ledgers, receipts, sessions, audits, and eval artifacts. Currently, forensic evidence auto-builds on dispatch run completion: when a run finalizes, the observability domain automatically compiles the evidence bundle under `<dataDir>/evidence/run-<id>/` and updates a compact sidecar index row in `<stateDir>/evidence-index.json`. Long-term memory records are local, evidence-linked, and only injected after explicit approval. Use the TUI [`/view`](observability.md) command for interactive inspection of receipts, dispatch output, durable tool output, compaction summaries, and session accountability before building or citing evidence.
 
 Source of truth: `src/domains/evidence/**`, `src/domains/memory/**`, `src/cli/evidence.ts`, and `src/cli/memory.ts`.

package/docs/architecture/library.md

@@ -1,7 +1,5 @@
 # Library architecture
 
-> **Visual blueprint:** See the [Library architecture visual reference](../html/library_blueprint.html) in the source checkout.
-
 Clio uses **library** for the collection and **package** for a distributable item. This name covers both local authoring and indexed distribution without suggesting a remote store or a purchase. CLI `library`, slash `/library`, the Library overlay and the bundled `library/registry.yaml` describe the same collection. The Pi API snapshot does not contain the retired command names, so top-level `plugins`, top-level `skills`, and `/resources` are removed rather than retained as aliases. Retired slash commands `/plugins` and `/resources` return an explicit usage error pointing to `/library` (for recipe packages) and `/extensions` (for harness extensions). Bare `/skill` returns usage guidance pointing to `/skills`, while `/skill <name>` activates a skill and `/skill off` clears the active skill's armed tool surface (without erasing instructions already loaded in transcript or context).
 
 ## Invariants
@@ -15,7 +13,7 @@ Clio uses **library** for the collection and **package** for a distributable ite
 7. **Trust follows origin.** `installLibraryPackage({kind, sourcePath, scope, origin, trust, ...})` is exported from `src/domains/plugins/index.ts`. Interop supplies a reviewed prepared tree, `{kind: "interop", host, source: absoluteOriginalPath}`, and `trust: "foreign"`. Skill and prompt loaders honor foreign trust at either scope. Generic updates and forced replacement of adopted content refuse until explicit removal and reviewed re-adoption.
 8. **Eval is an explicit action.** Named evals are contained suite files in the manifest. Installation does not execute them. `eval validate/run --package` resolves a local package or an active verified installation and includes package identity in suite provenance. Evals can execute authored commands in the declared workspace; validation alone does not execute them.
 9. **Operator authority remains separate from autonomy.** Recognized model shell calls cannot install, update, enable, disable or remove package content through the library. Read-only inspection and install/update dry-runs remain available. Interop adoption with `--yes` is likewise an operator action. Runtime offers and overlays commit only through their bound approval paths.
-10. **One inventory, two projections.** `src/domains/resources/library-inventory.ts` produces the bounded, body-free record of packages, scoped copies and actual recipe resources. The CLI reads it for `library recipes` and the model reads it through `context(scope="library")`; they agree about ownership, runtime name, scope, origin, availability and invocation because they are the same records. The model projection is narrower, not different: it is the model audience, so internal and shadow agents, untrusted, invalid, shadowed and manual-only resources are absent, and it drops absolute recipe paths. A catalog `provides` hint is projected as its own tagged row that names its installable owner and that member's honest state, and it never carries an invocation. Neither projection activates, installs, registers or pins anything, and neither fetches a remote source. A native worker registry has no admitted library projection and receives a clear unavailable read rather than the global library.
+10. **One inventory, two projections.** `src/domains/resources/library-inventory.ts` produces the bounded, body-free record of packages, scoped copies and actual recipe resources. The CLI reads it for `library recipes` and the model reads it through `gateway(op="call", capability="clio_library", args={})`; they agree about ownership, runtime name, scope, origin, availability and invocation because they are the same records. The model projection is narrower, not different: it is the model audience, so internal and shadow agents, untrusted, invalid, shadowed and manual-only resources are absent, and it drops absolute recipe paths. A catalog `provides` hint is projected as its own tagged row that names its installable owner and that member's honest state, and it never carries an invocation. Neither projection activates, installs, registers or pins anything, and neither fetches a remote source. A native worker registry has no admitted library projection and receives a clear unavailable read rather than the global library.
 
 ## Identity at runtime
 

package/docs/architecture/middleware-and-components.md

@@ -1,8 +1,5 @@
 # Middleware and Component Registry
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Middleware and Component Registry visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/middleware_blueprint.html).
-
 Clio Coder has two related but separate surfaces:
 
 1. **Components**: deterministic inventory of files that can affect harness behavior.

package/docs/architecture/model-catalog.md

@@ -1,8 +1,5 @@
 # Model Catalog, Runtime Refresh, and Field Notes
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Model Catalog, Runtime Refresh, and Field Notes visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/models_blueprint.html).
-
 Clio Coder treats a selectable model as the intersection of three sources:
 
 1. **Configured targets** in `settings.yaml` (`targets[]`, `defaultModel`, and optional `wireModels`).
@@ -225,7 +222,7 @@ When an LLM response is interrupted because it hits an output token limit during
    - Replay repair does not mutate saved session transcripts, original stop reasons, usage metrics, or thinking signatures.
    - If target model, provider, or API switches, or reasoning is turned off, this narrow request repair is skipped and existing conversion policy applies; opaque signatures and cross-model conversions retain their original provider semantics.
    - A per-response output-token cap does not cap total task tokens or guarantee completed task execution; existing repair and deadline limits continue to apply.
-   - Verified by contract suite `tests/contracts/reasoning-length-replay.test.ts`.
+   - Verified by contract suite `tests/extended/reasoning-length-replay.test.ts`.
 
 ---