@iowarp/clio-coder 0.4.7 → 0.4.9

package/.claude-plugin/marketplace.json

@@ -66,7 +66,7 @@
 			"name": "clio-coder-test",
 			"source": "./library/skills/meta/clio-coder-test",
 			"description": "Verifies a Clio Coder source change against the current contract, smoke, boundary, and application test lanes, including temporary-state and local-provider harnesses. Not for deciding what may change; use clio-coder-dev.",
-			"version": "0.3.0",
+			"version": "0.3.1",
 			"category": "meta",
 			"license": "Apache-2.0"
 		},

package/CHANGELOG.md

@@ -2,6 +2,117 @@
 
 All notable changes to Clio Coder are documented in this file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and versions follow Semantic Versioning; pre-1.0 minor releases may include incompatible changes.
 
+## 0.4.9 - 2026-09-17
+
+### read
+
+- Read text of any size through bounded windows; count exact lines only through 32 MiB, keep a separate 20 MB (20000000 bytes) image ceiling, refuse binary/invalid UTF-8 with offsets, report file identity and observed changes, and provide honest tail continuation and numbering limits.
+
+### write and edit
+
+- Publish atomically to real symlink targets with mode preservation, before/after file identities, and explicit durability warnings. Bound previous-content diff reads and skip diffs above 1 MiB.
+- Edit refuses binary, invalid UTF-8, mixed or bare-CR endings; preserves BOM and uniform line endings; requires exact matching above 1 MiB. External writers remain unlocked.
+
+### bash
+
+- Keep the combined 16 MiB stop-on-output contract while distinguishing observed and retained bytes and reporting actual inline, offloaded, discarded, or failed retention under every output policy. Point large-output processing to run_script.
+
+### grep, find, and ls
+
+- Preserve partial search results on timeout, cancellation, and recoverable errors, with completeness, skipped counts, bounded samples, and unknown-coverage notices. Disclose fallback ignore differences and native find's uncounted symlink-directory skips while preserving fd glob behavior.
+- List symlink targets, broken links, and inspection failures explicitly. Select the alphabetical prefix asynchronously with bounded retained entries and report selection metadata.
+
+### run_script
+
+- Add direct script execution with an explicit interpreter, argv, cwd, timeout, declared environment and file references, disk-streamed stdout/stderr, bounded progress, and a run manifest under `.clio-coder/runs/`.
+- Preserve actual leader exit beside effective failure for incomplete group cleanup or pipe draining; bound post-exit draining to one second and state escaped-process limits. Keep 100 completed run records with bounded retention metadata reads and explicit skipped entries.
+
+### verify
+
+- Add explicit all/any tolerance combination and fail/match non-finite policy, safe-integer ULP bounds, lossless non-finite report spellings, reference/payload provenance, and separate execution/validation/scientific-validity judgements.
+- Add version-2 performance baseline environments and informational mismatch reports. Refuse judgement of capped output; align direct and host verification at the 32 MiB judged capture/reference ceiling.
+
+### gateway and MCP
+
+- Add find/describe/call routing for secondary builtins, extension commands, and trusted local stdio MCP, preserving inner authority, worker attestation, terminal results, and exported evidence identity.
+- Add strict user/project mcp.yaml configuration, digest-bound project trust, `clio-coder mcp list|trust|untrust`, and interactive `/mcp`. Cancel shared discovery with owned cleanup and await teardown on shutdown; exit cleanup stays client-owned.
+- Reject malformed MCP call result envelopes instead of reporting successful empty results.
+- Render structured-only MCP results in bounded model-visible text, preserving numeric source literals in both the projection and retained evidence.
+- Resolve overlapping MCP server prefixes deterministically and report conflicting tool names as unregistrable, preserving server identity and authority during lazy discovery.
+
+### model compatibility
+
+- Record the measured mini/qwopus3.8-27b-dense route's low/medium/xhigh effort vocabulary. Map high/max to xhigh and forward the explicit effort through LiteLLM to avoid the observed upstream rejection, consistent with an incompatible deployment default.
+
+### context, web, and artifacts
+
+- Keep workspace, skills, and recall on context; move documentation and recipe browsing to gateway capabilities clio_docs and clio_library.
+- Separate gateway GET-only web_read from full web_fetch requests. Move git, evidence, and credential_present behind the same gateway.
+- Move artifact behind the gateway with atomic publication and its existing terminal turn contract intact.
+
+### data
+
+- Add gateway inspection, selection, and validation for CSV/TSV and JSON/JSONL with streaming readers, explicit exact/sampled/cut views, precision and sentinel reporting, bounded captures, and actionable unsupported-format refusals.
+
+### terminal workbench
+
+- Use case-insensitive literal search terms across View resource identity and provenance, show match counts, and place the cursor at the end of an initial query. Ctrl+U clears the whole filter independently of customized cursor bindings, with one-step undo restoring the query and cursor. Workspace outputs lead with their basename and relative path; preview offers scrollable provenance with `i` and retains selection across refresh.
+- Separate Library discovery notices into a searchable `n` view that preserves the resource browser on return. Use package, entry, and member units consistently in status and footer counts; label plugin providers in recipe categories, explain package action scope, and open narrow layouts with detail visible. Notice-return guidance respects search focus, and trusted state colors survive sanitization of external metadata.
+- Preserve raw target/model fields until composer rendering, retaining recognizable target, model family, and variant suffixes at narrow widths. Sanitize identity and workspace text before abbreviation. Keep workspace identity and live worker counts visible in the footer. Fleet Runs shows current operations and compact task previews, with the full route and task, available policy and budget details, and a bounded answer excerpt available through Enter detail; complete available evidence remains inspectable through `/view`; control hints reflect the selected run's capabilities. Ordinary unvalidated completions retain an explicit unverified/validation summary, with full provenance on Enter and exceptional trust facts still visible.
+- Distinguish current worker operations from completed calls in Detailed previews while retaining pending checkpoint questions and canonical evidence.
+
+### maintenance reliability
+
+- Keep stale or unavailable addressed worker steering out of the main conversation and preserve the rejected draft. Preserve session-picker selection through filtering and undo, honor the selected row with customized confirmation, and prioritize task identity in narrow terminals.
+- Bound provider-error previews by terminal rows, retain actionable status and route advice, and distinguish provider retries from fleet retries. Keep complete available redacted diagnostics in inspection and export. On OpenAI-compatible routes, restore the error body the SDK truncates at 4000 characters when the captured response provably matches it, bounded at 65536 characters; other adapters keep the upstream cap. Replaying intermediate tool-use messages no longer attaches a successful completion footer to an earlier failed or cancelled turn.
+- Complete partial UTF-8 session writes before acknowledging entries, roll back failed appends, and retain pending durability flushes through descriptor cleanup. Validate session format and replay entries before switching owners, and prepare migrated ledgers before publishing reopened lifecycle state.
+- Keep provider deadlines and caller cancellation active through response bodies and release unread probe responses. Apply the same lifetime to native capability and embedding requests; permit native embedding fallback only for completed endpoint-unavailable responses, preserving the existing healthy vector and reranking contracts.
+- Render recognized completed worker contracts consistently in Fleet Runs and the transcript using verified receipt identity and conformance. Preserve raw evidence, partial-output disclosure and the distinction between execution, contract conformance and validation.
+- Align installed-skill activation guidance with the existing autonomy policy while preserving operator-gated marketplace installation, recipe restrictions and first-turn discovery. The corrected instructions replace contradictory wording without growing the prompt.
+- Retain scheduler ownership of workers across partial parallel startup and cancellation until their terminal cleanup settles. Keep concrete fleet-member steering, permission responses and cancellation within the addressed member or assignment retry chain instead of selecting a sibling with shared ancestry.
+- Reopen and restamp a migrated version-3 session in one atomic metadata publication, so a refused resume leaves the prior metadata intact instead of marking the candidate open under its old version.
+- Stop the boot-time tool-support warning for targets that were never probed; a cold gateway route reports nothing about its model until a probe, catalog entry or target flag states it.
+- Record fleet preflight results again, through `clio-coder doctor --fix`. Since 0.4.1 no command wrote the preflight store, so dispatch admission refused every SSH node while advising a plain `doctor` run that could not help. Plain `doctor` stays observation-only and says whether the node is recorded. Verified with a real worker dispatched to a homelab node over SSH.
+- Name write-root confinement in the dispatch refusal when it, not the runtime, removed a required tool, with the remedy for read-only or worktree runs.
+- Verify a preserved skill load when its `context` call shared a parallel tool batch. The ledger chains entries linearly, so the strict parent check failed for batched loads, the fail-closed clamp then protected everything after the activation, and the session could never compact. Found in a live WTF-P session that stalled at 80% context with `/context compact` reporting nothing to compact.
+- Record a loaded skill that declares no tool narrowing as a known selection. It was persisted as unknown, which also forced the compaction clamp for the rest of the session.
+- Title a session from the typed input when a prompt template or command expanded it. The session picker and replayed transcripts showed the expansion, so every WTF-P session read "<!-- Generated by WTF-P adapter compiler". The expansion stays the request that compaction reasserts.
+- Render one terminal row per tool line. A multi-line bash command stayed one row with a raw newline inside, and tool output kept cursor movement, backspaces and carriage returns, so the diff renderer painted every row below one row low and left bash residue over the composer border. Command previews collapse to one sanitized line and result text is neutralized before it is wrapped.
+- Bound one MCP result to 16 KiB of model context, the cap the built-in observation tools use. Only the 64 KiB session cap applied before, so a 62 KB search result entered context verbatim and two of them stalled a 131k local model. The full text is offloaded and the result names how to narrow the call or read the file in windows.
+- Name an ignored project settings layer under the Settings header of `clio-coder config inspect`. An untrusted `.clio-coder/settings.yaml` is ignored by design until `clio-coder config trust settings --hash <digest>`, but the only notice sat in the trailing Issues block, so a project `chat.retry.streamStallMs` looked like a setting that failed to apply.
+- Give the wait for a call's first token its own window, `chat.retry.firstTokenStallMs` (default 600000). One 180 s timer covered both the first token and mid-stream silence, although the setting is documented as measured from the last token received. A local llama-server that slept reloads in about 150 s and then prefills cold, so healthy turns were aborted and retried. `streamStallMs` still catches a stream that goes silent after it started, and re-arms at the first token.
+- Accept `clio-coder --autonomy <level>` for the interactive session. Only `clio-coder run` took the flag, so the supervised start that the WTF-P guide documents failed as an unknown global option. The flag seeds the same one-session override `/settings` uses and leaves `settings.yaml` untouched. Before a subcommand it is refused with the `run --autonomy` form named, because dropping a safety level silently would be worse. The top-level help now also lists `clio-coder mcp`.
+- Clear the remaining lint findings and split the web framework into its own chunk, which removes the oversized entry-chunk warning.
+
+## 0.4.8 - 2026-09-12
+
+Clio Coder 0.4.8 strengthens the terminal and headless harness: settings take effect consistently, provider and usage records stay tied to the right request, and startup, reload and shutdown retain their cleanup guarantees. Start with `clio-coder configure`, then `clio-coder` for interactive work or `clio-coder run` for headless tasks. The optional web app and local PWA add another way to reach the same runtime; they do not replace the CLI, TUI or ACP.
+
+### Added
+- An npm-backed bootstrap installer for Linux/macOS with prerequisite checks, a user-owned prefix, version selection, dry runs, conflict protection, and terminal-first next steps.
+- An optional web application through the lazy `clio-coder web` command, packaged with its REST/SSE server, two domain workers, and local client assets. Sessions, traces, docs, toolchain, settings/targets, fleet, evidence, evals/usage, Library, and system inspection use the existing Clio runtime.
+- Explicit background service setup for Linux with a systemd user session and an installable PWA with a stable local connection and offline recovery. Native lifecycle verification covers Linux/WSL2; macOS and Windows were not exercised in this sprint. Foreground web use remains available on other platforms.
+
+### Changed
+- Separate fast routine CI, exact-package qualification and explicitly invoked full development investigations. Publication now checks a fresh, source- and artifact-bound qualification instead of rerunning the entire suite. An earlier v0.4.8 candidate was withdrawn before npm publication; this release is the re-qualified cut.
+- Remove duplicated catalog/prose snapshots and repeated synthetic eval executions, reuse the installed package for browser verification, and replace configuration-reference repository copies with one typed schema check.
+- Preserve causal first-call timing when session wall clocks regress, and stop cancellation tests from swallowing Node test reporter output.
+- Generate the web documentation directly from the canonical Markdown, with shared navigation, search, heading outlines and the application theme. `clio-coder docs [topic]` opens the same reading surface and reuses a configured background app. Retire the separate docs server and HTML blueprints, including their iframe bridge and package assets. Markdown remains available to agents and repository readers.
+- Build the web surface together with the CLI, share server chunks, and ship frontend/font/Hono notices. Installed-package tests exercise both workers without a TypeScript loader. Release size tripwires are 12 MB compressed / 55 MB unpacked for the complete package.
+- Restore the Clio logo in the web app with cream and pastel forest themes and compact application controls.
+- Retire the separate trace viewer and `trace ui`; the unified web app uses the shared runtime trace reader. Preserve Workbench as reference source outside workspace builds, publication, and product gates. Update the shipped testing skill to use the current application lane.
+
+### Fixed
+- Apply effective output limits, thinking settings, tool read limits and history retention at their declared reload boundaries. Changing the selected target refreshes its runtime; configuration mutations are validated once against the value that will actually be committed.
+- Load provider runtime packages from canonical settings and bind cached probe state to the current target identity. External agent edits invalidate prompt inputs; recipe reloads stay independent from executable extension reloads.
+- Preserve SDK pricing tiers and per-call costs through native worker accounting. Retain cache-write lifetimes and usage from billed failed calls across session history, traces, compaction and receipts instead of repricing aggregate tokens.
+- Carry target cache policy through native provider requests. Prewarm uses the normal request hooks, requires fresh matching deployment evidence, and enforces input, duration and cooldown bounds. Detached work retains ownership until it settles; paid routes remain ineligible for speculative warming.
+- Unwind started domains after a startup failure, stop each domain once, and preserve per-domain shutdown budgets. Failed extension reloads retain the cleanup needed to stop their processes.
+- Apply user-hook path protections before tool execution and preserve annotations emitted before a tool starts.
+- Report unavailable target credentials before an ACP turn starts, with recovery instructions for background sessions whose keys were configured only in a terminal environment. Keep provider error bodies and credentials out of web errors.
+- Stop and disable owned web background services and remove their desktop entries before root uninstall deletes Clio state. Preview these resources and preserve state when ownership checks or service removal fail.
+- Resolve the real-home release smoke's input configuration through Clio's canonical paths command and pin all four temporary roots before running diagnosis or a turn, so inherited directory overrides cannot redirect smoke writes into the operator's state.
+
 ## 0.4.7 - 2026-09-10
 
 This release brings a unified Library for reusable workflows, operator extensions, safer keyboard and draft handling, and a compact welcome header. Native workers retain configured output limits and interrupted reasoning, and the guides describe the shipped behavior and its verification limits.

