@iowarp/clio-coder 0.3.0 → 0.3.1

package/docs/safety-model.md

@@ -1,7 +1,7 @@
 # Clio Coder Safety Model
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/safety_blueprint.html](html/safety_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/safety_blueprint.html](html/safety_blueprint.html) (Version: 0.3.1).
 
 Clio Coder's safety posture is code-enforced, not prompt-only. As the orchestrator coding agent in the [IOWarp](https://iowarp.ai) ecosystem developed by the [Gnosis Research Center](https://grc.iit.edu) at Illinois Tech under NSF Award [#2411318](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2411318), Clio gates execution by target capabilities, the tool registry, the safety policy engine, project policies, protected-artifact checks, and audit receipts.
 
@@ -13,7 +13,7 @@ Source of truth: `src/domains/safety/**`, `src/tools/registry.ts`, `src/tools/bo
 
 The `autonomy` setting (`read-only` | `suggest` | `auto-edit` | `full-auto`) is an enforced dial. It controls exactly one thing: which action classes run immediately, which park for operator approval, and which are auto-denied. The safety net (damage-control rules, path policy, protected artifacts, loop guard, dispatch scope admission) is independent of the dial and identical at every level. When a `[safety-net]` notice appears at full-auto, that is the always-on net working as designed, not a contradiction of the level.
 
-In Clio Coder v0.3.0, effective autonomy resolution is strictly centralized in `src/entry/orchestrator.ts` through `resolveEffectiveAutonomy` and `resolveBaselineAutonomy`. Every admission surface (tool registry admission, dispatch plan provenance, and ACP session snapshots) delegates to this pair of functions so that fallback paths cannot diverge across execution contexts. `resolveBaselineAutonomy` evaluates dispatch settings overrides, headless CLI options, and configuration settings before applying the default `auto-edit` level. `resolveEffectiveAutonomy` combines any active ACP session autonomy level with the baseline resolution.
+In Clio Coder v0.3.1, effective autonomy resolution is strictly centralized in `src/entry/orchestrator.ts` through `resolveEffectiveAutonomy` and `resolveBaselineAutonomy`. Every admission surface (tool registry admission, dispatch plan provenance, and ACP session snapshots) delegates to this pair of functions so that fallback paths cannot diverge across execution contexts. `resolveBaselineAutonomy` evaluates dispatch settings overrides, headless CLI options, and configuration settings before applying the default `auto-edit` level. `resolveEffectiveAutonomy` combines any active ACP session autonomy level with the baseline resolution.
 
 ### Autonomy levels
 
@@ -27,12 +27,15 @@ In Clio Coder v0.3.0, effective autonomy resolution is strictly centralized in `
 | `system_modify` | deny | ask | ask | ask |
 | `git_destructive` | net block | net block | net block | net block |
 | `unknown` | deny | ask | ask | ask |
+| `read`: a gate declaring `exposure: outward` | allow | ask | ask | allow |
 
 - **`read-only`**: Clio inspects and answers. Mutating calls are auto-denied with a rejection telling the model to propose the change instead; approvals are never invoked. Denials render as `[autonomy]` notices.
 - **`suggest`**: every non-read action parks for one-shot approval. The operator drives.
 - **`auto-edit`**: workspace edits and recognized commands run; unrecognized bash asks instead of blocking.
 - **`full-auto`**: bash runs without prompting; the net is the protection, not the prompt. `system_modify` still asks because it reaches outside the workspace; `unknown` still asks because the net cannot reason about calls it cannot classify.
 
+The exposure tier is the one row keyed by the call rather than by its action class. A call may declare `exposure: outward` when answering it publishes or sends something the operator cannot quietly take back: filing an issue or a PR, posting a comment, pushing a branch, cutting a release. Today `ask_user` is the only tool that declares one, so a skill marks its own confirmation step outward and `auto-edit` parks that gate for the operator instead of answering it. Acting on the workspace without asking is not the same permission as publishing without asking. `suggest` parks it too, because the dial is ordered and a stricter level must never gate a surface less than the looser one below it. `full-auto` answers outward gates like everything else, `read-only` still answers them because the outward effect being confirmed is denied there anyway, and the tier only ever adds an ask: it never widens a row the action class already denied. The tier is declared, never inferred, because only the caller knows whether the step it is confirming leaves the machine; a value the schema does not recognize reads as `outward` and the call is then rejected, so a misspelled tier costs one prompt rather than silently downgrading the gate.
+
 The `system_modify` confirm is level-invariant, so it is enforced and attributed as a safety-net confirm rail: the overlay, notices, and audit ledger name the net (reason code `system-modify-confirm`, policy source `builtin-classifier`), not the autonomy level. The matrix row above is unchanged in outcome at every level; only `read-only` converts the ask to a denial. `unknown` remains in the autonomy mapping because the registry substitutes a registered tool's base action class after the net evaluates.
 
 The level is persisted as `autonomy` in `settings.yaml`, hot-reloads, and is edited in the `/settings` Autonomy & Safety section.
@@ -72,7 +75,7 @@ Escalation can never hang a run. Every escalated ask resolves by an operator dec
 
 ## Operating Posture and Visible Tools
 
-Clio operates under a single operating posture with a standard, unified visible toolset. The 19 built-in tools are organized in seven planes; each plane is one policy unit for action class, size posture, and concurrency, asserted at bootstrap by `src/tools/policy.ts` so the classifier and the registered specs can never drift apart silently.
+Clio operates under a single operating posture with a standard, unified visible toolset. The 20 built-in tools are organized in seven planes; each plane is one policy unit for action class, size posture, and concurrency, asserted at bootstrap by `src/tools/policy.ts` so the classifier and the registered specs can never drift apart silently.
 
 | Plane | Tools | Action class |
 | --- | --- | --- |
@@ -137,7 +140,7 @@ Every tool call entering the safety engine passes through a strict 10-step evalu
 2. **Write-Root Containment**: Verifies that mutations remain within configured write boundaries (`evaluateWriteRoots`).
 3. **Hard Blocks**: Enforces unconditional blocks against destructive actions (such as `git_destructive` operations and zero-access credentials).
 4. **Invalid Project Policy Fail-Closed**: If `.clio-coder/safety.yaml` contains parsing or schema errors, execution tools fail closed.
