@iowarp/clio-coder 0.4.6 → 0.4.8

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 pins), one build, the contract/smoke suite, and the trace-viewer suite.
-Use `pnpm run skills:check` when checking skill pins on their own; it is already
-included 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,
@@ -301,29 +311,101 @@ Agents should:
 - Leave remote writes, branch rules, and release tags to `@akougkas` unless
   explicitly instructed.
 
-## Skills
-
-`skills/` is the curated skills marketplace: maintainer-approved `SKILL.md`
-guides, distinct from the runtime skills any user can drop into a discovery
-root. It is not itself a discovery root, so nothing here auto-loads; skills
-activate after `clio-coder skills install <name>` or from an explicit
-`clio-coder --skill skills/<category>/<name>/SKILL.md` development path.
-
-To propose a skill:
-
-1. Add `skills/<category>/<name>/SKILL.md`. Follow the local
-   [`skill-craft`](skills/meta/skill-craft/) guidance: put trigger phrases in
-   `triggers`, keep `description` to the job and explicit routing boundaries,
-   and move conditional detail into `references/`.
-2. Include the core `name`, `description`, `version`, and `license` fields plus
-   a nested `clio-coder:` block with `registry-id`, `source-url`, `provenance`,
-   and `eval-status`. Ship an `evals.md` with the baseline scenarios.
-3. Verify locally with
-   `clio-coder skills validate skills/<category>/<name>/SKILL.md`.
-4. Install the candidate by name and confirm it appears with
-   `clio-coder skills list`.
-5. Open a PR. A maintainer reviews against the rubric, sets `audit: pass`,
-   approves the catalog version, then regenerates and checks the catalog with
-   `pnpm run skills:pin` and `pnpm run skills:check`.
-
-Full catalog conventions and install options: [skills/README.md](skills/README.md).
+## Library packages
+
+`library/` is the canonical home of shareable packages and recipes across the
+five supported kinds: `skill`, `agent`, `prompt`, `fleet`, and `plugin`.
+All five kinds share one portable package engine (a `plugin.json` manifest,
+exact semantic version, full-tree SHA-256 pin, and scoped lifecycle). Optional
+`extensions["ai.iowarp.clio"]` metadata declares Clio-specific kinds and resource
+paths; a conventional plugin with `skills/` needs no such metadata. Bundled packages are indexed in `library/registry.yaml`,
+ship with the npm package, and resolve relative to the installed index without
+requiring a network fetch.
+
+- Standalone skills live under `library/skills/<category>/<name>/`.
+- Domain bundles live under `library/plugins/<name>/` (e.g. `library/plugins/materio/`).
+- 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` 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.
+- Recipe packages may contain contained scripts for evaluation or workflow tasks;
+  these are declared metadata, executed only on explicit request, and are strictly
+  distinct from harness extension registration (which registers runtime tools,
+  hooks, and session UI under the separate extension lifecycle).
+
+### Contributor journey
+
+Follow this unified workflow to contribute or update a library package:
+
+1. **Choose package kind**:
+   - `skill`: Single procedure and supporting knowledge (`SKILL.md`).
+   - `agent`: Standalone worker recipe (`version: 1`, `skills: []`, `audience: custom`, strict budget and result contract).
+   - `prompt`: Reusable task template with path-derived invocation (`/<name> [args]`).
+   - `fleet`: Multi-agent coordination contract with a valid DAG and documented prerequisites.
+   - `plugin`: Composite bundle combining multiple resources (e.g., an agent binding a contained skill, prompts, assets).
+2. **Copy authoring template**:
+   Copy the matching template from `library/_authoring/templates/<kind>/` to begin with a valid envelope, manifest, and realistic scientific/HPC context. Templates are authoring material and are never entered into `library/registry.yaml`.
+3. **Author resources**:
+   - Single-kind packages expose exactly one public resource in their declared resource directory (`skills`, `agents`, `prompts`, or `fleets`).
+   - Keep `README.md` at the package root, outside the resource directory, so the loader does not discover it as a second public recipe.
+   - For skills, include house conventions: `triggers`, nested `clio-coder:` provenance block, and an `evals.md` with baseline/treatment scenarios (use `eval-status: scenarios-recorded` without claiming an audit was performed).
+4. **Validate**:
+   Run payload and manifest validation:
+   ```bash
+   clio-coder library validate <package-path> --json
+   ```
+   Validation is strictly read-only: it verifies manifest schemas, resource payloads, reference syntax (`${component:...}`, `${pluginRoot}`), and loadability without modifying workspace files or installation state.
+5. **Pin and check**:
+   Maintainers regenerate and verify library pins before release:
+   ```bash
+   pnpm run library:pin
+   pnpm run library:check
+   ```
+   If editing curated house skills in `library/skills/`:
+   ```bash
+   pnpm run skills:pin
+   pnpm run skills:check
+   ```
+   **Pins vs Evidence**: `library:pin` generates full-tree pins in `library/registry.yaml` covering every distributed byte for runtime distribution integrity. In contrast, `skills:pin` records normalized skill-body hashes in `library/skills/registry.yaml` and `skill-marketplace.json` as provenance evidence for audited instructions.
+
+   The same run regenerates `.claude-plugin/marketplace.json`, the repository's Claude Code marketplace, from those pins. Never edit it by hand. It publishes a package only when a peer host would load a real skill surface from it and nothing it would default-scan into a native component, and prints which packages it left out and why. An agent-, prompt- or fleet-only package is a normal contribution with no peer-host projection; it does not fail the pin.
+6. **Try in isolated project**:
+   Test the package using isolated registration and installation:
+   ```bash
+   clio-coder library register <package-path> --project
+   clio-coder library install <kind>:<name> --project
+   ```
+   Verify invocation through `/skill <name>`, `/run <agent-id> <task>`, `/<prompt-name>`, or `/fleet run <name>`. Browse the shared Library through `/library`, `/skills`, `/agents`, or `/prompts`.
+7. **Submit a focused fork PR**:
+   Push your topic branch to your fork and submit a PR against canonical `main`. Include problem, approach, validation evidence, and tests.
+
+### Skills
+
+`library/skills/` contains the curated skill packages: maintainer-approved `SKILL.md`
+guides, distinct from the runtime skills any user can drop into an active discovery
+root (`.clio-coder/skills/` or `<configDir>/skills/`). It is not itself a discovery
+root. Install with `clio-coder library install skill:<name>`, then activate with
+`/skill <name>`. An explicit `clio-coder --skill library/skills/<category>/<name>/SKILL.md`
+path is also available for development.
+
+Full catalog conventions and install options: [library/skills/README.md](library/skills/README.md) and [library/README.md](library/README.md).
+
+### Plugins
+
+`library/plugins/` is the publishing shelf for complete domain bundles. Packages use a
+portable root `plugin.json`, conventional `skills/`, and namespaced Clio metadata
+for native prompts, recipes, and fleets. Follow the
+[plugin authoring guide](docs/guide/authoring-plugins.md) and keep harness command
+implementations in the separate [extension lifecycle](docs/guide/harness-extensions.md).
+
+After changing any bundled file, run `pnpm library:pin` and review the updated
+full-tree digest in `library/registry.yaml`. Run `pnpm library:check` to verify
+the exact candidate; lint and the release gate include this check. Add behavior
+tests for lifecycle changes and validate an installed package's actual resources,
+including package-local references and bound skills. Peer projections must state
+which host capabilities they translate and which they omit.

package/NOTICE

@@ -56,3 +56,11 @@ git.yazi (https://github.com/yazi-rs/plugins/tree/main/git.yazi)
   Copyright 2023 the yazi-rs authors.
   Licensed under the MIT License.
   Vendored as source with its LICENSE under the managed file-pane profile.
+
+Bundled terminal compatibility code
+----------------------------------
+Clio bundles the JavaScript from @earendil-works/pi-tui 0.85.1 with a local
+input-policy/search/semantic-edit patch, plus marked and get-east-asian-width.
+Their MIT notices are distributed in dist/assets/tui-notices/. The pinned
+pi-tui runtime package remains installed for its Darwin and Windows native
+helpers; Clio does not modify consumer dependencies during installation.

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,8 +67,17 @@ 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.6:** Quick Connect and simpler output styles. See
-[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.8:** More reliable live settings, provider accounting and runtime
+cleanup, an npm-backed installer, and an optional web app with documentation
+generated from the Markdown guides. See the
+[changelog](CHANGELOG.md) for release details and [Install](#install) for source
+builds and other package managers.
 
 ## Built for scientific software
 
@@ -94,6 +105,7 @@ Tool calls appear as they run, and edits appear as diffs.
 | --- | --- |
 | Find commands | `/help` |
 | Change models or settings | `/settings` |
+| Browse reusable recipes | `Alt+L` or `/library` |
 | Check context use or cost | `/context`, `/cost` |
 | Include a project file | Type `@` and choose a path |
 | See delegated tasks | `/tasks` |
@@ -111,11 +123,11 @@ Tool calls appear as they run, and edits appear as diffs.
 | Delegate a focused task | `/run tester "Run the parser tests and explain any failure."` |
 | Branch or resume a conversation | `/tree`, `/fork`, `/resume`, `/new` |
 | Carry current state into a fresh session | `/handoff <goal>` |
-| Browse agents, prompts, and skills | `/resources` |
+| Open a Library category | `/skills`, `/agents`, `/prompts` |
 | Load a specialized skill | `/skill <name>` |
 | Export the transcript | `/export` |
 
-Enter steers an active turn; `Alt+Enter` queues a follow-up; Escape cancels.
+Enter steers an active turn; `Ctrl+Q` queues a follow-up; Escape cancels.
 Pasted multiline text beginning with `!` or `!!` is treated as prompt text.
 Private shell output remains visible to you but is excluded from model replay
 and compaction. See [Commands and Modes](docs/guide/commands-and-modes.md).
@@ -203,6 +215,35 @@ Read about [project context](docs/architecture/context-engine.md),
 
 </details>
 
+<details>
+<summary><strong>Domain plugins and materials research</strong></summary>
+
+Install a complete workflow with its prompts, agents, skills, scripts and references:
+
+```bash
+clio-coder library search
+clio-coder library install plugin:materio --user
+```
+
+In a new session, start with `/materio:help` or
+`/materio:identify-research`. The workflow progresses through
+supplied-paper literature review, lab feasibility, research tasks, verified
+execution, and a text handoff to WTF-P for paper planning. Researchers retain
+control of assumptions and scientific decisions.
+
+The [Library](library/README.md) bundles skills, agent recipes, prompts, fleets,
+and plugins with Clio-Coder. It verifies complete package pins and supports
+previews, updates, removal and drift checks. Its portable skills can also be
+installed in Claude Code and discovered by Codex; Clio-Coder can review and
+import supported packages from those hosts. The [interop guide](docs/guide/interop.md)
+documents the measured formats and their limits. [Plugin usage](docs/guide/plugins.md),
+[package authoring](docs/guide/authoring-plugins.md), and
+[harness extensions](docs/guide/harness-extensions.md) describe the plugin and
+harness-extension contracts. WTF-P installs as a plugin with `clio-coder library
+install`; remove an older extension copy with `clio-coder extensions remove wtfp`.
+
+</details>
+
 <details>
 <summary><strong>Multi-agent workflows and workers over SSH</strong></summary>
 
@@ -272,6 +313,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.
 
@@ -309,7 +372,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.6 https://github.com/iowarp/clio-coder.git
+git clone --branch v0.4.8 https://github.com/iowarp/clio-coder.git
 cd clio-coder
 corepack enable pnpm
 pnpm run install:local
@@ -352,7 +415,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
@@ -360,52 +426,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.
-
-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>
+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).
 
-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 |
 | --- | --- |