package/CONTRIBUTING.md

@@ -17,45 +17,60 @@ Requirements:
 - Linux or macOS for full parity. Windows is best effort until a stable release.
 
 Enable pnpm through Corepack (`corepack enable pnpm`), or install the pinned version locally.
-The root workspace includes both applications. pnpm owns dependency installation;
-Workbench still uses Deno for its host and tests.
+The root workspace includes the unified web application. pnpm owns dependency
+installation. `apps/workbench/` is retained reference source and excluded from
+workspace builds, publication, and product gates.
 
-Bootstrap:
+Bootstrap, in the order the checks depend on each other (the smoke tests run
+the built `dist/`, so build before testing):
 
 ```bash
 pnpm install --frozen-lockfile
+pnpm run build
 pnpm run typecheck
 pnpm run lint
 pnpm run test
-pnpm run build
+pnpm run test:web
 ```
 
-Local and GitHub PR gate (fast, deterministic):
+Local and GitHub PR gate:
 
 ```bash
 pnpm run ci
 ```
 
-This runs type checking, lint (including boundaries, documentation drift and
-skill audit records and full-tree library pins), one build, the contract/smoke
-suite, and the trace-viewer suite. Use `pnpm run library:check` for package pins
-and `pnpm run skills:check` for skill authoring records; both run in `lint` and `ci`.
+This runs types, lint (including architecture boundaries and library pins), one
+build, 27 core contract files, three real CLI/ACP/process smoke files, and the
+web application's authentication and runtime boundary tests. It deliberately
+excludes broad development regressions, catalog inventories and model eval
+corpora. Superseded GitHub runs are cancelled. Branch protection requires `ci (22)` (the routine gate) and `ci (24)` (engine,
+provider transport and durable-session compatibility only). The separate Windows job runs
+only the three subprocess contracts whose process-tree behavior is platform-specific.
 