-5. **Path Policy Enforcement**: Evaluates `zeroAccessPaths`, `readOnlyPaths`, and `noDeletePaths`.
+5. **Path Policy Enforcement**: Evaluates `zeroAccessPaths`, `readOnlyPaths`, `noWritePaths`, and `noDeletePaths`.
 6. **Bash Zero-Access Protocol**: Rejects shell commands attempting to read, exfiltrate, or redirect from protected credential files. A safe presence-check exception (`grep -sq "^NAME=" <file>`) is permitted for environment probing without exposing secrets.
 7. **Ask Rails**: Evaluates rules requiring confirmation (such as project `requireConfirmation` or unanalyzable command substitutions `$(...)`).
 8. **System Modify Checks**: Assesses operating-system level modification commands targeting system roots (`/etc`, `/usr`, `/var`, `/bin`, `/sbin`, `/run`), exempting temporary write paths (`/var/tmp`, `/var/folders`).
@@ -159,6 +162,8 @@ zeroAccessPaths:
   - .env
 readOnlyPaths:
   - vendor/
+noWritePaths:
+  - third_party/generated/
 noDeletePaths:
   - out/validated/
 commands:
@@ -181,7 +186,7 @@ commands:
 Accepted root keys:
 
 ```text
-version | commands | tasks | disableDefaultPathPolicy | zeroAccessPaths | readOnlyPaths | noDeletePaths
+version | commands | tasks | disableDefaultPathPolicy | zeroAccessPaths | readOnlyPaths | noWritePaths | noDeletePaths
 ```
 
 `tasks` is an alias for command policy entries. Unknown keys, wrong types, duplicate command IDs, absolute `cwd`, `..`-escaping `cwd`, and invalid path-policy entries make the policy invalid.
@@ -192,9 +197,20 @@ Path-policy behavior:
 | --- | --- |
 | `zeroAccessPaths` | Blocks read, write, and delete. |
 | `readOnlyPaths` | Allows read, blocks write/delete. |
+| `noWritePaths` | Allows read, blocks write/delete. Separate from `readOnlyPaths` so the default policy can name directories Clio reads as a matter of course and must never author. |
 | `noDeletePaths` | Blocks delete. |
 | `disableDefaultPathPolicy` | Uses only project path policy rather than merging default damage-control paths. Note: This cannot disable built-in zero-access protection for critical system paths like `.git/config` and `credentials.yaml`. |
 
+The default damage-control policy populates `noWritePaths` from the interop
+agent registry: `~/.claude/`, `.claude/`, `~/.codex/`, `.codex/`, `~/.config/opencode/`,
+`.opencode/`, `~/.gemini/`, `.gemini/`, `~/.copilot/`, `~/.cursor/`, `.cursor/`,
+`~/.antigravitycli/`, `.antigravitycli/`, `~/.agents/`, and `.agents/`. Clio never writes
+into another coding agent's directory. It reads those roots for skills, prompts, and
+rule prose and has no reason to author them. A `write` or `edit` targeting any of
+these paths is refused at every posture including `auto-edit` and `full-auto`, with reason
+code `path-policy:noWritePaths`. Reads remain allowed. `.clio-coder/` is Clio's own directory
+and is untouched. `.github/` is deliberately not blocked.
+
 Command entry notes:
 
 | Field | Meaning |

package/docs/scientific-validation.md