-The GitHub `ci` job runs the release gate on Ubuntu. The separate
-`windows-subprocess` job uses Node 22 on `windows-latest` and runs typecheck
-plus the Antigravity subprocess, Bash settlement, and Windows process-tree
-contracts. It is a focused Windows lane, not the full suite. Native Windows
-local checks provide local evidence; they do not establish a hosted CI pass.
-
-Release gate (for maintainers before tags or release artifacts):
+Choose the lane for the risk:
 
 ```bash
-pnpm run ci:release
+pnpm run test:file -- tests/contracts/safety-gates.test.ts # focused development
+pnpm run ci                                              # routine Linux CI
+pnpm run ci:release                                      # clean committed candidate
+pnpm run test:full                                       # explicit full root investigation
+pnpm run test:web:full                                   # explicit full web investigation
+pnpm --filter @iowarp/clio-coder-web verify                # full web development, including browser matrix
 ```
 
-The release gate includes `ci` and adds the package audit. Running `ci` again
-on the same unchanged tree is unnecessary. Run a focused regression while
-developing a repair, then the full gate for the candidate being reviewed.
+Candidate qualification runs the routine gate, web types, the dependency/package
+audit, and two package smoke files. Those install the exact tarball with normal npm
+lifecycle scripts, exercise native delayed-header timing, and boot the installed web
+app in Chrome. They reuse that installed server for the browser check. No live model
+or operator credentials are required. Registry access is needed for the installed
+runtime dependencies and advisory audit; a failed audit is a failed qualification.
+Cold dependency installation is separate from gate timing.
+
+`tests/extended/` and `tests/extended-smoke/` retain focused development regressions.
+Run the relevant ones when editing their surfaces, or the explicit full suite for an
+extended investigation. They are not repeated during CI or npm publication. A newly
+found correctness regression must be fixed before qualification; moving a failing
+test to an extended lane is not a repair.
 
 Live provider validation (manual/opt-in, after `pnpm run build`):
 
@@ -76,56 +91,38 @@ built `dist/cli/index.js`; their files own the process drivers needed for each
 boundary. Rebuild `dist/` after changing CLI or entry-point source before
 running a focused smoke test.
 
-Do not assert a CLI subcommand's output by capturing `process.stdout.write`
-in-process. In-process stdout capture fights the node:test spec reporter:
-async flushes land in the capture buffer and the reporter's pass/fail counters
-get eaten, so a passing test can report as no output. Spawn the CLI through the
-harness instead. Patching `process.stdout`/`stderr` to assert a small library
-function's own output is fine; the trap is capturing a whole subcommand's
-output in-process while the reporter runs.
+Never replace `process.stdout.write` across asynchronous test work. Node's test
+child sends reporter records through that stream: a later test's mock can swallow
+an earlier failure's name and details. Spawn CLI commands using the current built
+binary. Small library captures must forward non-string reporter frames unchanged.
+
 
 ## Releasing
 
-Releases are cut from a tag. The GitHub release is created by CI; the npm
-publish is a manual maintainer step. The current procedure is the sequence
-below together with `.github/workflows/release.yml` and
-`scripts/check-release.mjs`. The
-[v0.4.1 release-cut checklist](docs/history/release-cut-checklist.md) is a
-historical record, not a reusable current checklist.
-
-1. During development, keep the top changelog section at `## Unreleased`. A
-   maintainer collects release work on a **local-only** compact candidate
-   branch (`v046` for `v0.4.6`) and bumps `version` there. Never push this
-   candidate branch to the canonical repository. Before the cut, retitle the
-   changelog section `## <version> - YYYY-MM-DD`, align the ACP registry manifest
-   version, and update the README's install tag and release notices.
-2. Run `pnpm run ci:release` on the exact candidate. It runs the full `ci` gate,
-   then `scripts/check-release.mjs`, which verifies the built `dist/` and
-   audits the exact npm package contents.
-3. Fetch `origin`, require the fetched `origin/main` to be the candidate's
-   ancestor, then fast-forward local `main` with `git merge --ff-only v046`.
-   Re-run the release gate if the candidate changed and verify local `main`
-   equals the reviewed candidate SHA.
-4. Fetch once more and stop on unexpected movement. With explicit maintainer
-   authorization, push only `refs/heads/main:refs/heads/main`; no topic or
-   release-candidate branch is pushed to canonical `origin`.
-5. Require CI for that exact `main` SHA to pass. Create the annotated tag on
-   that commit and push only it: `git tag -a v0.4.6` followed by
-   `git push origin refs/tags/v0.4.6`. The tag must match `package.json`; the
-   release workflow refuses mismatches.
-6. `.github/workflows/release.yml` verifies the tag against `package.json`,
-   runs `pnpm run ci:release` on the tagged tree, and creates the GitHub release
-   with the tarball attached and the version's `CHANGELOG.md` section as the
-   body. It does not publish to npm.
-7. A maintainer publishes from the tagged commit with `npm publish`;
-   `prepublishOnly` runs the same `ci:release` gate in release mode first.
-8. Verify the release and tag. Reconcile milestone tickets against tagged
-   implementation and acceptance evidence; plain issue references and release
-   tags do not close tickets. Verify automatic closures, explicitly close
-   completed tickets that remain open, and carry incomplete work forward before
-   closing the milestone. Then delete the local compact candidate branch.
-   The canonical remote returns to its steady state: `main` plus immutable
-   release tags and GitHub releases, with no release branch.
+The current [release checklist](docs/process/release-cut-checklist.md) is authoritative.
+
+1. Prepare and commit the exact candidate on a local branch. Install the pinned
+   workspace dependencies, then run `pnpm run ci:release` once. It qualifies one
+   artifact and stores it with a receipt under `~/.cache/clio-coder/qualification/`.
+   A new qualification invalidates old evidence before doing any work.
+2. Review the candidate SHA and qualified package. With explicit authorization,
+   fast-forward main and push the matching annotated version tag. The tag workflow
+   qualifies its own exact package before a dependent job can create the GitHub release.
+   It uploads that package, never a newly packed replacement.
+3. From the unchanged locally qualified checkout, run `pnpm run release:preflight`,
+   then, only with publication authorization, `npm publish`. `prepublishOnly` repeats
+   only the fast preflight. It requires the same clean commit, Node version, a
+   qualification less than 24 hours old, the original artifact digest, matching
+   current package bytes (including ignored build output), and dated release notes.
+   Missing, stale or changed evidence fails closed: qualify again. There are no
+   bypass flags or ignored lifecycle hooks in this procedure.
+4. Verify the published artifact and reconcile the release milestone before branch
+   closeout. Remote writes, tags and publishing always require explicit authorization.
+
+Do not run `ci`, the full suite, another build, or another installed-package check
+between successful qualification and publication. A rebuild may change package bytes
+and require qualification again. Live-model checks and the real-home smoke are
+optional investigations, not deterministic publish prerequisites.
 
 What `scripts/check-release.mjs` enforces, and how to respond when it fails:
 