@@ -1,11 +1,11 @@
 # Clio Coder Scientific Validation Contracts
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive numerical tolerance calculator and HPC queue execution simulator is located at [docs/html/validation_blueprint.html](html/validation_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive numerical tolerance calculator and HPC queue execution simulator is located at [docs/html/validation_blueprint.html](html/validation_blueprint.html) (Version: 0.3.1).
 
 Scientific software development cannot treat simple file presence as proof of correctness. A simulation script that crashes on rank 48, or writes out NetCDF arrays filled with `NaN`s, may still successfully write a file to the disk. 
 
-Clio Coder recognizes **scientific validation contract files** as an opt-in signal for a higher evidence bar. In v0.3.0, core Clio does not parse or enforce a scientific contract schema. The presence of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, `validation.yml`, or `VALIDATION.md` at the workspace root raises the default rigor level to `high`; the file contents are advisory material for developers, project agents, and external validators.
+Clio Coder recognizes **scientific validation contract files** as an opt-in signal for a higher evidence bar. In v0.3.1, core Clio does not parse or enforce a scientific contract schema. The presence of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, `validation.yml`, or `VALIDATION.md` at the workspace root raises the default rigor level to `high`; the file contents are advisory material for developers, project agents, and external validators.
 
 The convention below is a recommended shape for scientific projects that need to document expected dimensions, attributes, numerical tolerances, scheduler context, and verification commands for scientific artifacts. Developed at the [Gnosis Research Center (GRC)](https://grc.iit.edu) at Illinois Tech as part of the NSF-funded scientific-software context (NSF Award [#2411318](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2411318)), this convention links execution metadata with physical output checks without claiming that the current harness executes those checks automatically.
 
@@ -77,7 +77,7 @@ Comparing floating-point values in scientific computations must accommodate roun
 
 ## Common Scientific Artifact Families
 
-The following labels are useful project conventions for validation contracts and reports. They are not a closed, core-enforced enum in v0.3.0:
+The following labels are useful project conventions for validation contracts and reports. They are not a closed, core-enforced enum in v0.3.1:
 
 - **`HDF5` / `NetCDF` / `Zarr`:** Multi-dimensional scientific array files.
 - **`FITS`:** Flexible Image Transport System (used in astrophysics).

package/docs/session-lifecycle.md

@@ -1,6 +1,6 @@
 # Session Lifecycle
 
-This document is the authoritative specification for Clio Coder interactive and headless session lifecycles, on-disk ledger structures, tree-based conversation branching, checkpoints, and recovery protocols in `v0.3.0`.
+This document is the authoritative specification for Clio Coder interactive and headless session lifecycles, on-disk ledger structures, tree-based conversation branching, checkpoints, and recovery protocols in `v0.3.1`.
 
 Source implementations: `src/engine/session.ts` and `src/domains/session/`.
 
@@ -43,7 +43,7 @@ export interface ClioSessionMeta {
 }
 ```
 
-Format version `CURRENT_SESSION_FORMAT_VERSION = 3` (`src/engine/session.ts:66`) is stamped on all sessions created in `v0.3.0`. Sessions with missing or earlier format versions trigger schema migrations in `src/domains/session/migrations/` on `/resume`.
+Format version `CURRENT_SESSION_FORMAT_VERSION = 3` (`src/engine/session.ts:66`) is stamped on all sessions created in `v0.3.1`. Sessions with missing or earlier format versions trigger schema migrations in `src/domains/session/migrations/` on `/resume`.
 
 ---
 

package/docs/skills-marketplace.md

@@ -1,7 +1,7 @@
 # Skills Marketplace
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/skills_blueprint.html](html/skills_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/skills_blueprint.html](html/skills_blueprint.html) (Version: 0.3.1).
 
 The Skills Hub (`/skill`) shows project skills, user skills, and the marketplace. Every marketplace row comes from the same local lookup that `clio-coder skills install <name>` and `/skill:<name>` resolve through, so the hub lists nothing it cannot install.
 

package/docs/time-conventions.md

@@ -0,0 +1,101 @@
+# Time and Clock Conventions
+
+This document defines the canonical time and clock conventions for `clio-coder`. These policies establish consistent rules for measuring durations, recording instants, converting timezones, and managing concurrency across the codebase.
+
+This policy is promoted from Section 10 of the repository time audit in [time-audit-2026-08-15.md](issues/time-audit-2026-08-15.md).
+
+---
+
+## 1. Which Clock for What Purpose
+
+### Monotonic clocks for durations
+
+All durations must be measured using `performance.now()` without exception. This rule applies to latency measurements, elapsed run times, time-to-first-token (TTFT), execution budgets, timeouts, stall watchdogs, retry backoff intervals, and rendering metrics.
+
+Whenever a value answers the question "how long did this take" or "how long until", it must originate from the monotonic clock. Monotonic clocks are unaffected by Network Time Protocol (NTP) adjustments, system suspend or resume events, and Daylight Saving Time (DST) transitions.
+
+### Wall clocks for anchored instants
+
+Wall clock reads via `Date.now()` or `new Date()` are reserved exclusively for anchoring instants that a human operator or an external machine will inspect. These include timestamps such as `startedAt`, `endedAt`, `createdAt`, and `expiresAt`. Wall clocks must never be used to measure durations or elapsed intervals.
+
+### Combined anchor and span pattern
+
+When both an anchor instant and a duration are required, code must follow the pattern established in `src/domains/dispatch/code-step.ts:291-306`:
+
+```ts
+const startedAtMs = Date.now();                      // wall anchor, for the record
+const clock = process.hrtime.bigint();               // monotonic span
+const startedAt = new Date(startedAtMs).toISOString();
+// ... operation executes ...
+const durationMs = Number((process.hrtime.bigint() - clock) / 1_000_000n);
+const endedAt = new Date(startedAtMs + durationMs).toISOString();
+```
+
+The wall clock anchors the starting instant for human correlation. The monotonic clock measures the elapsed span. The ending timestamp `endedAt` is derived by adding the monotonic span to the initial wall anchor. This derivation guarantees that `endedAt - startedAt === durationMs` remains true regardless of any wall-clock adjustments that occur during execution.
+
+### Injectable clock seams
+
+Every module that reads a clock must accept an optional injectable clock interface in its configuration or options, defaulting to the system clock. Injectable clock seams allow test suites to run deterministically without relying on real-time passage or introducing timing races.
+
+### Cross-host timestamp boundaries
+
+A timestamp produced on one host must never be compared directly against a clock read on another host. Systems must receive-stamp incoming events upon arrival on the local host, maintain an explicit clock offset, or order events using sequence numbers rather than timestamps. Code must never subtract timestamps across host boundaries.
+
+### Sequence numbers over timestamps for ordering
+
+When ordering operations under concurrency, code must prefer monotonic sequence numbers over timestamps. Components such as the agent ledger (`src/domains/session/agent-ledger-store.ts`) and the execution scheduler (`src/domains/dispatch/execution-scheduler.ts`) rely on sequence numbers to remain correct by construction. Timestamps are reserved for human display and coarse windowing. Any attribution logic that relies on timestamps must report ambiguity explicitly rather than returning null.
+
+---
+
+## 2. Where UTC Is Converted
+
+### Storage, transport, and comparisons in UTC
+
+The system stores UTC, transports UTC, and compares UTC. Conversion to local time occurs once, strictly at the render call site.
+
+1. On disk and across the wire, timestamps are always represented as canonical ISO-8601 strings produced by `toISOString()`. Every store validates timestamps upon reading using the exact round-trip check from `src/domains/dispatch/capacity-lease.ts:80-84`.
+2. In memory, instants are stored as epoch milliseconds or canonical ISO-8601 strings. Localized or pre-formatted date strings must not be held in memory models.
+3. At the user interface render boundary, UTC instants are converted to the operator's local timezone.
+4. Whenever a converted local timestamp is displayed, the underlying canonical UTC instant must remain accessible. For example, a table row displays local time while the associated detail pane preserves the exact ISO-8601 string so that the two representations can always be reconciled.
+
+---
+
+## 3. Formatter Policy
+
+All operator-facing time formatting is consolidated in `src/interactive/format-time.ts`. The module provides three standardized formatting functions:
+
+| Function | Output Format | Timezone and Locale Frame | Purpose |
+|---|---|---|---|
+| `clockLocal(instant)` | `HH:MM:SS` | Operator local timezone using `en-GB` locale with 24-hour cycle (`hourCycle: "h23"`) | Renders time-of-day for logs, tree selectors, and message pickers |
+| `dateLocal(instant)` | `YYYY-MM-DD` | Operator local timezone using `en-CA` locale | Renders calendar dates for session selectors, welcome dashboards, and export filenames |
+| `relative(instant, now)` | `"3m ago"` (falls back to `dateLocal`) | Operator local timezone | Renders relative recency ladders with automatic fallback to calendar dates |
+
+Both `Intl.DateTimeFormat` instances are constructed at module scope. The module automatically rebuilds formatters if `process.env.TZ` changes during runtime.
+
+Machine surfaces such as filenames, IDs, structured log fields, and receipt records bypass the formatting module entirely and use canonical `toISOString()`.
+
+---
+
+## 4. Test Determinism and Receipt Integrity
+
+### Test clock harness
+
+Test suites must rely on the steppable clock helper in `tests/harness/clock.ts`. Every factory function that reads a clock must default to the harness clock in test environments. Real-time passage in tests is opt-in and requires explicit configuration.
+
+### Receipt integrity digests
+
+Persisted fields such as `startedAt` and `endedAt` participate in receipt integrity digests (`src/domains/dispatch/receipt-integrity.ts`). Any timestamp normalization, derivation, or adjustment must occur before the receipt digest is sealed. Timestamps must never be rewritten after receipt creation.
+
+---
+
+## 5. State-Root and Audit-Filename Assumptions
+
+### Host-scoped state root and coordination
+
+The state root directory is host-scoped. Durable locks and capacity leases carry a metadata payload containing `{host, pid, birthToken}`.
+
+A coordination record created by a foreign host is never adjudicated against the local process table. This follows the host-scoping pattern implemented in `src/tools/compete-worktrees.ts:207-215`, `src/domains/dispatch/orphan-recovery.ts:140-149`, and `src/core/run-identity.ts:23`.
+
+### Audit filename semantics
+
+The date in an audit log filename (such as `audit-YYYY-MM-DD.jsonl`) is a human-facing label indicating the local calendar date on which the audit log was opened. It does not represent machine-read data. All individual audit event records contained within the file store canonical UTC ISO-8601 timestamps.

package/docs/tool-usage.md

@@ -1,11 +1,11 @@
 # Tool Usage Reference
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive seven-plane tool atlas and observation envelope truncation/offload calculator is located at [docs/html/tool_usage_blueprint.html](html/tool_usage_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive seven-plane tool atlas and observation envelope truncation/offload calculator is located at [docs/html/tool_usage_blueprint.html](html/tool_usage_blueprint.html) (Version: 0.3.1).
 
 This is the deep usage reference behind the deliberately terse tool descriptions in the prompt envelope. Toolkit v2 keeps rich guidance out of tool descriptions and puts it here, where `context(scope="docs", query=...)` retrieves it section by section. Each tool below has its own self-contained `##` section covering the argument surface, defaults, truncation and continuation behavior, and concrete calls. Source of truth is `src/tools/`.
 
-In Clio Coder v0.3.0, `src/tools/agent-tools.ts` serves as the single agent-tool adapter across both orchestrator and worker runtimes. Both surfaces resolve their executable tools through the exact same `effectiveToolNames` narrowing, ensuring that attested tool schemas never drift from the tools available at runtime. Tools are keyed strictly by the `ToolName` union with no alias table. Argument leniency for weak-model callers is provided exclusively by per-tool `prepareArguments` normalizers declared on `ToolSpec`.
+In Clio Coder v0.3.1, `src/tools/agent-tools.ts` serves as the single agent-tool adapter across both orchestrator and worker runtimes. Both surfaces resolve their executable tools through the exact same `effectiveToolNames` narrowing, ensuring that attested tool schemas never drift from the tools available at runtime. Tools are keyed strictly by the `ToolName` union with no alias table. Argument leniency for weak-model callers is provided exclusively by per-tool `prepareArguments` normalizers declared on `ToolSpec`.
 
 ## Observation envelope: truncation notices, offload, next hints, and the turn budget
 
@@ -495,6 +495,7 @@ Arguments:
 - `decisions` (optional array). For `action="complete"`, key-value objects representing settled configurations.
 - `summary` (optional). Closeout explanation for `action="complete"`.
 - `max_rounds` (optional number). Round limit for this interview (default 6, max 24).
+- `exposure` (optional). `local` (default) or `outward`. `outward` marks a gate whose answer publishes or sends something outside the workspace (filing an issue or PR, posting a comment, pushing, releasing). At autonomy `auto-edit` an outward gate parks for the operator instead of being answered automatically; `full-auto` answers it. See [safety-model.md](safety-model.md).
 
 The tool manages a stateful operator interview. The UI presents choices (with an implicit "Other" option for custom text input). Once completed, the final decisions are persisted as standard configurations in the session ledger, allowing the agent to proceed with operators' inputs or defaults.
 
@@ -514,9 +515,9 @@ Arguments:
 - `kind` (required). `plan`, `review`, or `report`.
 - `content` (required). Full Markdown body.
 - `title` (optional). Document title.
-- `path` (optional). Override the default artifact path.
+- `path` (optional). Override the default path under `.clio-coder/artifacts/`.
 
-`kind=plan|review|report` writes a Markdown document to PLAN.md, REVIEW.md, or REPORT.md at the project root by default; `path` may override the destination but must stay inside the workspace. When `content` does not already start with `#`, a non-empty `title` is prepended as an H1. These kinds are TERMINAL: writing the artifact completes the turn and the harness skips the follow-up model call, so the artifact body itself is the answer. Put everything the reader needs in `content`; there is no closing message after the write.
+`kind=plan|review|report` writes a Markdown document to `.clio-coder/artifacts/PLAN.md`, `REVIEW.md`, or `REPORT.md` by default, so a turn nobody asked a file from never litters the working tree; `path` may override the destination but must stay inside the workspace. See [artifact-placement.md](artifact-placement.md) for the full contract. When `content` does not already start with `#`, a non-empty `title` is prepended as an H1. These kinds are TERMINAL: writing the artifact completes the turn and the harness skips the follow-up model call, so the artifact body itself is the answer. Put everything the reader needs in `content`; there is no closing message after the write.
 
 Skills are not artifacts. A skill is a `SKILL.md` folder written with the ordinary write tool into `.clio-coder/skills/<name>/` (or the user skill store) and validated by the skills loader; the `skill-craft` shipped skill documents the format and craft rules.
 

package/docs/trace-store.md

@@ -1,7 +1,7 @@
 # Trace store contract
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive trace database viewer, schema inspector, and SQL query validator simulator is located at [docs/html/trace_blueprint.html](html/trace_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive trace database viewer, schema inspector, and SQL query validator simulator is located at [docs/html/trace_blueprint.html](html/trace_blueprint.html) (Version: 0.3.1).
 
 Clio's trace database is a rebuildable, queryable mirror. Receipts, session
 ledgers, gate artifacts, and evidence remain the source of truth. Removing

package/docs/troubleshooting.md

@@ -1,6 +1,6 @@
 # Troubleshooting & Error Remediation
 
-This guide provides concrete, actionable remediation procedures for operational errors, permission denials, target connection failures, and system diagnostics in Clio Coder `v0.3.0`.
+This guide provides concrete, actionable remediation procedures for operational errors, permission denials, target connection failures, and system diagnostics in Clio Coder `v0.3.1`.
 
 ---
 

package/docs/tui-design.md

@@ -1,7 +1,7 @@
 # Clio TUI Design System
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive color/glyph token laboratory and terminal transcript preview renderer is located at [docs/html/tui_design_blueprint.html](html/tui_design_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive color/glyph token laboratory and terminal transcript preview renderer is located at [docs/html/tui_design_blueprint.html](html/tui_design_blueprint.html) (Version: 0.3.1).
 
 This document is the reference specification for the Clio Coder TUI visual layout, styling, and behavior. It describes color semantics, the glyph vocabulary, structural recipes, and state choreography for all surfaces under [src/interactive/](../src/interactive/).
 
@@ -19,7 +19,7 @@ All color styling is defined in [src/interactive/theme/tokens.ts](../src/interac
 |---|---|---|
 | `accent` | `rgb(70, 229, 208)` (Teal) | Brand and interactivity: frame titles, selection highlight, keybinding/slash-command affordances, agent voice glyphs, tool verbs, and active/writing phases. |
 | `accentDeep` | `rgb(31, 183, 166)` | Structural emphasis only: bold CAPS section tags. |
-| `action` | `rgb(255, 126, 41)` (Orange) | Active autonomous operations: dispatching phase pills, active fleet badges, running fleet indicators, and user-steering queues. |
+| `action` | `rgb(255, 126, 41)` (Orange) | Active autonomous operations: dispatching phase pills, active fleet badges, running fleet indicators, running connect/probe indicators, and user-steering queues. |
 | `success` | `rgb(87, 227, 137)` (Green) | Positive outcomes: success indicators (`✓`), ok health status, clean git trees, and output-token count updates. |
 | `warning` | `rgb(255, 180, 84)` (Amber) | Real warnings only: stale data, dirty trees, retry status, blocked tools, and truncation. |
 | `error` | `rgb(255, 92, 102)` (Red) | Failures: error indicators (`✗`), error rails, stuck states, and error message text. |
@@ -36,6 +36,7 @@ All color styling is defined in [src/interactive/theme/tokens.ts](../src/interac
 - Color is used functionally to indicate state. If removing a color does not lose information, the text is colored using `dim`, `muted`, or left unstyled.
 - `warning` amber is reserved for true warnings. Costs and neutral telemetry numbers use `muted`.
 - `accentDeep` is used only in section tags. Metric values (such as TTFT, tokens-per-second, and autonomy status) use `muted`.
+- `action` neon orange remains scarce and strictly disciplined: only while Clio is acting or a prompt owns the keyboard (e.g. running connect/probe operations, active dispatch/fleet execution, or the keyboard-owning confirmation border / `STEER` mode). It is never used for idle decoration or settled telemetry, and never appears on more than one element per screen region.
 - Per-surface color budgets limit noise: chip strips use at most one non-neutral token per chip, and framed cards use at most one status token alongside neutral colors.
 
 ---
@@ -46,7 +47,7 @@ All symbols are defined as constants in [src/interactive/theme/glyphs.ts](../src
 
 | Glyph | Name | Meaning | Used by |
 |---|---|---|---|
-| `>C_` | `brand` | Clio wordmark | Welcome header and dashboard header only. |
+| `>C_` | `brand` | Clio wordmark | Welcome launchpad header, session header, and dashboard header only. |
 | `✦` | `agent` | Agent voice | Chat reply prefix (accent; error red on failed turns). |
 | `›` | `user` | User voice | Chat user prefix (accent); steering queue marker (action). |
 | `❯` | `cursor` | Selection focus | Settings, list overlays, selectors. |
@@ -75,7 +76,7 @@ All symbols are defined as constants in [src/interactive/theme/glyphs.ts](../src
 | `─` | (rules) | Horizontal rule and borders | Frames and rules. |
 | `╌` | `innerDivider` | Divider inside a frame | Task island, any framed list. |
 | `·` | (dotSep) | Chip separator (dim) | Everywhere. |
-| `◆ ◇` | `active/scoped` | Active and scoped marks | Model selector, thinking selector. |
+| `◆ ◇` | `active/scoped` | Active and scoped marks | Model selector, thinking selector, Settings profile workbench. |
 
 ---
 
@@ -139,21 +140,54 @@ Drawn as `<key padded, dim> <value>`, where the value defaults to `muted` unless
 ### 4.6 Narrow Terminal Behavior
 
 All TUI overlays and cards support compact widths down to 40 columns:
-- Split overlays such as `/view` fall back to a single pane layout with `[Tab]` switching between the artifact list and details.
+- Split overlays such as `/view` fall back to a single-pane layout with `[Tab]` switching between the artifact list and details.
 - Keybinding hints, cards, and markdown detail text wrap fluidly without horizontal clipping.
-
+- Settings provides a dedicated drill-down stack below 72 columns.
 
 ---
 
-## 5. State Choreography
+## 5. Screen Surfaces & State Choreography
+
+The Clio screen maintains a responsive, four-zone structure: the launchpad / session header, transcript, composer, and footer.
+
+### 5.1 Welcome Launchpad & Session Header
+
+- **Pre-Submit Launchpad**: Before the first prompt, renders a compact launchpad at line 0 with bold CAPS section tags (`WORKSPACE`, `ROUTE`, `NEXT`), honest readiness state, and a context-sensitive next action (e.g. `ctx missing · /context init`, `ctx checking…`, or `ctx ready · type a task`). Asynchronous repository probes use height-stable dim placeholders (`factsPending`).
+- **Session Header Collapse**: On first user submission, the launchpad deliberately collapses into an immutable, single-line session header (`>C_ Clio Coder vX.Y.Z · EXPERIMENTAL · ctx ready · type a task`) so the conversation transcript owns the viewport.
+
+### 5.2 Composer (ClioEditor)
+
+- **Mode Section Tag**: The top rail features an explicit left section tag indicating prompt semantics:
+  - `MESSAGE` (dim/teal) while idle.
+  - `FOLLOW-UP` (muted) while Clio is actively processing a run.
+  - `STEER` (neon orange) when Enter will actively steer in-flight work.
+  - When the draft scrolls, the active mode folds into the scroll indicator row so the orange warning remains visible.
+- **Top Rail Metadata**: The top rail right displays target/model and thinking level with two-step color hierarchy: `off` (dim), `minimal`/`low` (muted), `medium`/`high` (`reason` purple), and `xhigh`/`max`/`on` (bold `reason` purple).
+- **Empty-State Placeholder**: Displays dim prompt `Ask Clio…  / for commands`.
+- **Lower Rail Affordance**: On terminals at or above 60 columns, the bottom rail displays `Enter send · Shift+Enter newline` (or resolved keybindings).
+
+### 5.3 Progressively Disclosed Footer
 
-The Clio screen maintains a fixed structure: banner, transcript, editor rail, and footer. State is signaled through the status pill in the footer and matches the following table:
+- **Compact Mode (Quiet Idle)**: Two always-on lines that eliminate idle telemetry noise (suppresses `tools none`, `◌ idle`, and default-output tags):
+  - **Line 1 (Workspace & Readiness)**: CWD path, git branch/dirty state, and active phase pill only when meaningful.
+  - **Line 2 (Context & Receipt)**: Context window meter and the best current/last-turn receipt.
+- **Expanded Mode (`Alt+U`)**: Four responsive sections ordered by operational urgency rather than a static telemetry grid:
+  1. `Activity`: Live agent phase, active workers, running tool calls.
+  2. `Context`: Context window gauge, breakdown, token headroom.
+  3. `Session`: Session cost, throughput, total token breakdown, leader key state.
+  4. `Workspace`: CWD, branch, target, git dirty status.
+  Empty rows collapse rather than occupying blank grid space.
+- **Notification Badge & Degradation Ladder**: The footer notification badge reserves the severity head (`ℹ 1 notice`, `⚠ 1 warning`, `✗ 1 error`), separator, and `[Alt+X] dismiss` tail first, allocating the middle width to an ellipsized message. At narrow widths, it degrades gracefully down the ladder (`head · [Alt+X] dismiss` → `head · [Alt+X]` → `head` → glyph alone) without clipping the action key.
+
+### 5.4 State Choreography Table
+
+State is signaled through the status pill in the footer and matches the following table:
 
 | State | Pill | Transcript Echo | Action Orange? |
 |---|---|---|---|
-| idle | `◌ idle · tools none` (muted) | None; last-turn telemetry on line 2 | No |
+| idle | Quiet (phase omitted; line 1 shows workspace, line 2 shows context/receipt) | None; last-turn telemetry on line 2 | No |
 | preparing / waiting | spinner + `waiting` (info) | None | No |
-| thinking | spinner + `thinking` (reason) | Dim `Thinking (N tokens)...` marker | No |
+| thinking | spinner + `thinking` (reason) | Dim `Thinking (N tokens)…` marker | No |
 | writing | spinner + `writing` (accent) | Streaming markdown text | No |
 | tool running | spinner + `tool <name>` (accent) | `▸` tool execution ledger line | No |
 | blocked | `⏸ blocked` (warning) | Permission prompt surface | No |
@@ -161,33 +195,40 @@ The Clio screen maintains a fixed structure: banner, transcript, editor rail, an
 | compacting | spinner + `compacting` (reason) | None | No |
 | dispatching / fleet live | spinner + `dispatch` (action) | Task island status updates | Yes |
 | stuck | `⚠ stuck 12s` (error) | Inline watchdog warning | No |
-| done | `✓ done` (success), then telemetry | Settled transcript blocks | No |
+| done | `✓ done` (success), then quiet telemetry | Settled transcript blocks | No |
 
 ---
 
 ## 6. Agent and Transcript Formatting
 
-### 6.1 Voices
+### 6.1 Voices & Hanging Indent
 - **User**: `› text` with the user glyph in `accent`.
-- **Agent**: `✦ text` with the agent glyph in `accent` (turning `error` red on failed turns, along with the text message).
+- **Agent**: `✦ text` with the agent glyph in `accent` (turning `error` red on failed turns, along with the text message). Skill suggestions do not claim the `✦` reply glyph.
+- **Two-Cell Hanging Indent**: User and assistant prose are rendered with a fixed two-cell gutter. The first line begins with the turn prefix (`› ` or `✦ `), while all wrapped continuation lines indent by two spaces (`PROSE_GUTTER = "  "`), keeping multiline text visibly attached to its voice glyph.
 
 ### 6.2 Thinking Blocks
-Drawn as a folded dim marker (`Thinking (N tokens)...` or `Thinking...`), which expands into a body using the `reason` color vertical `│` rail. Cap of 12 lines.
+Drawn as a folded dim marker (`Thinking (N tokens)…` or `Thinking…`), which expands into a body using the `reason` color vertical `│` rail. Cap of 12 lines.
 
 ### 6.3 Tool Ledger
 Tool lines wrap as a single composed block:
 ```
 ▸ verb object · resource · facts · size ✓ · 230ms · full: path (ctrl+o)
 ```
-- Verb is bold `accent`, tail details are `dim`, status glyph is semantic (`✓`/`✗`), and the keyboard shortcut hint is appended at the end.
+- Verb is bold `accent`, tail details are `dim`, status glyph is semantic (`✓`/`✗`), and the keyboard shortcut hint is appended at the end. Tool ledgers maintain full terminal width and bypass the prose hanging indent.
 
 ### 6.4 Editor Rail
-The right-hand label shows `model · thinking`. Thinking level colors map as: `off` (dim), `minimal`/`low` (muted), and `medium` and above (purple `reason`).
+The right-hand label shows `model · thinking`. Thinking level colors map as: `off` (dim), `minimal`/`low` (muted), `medium`/`high` (`reason` purple), and `xhigh`/`max`/`on` (bold `reason` purple).
 
 ### 6.5 Transcript Notices
 Replay and system tags (e.g. `[retry]`, `[model]`) are wrapped in `dim` brackets with a `muted` message. Retry tags use `warning` amber.
 
-### 6.6 Code Ink (Syntax Highlighting)
+### 6.6 Output Verbosity Receipts
+Turn usage receipts rendered at the bottom of completed turns respect the output verbosity configuration:
+- `minimal`: Omits the turn usage receipt entirely.
+- `default`: Renders one compact dim receipt: `turn · in <N> · out <M>`.
+- `verbose`: Renders the full receipt with model call counts (`over N calls`), cache reads/writes (`cache R/W`), reasoning tokens with provenance (`reasoning N provider` or `reasoning ≈N estimated`), and the verification caveat (`· reasoning text is a UI excerpt, not a verification`).
+
+### 6.7 Code Ink (Syntax Highlighting)
 
 Syntax highlighting within code blocks is handled by [src/interactive/renderers/code-ink.ts](../src/interactive/renderers/code-ink.ts). It maps a restricted set of four tokens to stay quiet:
 
@@ -200,16 +241,30 @@ All other code elements (identifiers, types, function names, punctuation) remain
 
 ---
 
-## 7. v0.2.9 TUI & Cost Provenance Transformations
-
-### 7.1 Fleet Visibility Across Surfaces
-- **Dispatch Board**: Displays per-run status cards with node assignments (`local` vs remote node ID), reroute badges, gate indicators (`gate reviewer c2`), live tool activity, and context occupancy meters.
-- **`/fleet` Overlay**: Modal overlay allowing operators to view running dispatches, inspect node capabilities, edit profile node pins, and monitor worker heartbeats.
-- **Parked Tools & Approvals**: Parked tool calls awaiting permission are rendered as `⏸ awaiting approval` with explicit approval prompts. Input overlays stay modal during active runs so background completions do not displace open dialogs.
-
-### 7.2 Cost Provenance & Evidence Rendering
-- **Session vs Run Provenance**: The Activity footer renders session token/cost totals, while the dispatch board and `/fleet` overlay render per-run worker tokens and cost with `known`, `estimated`, or `unknown` provenance markers. The current surfaces do not present a separate orchestrator-versus-worker algebra.
-- **Proof Markers**: Dispatch cards and `/fleet` rows render evidence readiness as `proof` markers (`pending`, `ready`, or `failed`) from the observability projection. Model-facing dispatch and monitor output use `receipt_integrity=verified/v15/sha256` and a separate `evidence_verification` label; the TUI does not emit a `[VERIFIED_RECEIPT_OK]` badge.
+## 7. Settings Center & Command Overlays
+
+### 7.1 Settings Center Architecture
+The `/settings` overlay is a full-screen transactional control center:
+- **Group Structure**: Sections are organized under non-selectable section headers:
+  - `CORE`: Autonomy & Safety (`safety`), Orchestrator (`orchestrator`)
+  - `ROUTING`: Fleet (`fleet`), Targets (`targets`), Models (`models`)
+  - `RUNTIME`: Budget (`budget`), Compaction (`compaction`), Retry (`retry`)
+  - `EXPERIENCE`: Terminal (`terminal`), Advanced (`advanced`)
+- **Semantic Row Grammar**: Explicit presentation kinds (`setting`, `status`, `action`, `group-header`, `read-only-fact`, `destructive-action`) prevent confusion between focus (teal), health (green/amber/red), modified status (neutral/teal mark), and active operations (scarce orange).
+- **Transactional Edits**: Selecting a row and pressing `Enter` opens a dedicated value picker, input dialog, or checklist rather than immediately toggling values. Edits construct an immutable `SettingsChangePlan` and present explicit destination choices:
+  - `Apply this session` (for live-capable settings)
+  - `Apply and save globally`
+  - `Cancel` (or `Esc`)
+  - Restart-required settings (`budget.concurrency`, `runtimePlugins`) offer only global save and announce `Saved to settings.yaml · restart Clio to apply`.
+  - Destructive actions (target/profile removal) execute preflight analysis showing affected chat, fleet, and memory routes before confirmation.
+- **Fleet Workbench**: Organizes fleet settings with dim group headers (`Defaults`, `Profiles`, `Agent routes`, `Placement`). Profiles render as one-row summaries with `◆ Edit` affordance; pressing `Enter` drills into profile fields (target, model, thinking level, placement) or destructive removal.
+- **Targets Console Table**: Displays configured targets in an operational console table (`HEALTH`, `ID`, `ROLES`, `RUNTIME`, `LATENCY`) with an in-place action/detail drawer (URL, default model, last probe, failure reason). Actions include `Use`, `Connect`, `Probe`, and `Remove`. Active connect/probe operations show the single orange activity indicator.
+- **Scoped Models Checklist**: Settings → `Models` provides a provider-backed checklist subview with target-level and target/model items, checked current selections, `Space` to toggle, and capability details in the inspector. Unresolved model references are preserved under an `Unavailable` group.
+- **Narrow Terminal Drill-Down Navigation**: Below 72 columns, Settings transitions from a split view to a modal drill-down stack (section list → section rows → detail drawer) with a breadcrumb and `Esc` moving up one level before closing. Includes `/` filtering across label, path, and description. Below 60 columns, side margins are removed for full-width presentation.
+
+### 7.2 Slash Autocomplete Command Palette
+- **Grouped Palette**: Typing `/` opens a grouped command palette (ordered by `Run`, `Inspect`, `Configure`, `Sessions`) with compact argument hints and formatted descriptions.
+- **Stem-Gated Aliases**: Aliases (e.g. `/exit`, `/ctx`, `/compact`, `/models`, `/config`) are hidden by default and only surface when the typed stem matches the alias spelling.
 
 ---
 
@@ -237,3 +292,4 @@ Two shapes, both ending at something the user can act on.
 ### 8.2 Memory Step Rows
 
 `/memory` activity rows read `<trigger> <decision> <reason>`, followed by `<N>w` when the step wrote to the bank and `<N> cited` when it cited entries, then the tier and latency. `describeTaskMemoryActivity` is the one place that builds this string.
+

package/docs/worker-dispatch-mechanics.md

@@ -1,7 +1,7 @@
 # Worker Dispatch Mechanics
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive NDJSON protocol timeline stream and heartbeat watchdog simulator is located at [docs/html/worker_dispatch_blueprint.html](html/worker_dispatch_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive NDJSON protocol timeline stream and heartbeat watchdog simulator is located at [docs/html/worker_dispatch_blueprint.html](html/worker_dispatch_blueprint.html) (Version: 0.3.1).
 
 This document describes the design and lifecycle of Clio Coder dispatched workers, focusing on the spawning sequence, execution isolation, the standard input/output NDJSON communication loop, and permission escalation routing.
 
@@ -63,7 +63,7 @@ Clio divides worker output into two isolated streams to protect control signals
 2. **Control Lane (`stderr`)**:
    Emits out-of-band control frames prefixed by `@clio-control/1 `, capped at `WORKER_CONTROL_FRAME_MAX_BYTES` (16 KiB). Because control frames travel over `stderr`, they bypass backpressured bulk stdout streams and reach orchestrator watchdogs immediately. Control frame kinds include:
    * **Announce:** `{"kind": "announce", "attestation": ...}` sent immediately upon startup.
-   * **Heartbeat:** `{"kind": "heartbeat", "at": 1720186123000}` emitted every 1000 milliseconds.
+   * **Heartbeat:** `{"kind": "heartbeat"}` emitted every 1000 milliseconds. The frame carries no timestamp; the orchestrator stamps arrival on its own clock.
    * **Steer / Cancel Acknowledgments:** Confirming reception of stdin control directives.
 
 ### 2.2 Worker Input (`stdin`)
@@ -87,7 +87,7 @@ Any stdin chunk that is not a valid JSON structure matching these schemas is log
 
 Even when a model is processing a long thinking phase or generating a heavy output, the worker must prove it is alive to prevent the parent orchestrator's watchdog from reclaiming it.
 
-* **Emission:** The heartbeat loop (`startWorkerHeartbeat` in `src/worker/heartbeat.ts`) writes a heartbeat control frame (`{"kind": "heartbeat", "at": ...}`) to the `stderr` control lane every 1000 milliseconds.
+* **Emission:** The heartbeat loop (`startWorkerHeartbeat` in `src/worker/heartbeat.ts`) writes a heartbeat control frame (`{"kind": "heartbeat"}`) to the `stderr` control lane every 1000 milliseconds.
 * **Stream Isolation:** Because heartbeats ride the control lane rather than `stdout`, a large bulk output or queued tool result cannot starve or delay the watchdog check.
 * **Non-Blocking Timer:** The heartbeat timer interval is explicitly `.unref()`'d, ensuring the Node.js runtime is not kept alive past the natural lifetime of the worker run.
 * **Termination:** Once `startWorkerRun` resolves, the timer is cleared before returning the worker's exit code.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@iowarp/clio-coder",
-	"version": "0.3.0",
+	"version": "0.3.1",
 	"description": "Coding agent for HPC and scientific-software developers, part of IOWarp's CLIO ecosystem of agentic science.",
 	"keywords": [
 		"ai",
@@ -42,17 +42,17 @@
 	"bin": {
 		"clio-coder": "dist/cli/index.js"
 	},
+	"exports": {
+		"./package.json": "./package.json"
+	},
 	"files": [
 		"dist",
 		"!dist/**/*.map",
 		"assets/clio-coder-logo-128.webp",
-		"src/domains/agents/builtins/**",
-		"src/domains/agents/fleets/**",
+		"src/**",
 		"skills/workflow/cut-it/**",
 		"skills/git/**",
 		"skills/skill-marketplace.json",
-		"src/domains/providers/models/**",
-		"src/domains/prompts/fragments/**",
 		"docs/*.md",
 		"docs/html/**",
 		"README.md",
@@ -68,7 +68,7 @@
 		"access": "public"
 	},
 	"scripts": {
-		"build": "tsup",
+		"build": "tsup && node --import tsx scripts/build-codewiki-asset.ts",
 		"dev": "tsup --watch",
 		"clean": "rm -rf dist",
 		"typecheck": "tsc -p tsconfig.tests.json",
@@ -105,15 +105,7 @@
 		"@earendil-works/pi-tui": "0.83.0",
 		"@lmstudio/sdk": "1.5.0",
 		"@silvia-odwyer/photon-node": "^0.3.4",
-		"@vscode/tree-sitter-wasm": "^0.3.1",
-		"chalk": "5.6.2",
-		"diff": "9.0.0",
-		"ollama": "0.6.3",
-		"tree-sitter-wasms": "^0.1.13",
-		"typebox": "1.3.0",
-		"undici": "8.5.0",
-		"uuid": "14.0.1",
-		"yaml": "2.9.0"
+		"ollama": "0.6.3"
 	},
 	"overrides": {
 		"@anthropic-ai/sdk": "0.105.0",
@@ -123,10 +115,18 @@
 	"devDependencies": {
 		"@biomejs/biome": "2.5.1",
 		"@types/node": "24.12.2",
+		"@vscode/tree-sitter-wasm": "^0.3.1",
+		"chalk": "5.6.2",
+		"diff": "9.0.0",
 		"esbuild": "0.28.1",
 		"node-pty": "1.1.0",
+		"tree-sitter-wasms": "^0.1.13",
 		"tsup": "8.5.1",
 		"tsx": "4.22.4",
-		"typescript": "6.0.3"
+		"typebox": "1.3.0",
+		"typescript": "6.0.3",
+		"undici": "8.5.0",
+		"uuid": "14.0.1",
+		"yaml": "2.9.0"
 	}
 }