@@ -133,8 +130,9 @@ What `scripts/check-release.mjs` enforces, and how to respond when it fails:
   `npm publish` require `## <version> - YYYY-MM-DD`, so unfinished notes cannot
   enter an immutable artifact.
 - Only `dist/cli/index.js` and `dist/worker/entry.js` carry a shebang. The
-  shebang comes from the hashbang line in each entry source file. Never add
-  a tsup `banner`; it would stamp every chunk in `dist/`.
+  shebang comes from the hashbang line in each entry source file. Never put a
+  shebang in the tsup `banner`; a banner is stamped on every chunk in `dist/`
+  (the existing banner only defines `require` for bundled CommonJS code).
 - The package ships no source maps, benchmarks, caches, or repo scripts. If
   a forbidden file appears, fix the `files` allowlist in `package.json`
   rather than deleting the file from the repo.
@@ -144,7 +142,7 @@ What `scripts/check-release.mjs` enforces, and how to respond when it fails:
   both package.json `files` and `scripts/release-manifest.json`.
   The double bookkeeping is deliberate: neither edit can silently drop a
   resource the CLI needs at runtime.
-- Size budgets: 10 MB tarball, 50 MB unpacked, set in `check-release.mjs`.
+- Size budgets: 12 MB tarball, 55 MB unpacked, set in `check-release.mjs`.
   They are a tripwire for packaging defects such as a leaked `node_modules`
   or a doubled `dist/`, not a diet. If a legitimate change exceeds them,
   raise the budget in the same PR with a justification, never as a drive-by.
@@ -156,6 +154,18 @@ subcommands behind dynamic imports, and keep heavyweight runtime dependencies
 in the `external` list so they load from `node_modules` only when a chunk
 that needs them runs.
 
+## Getting help and reporting problems
+
+- Questions, bug reports, and feature requests go to
+  [GitHub issues](https://github.com/iowarp/clio-coder/issues). Include the
+  Clio and Node versions, the relevant `clio-coder doctor` output, and steps
+  to reproduce, with credentials and sensitive project data removed.
+- Security issues follow [SECURITY.md](SECURITY.md), not a public issue.
+- Participation is governed by the [Code of Conduct](CODE_OF_CONDUCT.md).
+- Field reports from real research projects are the most useful input: a
+  difficult build, an unreliable model connection, or a workflow that needs
+  better support.
+
 ## Hard Rules
 
 1. The canonical repository's only branch is `main`. Maintainer topic,
@@ -317,10 +327,9 @@ requiring a network fetch.
 - Standalone agent, prompt, and fleet packages live under `library/agents/`,
   `library/prompts/`, and `library/fleets/`.
 - Working authoring templates for all five kinds live under `library/_authoring/templates/{skill,agent,prompt,fleet,plugin}/`.
-- `.claude-plugin/marketplace.json` and `.agents/skills/` are the generated outbound
-  surfaces. The first is regenerated by `library:pin`; the second is two symlinks at
-  the canonical trees so a Codex session started in a clone discovers them. Neither
-  holds a copied recipe body, and neither is edited by hand.
+- `.claude-plugin/marketplace.json` is the generated outbound surface. It is
+  regenerated by `library:pin`, holds no copied recipe body, and is never edited by
+  hand.
 - Core agent recipes (`src/domains/agents/builtins/`) and baseline fleets
   (`src/domains/agents/fleets/`) remain product-owned in `src/` and are not
   community library packages.

package/README.md

@@ -27,9 +27,9 @@
   <a href="https://github.com/iowarp/clio-coder/issues">Feedback</a>
 </p>
 
-Clio Coder is an open-source coding agent for your terminal. Ask it to explain a
-repository, investigate a failing test, or help implement a change. It reads the
-project, works with your tools, and shows you what it did.
+Clio Coder is an open-source coding agent that runs in your terminal. Ask it to
+explain a repository, investigate a failing test, or help implement a change. It
+reads the project, works with your tools, and shows you what it did.
 
 Built for scientific software and high-performance computing (HPC), Clio works
 with the code researchers maintain every day: simulation kernels, numerical
@@ -42,8 +42,10 @@ still needs your expertise. See [release notes](CHANGELOG.md) for current change
 
 ## Get started
 
-You need **Node.js 22.19 or newer**, Linux or macOS, and a running model server
-or API endpoint. Windows support is currently best effort.
+You need **Node.js 22.19 or newer** on Linux or macOS, and a model to talk to:
+a local inference server such as Ollama or LM Studio, your lab's gateway, or a
+cloud API. A local server usually needs no key. A gateway or cloud API gives you
+one, and Quick Connect asks for it. Windows support is currently best effort.
 
 ```bash
 npm install -g @iowarp/clio-coder
@@ -65,10 +67,18 @@ workspace edits with command approval, one worker at a time, a $5 tracked sessio
 budget, and a regular terminal interface. Other settings can wait. Escape goes
 back during setup; `clio-coder configure --settings` opens the full menu.
 
-**New in 0.4.7:** A unified Library for reusable workflows, operator extensions,
-safer keyboard controls, and a compact welcome header. See the
-[changelog](CHANGELOG.md) for release details and [Install](#install) for source
-builds and other package managers.
+`clio-coder` opens the **terminal interface (TUI)**: an interactive chat that
+shows tool calls and diffs as they happen. The same command is the **CLI** for
+setup, diagnostics, headless runs, and automation; `clio-coder --help` lists
+it. An optional local **browser app** over the same runtime is described under
+[Optional browser app](#optional-browser-app). The first session does not need it.
+
+**New in 0.4.9:** File tools report bounded reads, atomic edits, and partial
+search results more precisely. Script runs retain streamed logs and provenance,
+and scientific verification exposes explicit tolerance and non-finite policies.
+A capability gateway adds data inspection and trusted local MCP alongside
+secondary tools. See the [changelog](CHANGELOG.md) for release details and
+[Install](#install) for source builds and other package managers.
 
 ## Built for scientific software
 
@@ -304,6 +314,28 @@ Read the [Safety Model](docs/architecture/safety-model.md) and
 
 ## Install
 
+The npm-backed bootstrap installer checks prerequisites and guides you through
+terminal setup:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/iowarp/clio-coder/main/scripts/install.sh | bash
+```
+
+To preview it from a source checkout, run `bash scripts/install.sh --dry-run`.
+The installer targets Linux and macOS (on Windows, use the npm command above),
+requires Node.js 22.19+ and npm, and installs under
+`$HOME/.local` without sudo or shell-profile edits. It checks for
+conflicting launchers, prints PATH guidance, and runs Clio's post-install migrations.
+It opens no browser and enables no background service automatically. Its next-step
+instructions follow the commands supported by the version actually installed.
+
+Options include `--version <tag-or-version>`, `--prefix <directory>`,
+`--omit-optional`, and `--dry-run`; pass them to a downloaded script using
+`bash -s -- <options>`. A source-checkout symlink is preserved unless you explicitly
+select `--force`. If you enabled the background service, run `clio-coder web background uninstall`
+before removing the package. Remove an install at the default prefix with
+`npm uninstall -g --prefix "$HOME/.local" @iowarp/clio-coder`.
+
 The npm command in [Get started](#get-started) is the shortest path. Other
 package managers install the same CLI; Node.js is required for all of them.
 
@@ -341,7 +373,7 @@ can also be installed with your package manager. See
 From source, the latest stable release uses the pinned pnpm workflow:
 
 ```bash
-git clone --branch v0.4.7 https://github.com/iowarp/clio-coder.git
+git clone --branch v0.4.9 https://github.com/iowarp/clio-coder.git
 cd clio-coder
 corepack enable pnpm
 pnpm run install:local
@@ -384,7 +416,10 @@ For source installs, update your checkout and rerun `pnpm run install:local`.
 To remove the npm package, use `npm uninstall -g @iowarp/clio-coder`.
 Removing the package preserves Clio's user data. For a deliberate data purge,
 preview `clio-coder uninstall --dry-run`; `uninstall --remove-binary` also
-removes a local source launcher. Per-project files are preserved.
+removes a local source launcher. It stops and disables the owned web background service
+before deleting its state and removes its desktop entry. Ownership conflicts or a
+failed service stop preserve Clio state and report the problem. Per-project files
+are preserved.
 
 `clio-coder reset --help` lists selective reset options. Use `--dry-run` before
 a reset. The [lifecycle guide](docs/guide/installation-and-lifecycle.md) explains
@@ -392,52 +427,39 @@ exactly which settings, credentials, and session directories each option affects
 
 </details>
 
-## Optional interfaces
+## Optional browser app
 
-The terminal is the main starting point. Source checkouts also include a
-desktop/browser interface and a local viewer for recorded runs.
-
-<details>
-<summary><strong>Desktop and browser GUI</strong></summary>
-
-The GUI in `apps/workbench/` uses your existing Clio configuration. It requires
-Deno `>=2.9.5`, workspace dependencies, and `clio-coder` on `PATH`.
+The terminal is the primary interface. Clio Coder also packages a local browser
+app over the same runtime, projects, configuration, and model targets:
 
 ```bash
-cd apps/workbench
-deno task browser       # build and serve on localhost:4173
-deno task gui:install   # optional standalone local application
+clio-coder web --open
 ```
 
-The installed launcher is `clio-coder-gui`. Linux, including WSL2, is tested;
-native Windows launch is unavailable. Prebuilt GUI downloads are not distributed.
-The GUI keeps its own recent-project list; Clio owns sessions and authentication.
+It prints a private launch link and opens your default browser only when asked.
+The server binds to `127.0.0.1`, and its Traces page reads the trace database
+without modifying it. On Linux with a systemd user session,
+`clio-coder web background install --open` keeps the app available after login
+and lets you install it from the browser as a PWA; `web background status`,
+`stop`, and `uninstall` manage that service. Other platforms can run the
+foreground app while its server is running. The background service has been
+verified on Linux only; macOS and Windows have not been exercised. Development
+details are in [`apps/clio-coder-web/README.md`](apps/clio-coder-web/README.md).
 
-See the [GUI guide](apps/workbench/README.md) for installation, state locations,
-updates, and removal. There is no `clio-coder workbench` subcommand.
-
-</details>
-
-<details>
-<summary><strong>Read-only trace viewer</strong></summary>
-
-From a source checkout:
-
-```bash
-clio-coder trace ui --port 4600
-```
-
-The viewer binds to `127.0.0.1` and reads the local trace database without
-modifying it. The npm package does not include this app. See the
-[trace viewer guide](apps/trace-viewer/README.md).
-
-</details>
+`apps/workbench/` remains as reference source for future GUI work. It is excluded
+from workspace installation, recursive builds, publication, and product gates.
 
 ## Help and documentation
 
+The guides under [`docs/`](docs/README.md) are Markdown, ship with the package,
+and need no browser. To discover commands, use `clio-coder --help` (`--help
+--all` includes developer tools) and `/help` inside a session.
+`clio-coder docs [topic]` opens the same guides in the browser app; for example,
+`clio-coder docs safety` opens the safety guide, and `--no-open` prints the
+private launch link instead of opening a browser.
+
 If setup fails, start with `clio-coder doctor` and
-`clio-coder configure --section diagnostics`. To discover commands, use
-`clio-coder --help`; `--help --all` includes developer tools.
+`clio-coder configure --section diagnostics`.
 
 | Looking for… | Start here |
 | --- | --- |

package/dist/{acp-W3Y3TRHD.js → acp-ZWZCPS2A.js}

@@ -6,32 +6,32 @@ import {
 } from "./chunk-7WLRF2U5.js";
 import {
   runClioCommand
-} from "./chunk-GI5RRMAH.js";
-import "./chunk-6CA2BHOR.js";
-import "./chunk-4N2RZ4TO.js";
+} from "./chunk-KW6OJ7IY.js";
+import "./chunk-OA2GDACN.js";
+import "./chunk-IALGWTLO.js";
 import "./chunk-FXFVDPWY.js";
 import {
   printError
-} from "./chunk-3T4DXWP6.js";
-import "./chunk-4MFBBY2Z.js";
-import "./chunk-24TOGHPO.js";
-import "./chunk-6TAATXXH.js";
-import "./chunk-VNBICSS2.js";
-import "./chunk-DXVMLM3Z.js";
-import "./chunk-4QKAITQT.js";
+} from "./chunk-KIVFXGBM.js";
+import "./chunk-W72LLZAV.js";
+import "./chunk-X6FLVUM5.js";
+import "./chunk-FPS4R2RN.js";
 import "./chunk-DVNAPPXU.js";
-import "./chunk-E3LEPLQ2.js";
-import "./chunk-3XE4NRLF.js";
+import "./chunk-ZKJU55MX.js";
 import "./chunk-U2MSJ57E.js";
 import "./chunk-C27U2TYG.js";
+import "./chunk-ZKVMDNAN.js";
+import "./chunk-VNBICSS2.js";
+import "./chunk-B5GGDIHT.js";
+import "./chunk-DXVMLM3Z.js";
 import {
   MAX_TIMER_DELAY_MS
 } from "./chunk-6EXUUOSN.js";
 import "./chunk-DVJL77SO.js";
 import "./chunk-TK2BMCBZ.js";
-import "./chunk-B5GGDIHT.js";
-import "./chunk-ZZFWWYLX.js";
 import "./chunk-CTTI7G3T.js";
+import "./chunk-ZZFWWYLX.js";
+import "./chunk-E3LEPLQ2.js";
 import {
   init_esm_shims
 } from "./chunk-ECBHH7LU.js";
@@ -127,4 +127,4 @@ async function runAcpCommand(args, options = {}) {
 export {
   runAcpCommand
 };
-//# sourceMappingURL=acp-W3Y3TRHD.js.map
+//# sourceMappingURL=acp-ZWZCPS2A.js.map