@iowarp/clio-coder 0.4.5 → 0.4.7

package/docs/guide/skills-marketplace.md

@@ -1,93 +1,56 @@
-# Skills Marketplace
+# Skills in the library
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Skills Marketplace visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/skills_blueprint.html).
+> **Visual blueprint:** See the [Skills visual reference](../html/skills_blueprint.html) in the source checkout.
 
-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.
+Skills are one kind of [library package](resource-library.md). `/skills` opens the Library overlay's skill tab directly, while `/library` opens the full overlay (covering skills, plugins, agents, prompts, and fleets). `/skill <name>` invokes a skill, and `/skill off` clears the session's active tool surface; bare `/skill` returns usage guidance pointing to `/skills`. Skill packages use the same manifest, version, full-tree digest, origins, scope and lifecycle as every other package.
 
-## Operator ownership of installed skills
-
-The active project `.clio-coder/skills/` tree and the resolved user `<configDir>/skills/` tree are operator-owned. Main-agent and worker tool admissions refuse writes, edits, artifacts and recognized shell mutations to either tree, including ancestor deletion and current symlink aliases. This boundary stays active at every autonomy level, even when the general default path policy is disabled. Reads and loading already installed skills retain their existing rules.
-
-Draft a proposed skill outside these active trees, for example in `draft-skills/`. The operator installs or updates it through `clio-coder skills install`, `skills update`, `skills sync`, `library add --yes`, the Skills Hub, `/skill <name>`, or an explicitly accepted marketplace offer. Even `full-auto` must wait for that offer's bound operator answer; a task match alone no longer installs a skill. Model shell calls to recognizable Clio skill installation, update and sync commands are refused. Confirmed `library add --yes` commands are also reserved for operators, including additions of other resource kinds that may install skill dependencies. An unconfirmed `library add` only prints a plan and remains available, as do inventory, search, inspection and validation commands.
-
-This is a tool-admission boundary, not an operating-system sandbox. Shell inspection covers literal paths and recognized command forms, respecting comments, quoted words and redirection operands when identifying Clio commands. Quoted search patterns remain read-only, and literal operator filenames do not hide later mutation operands. It cannot prove the effects of arbitrary scripts, dynamically constructed paths, aliases, or concurrent filesystem changes. Keep shell execution supervised when stronger confinement is required.
-
-## Where marketplace rows come from
-
-There is one source, `discoverMarketplaceSkills()` in `src/domains/resources/skills/marketplace.ts`, and it reads two kinds of real local data:
-
-1. **A catalog directory** of actual `SKILL.md` packages. Resolution order: `CLIO_CODER_SKILL_CATALOG_DIR`, then a `skills/` directory in the working tree when it holds packages, then the `skills/` catalog the installed clio-coder package carries. Metadata comes from the packages themselves through the skill loader, so a row's version, category, and audit state are the package's own.
-2. **A JSON index** whose entries name a `sourceUrl` that `clio-coder skills install` accepts. Resolution order: `CLIO_CODER_SKILL_MARKETPLACE_INDEX`, then `<configDir>/skill-marketplace.json`, then the package's own `skills/skill-marketplace.json`. `pnpm run skills:pin` publishes that file's `version`, `audit`, and `category` fields.
-
-The package fallbacks mean a fresh npm install has a marketplace with no configuration: `clio-coder skills search grill` lists `grill-me` from the shipped catalog, `clio-coder skills install grill-me` copies it out of the package into `.clio-coder/skills/`, and `/skill grill-me` offers that install before running. The shipped catalog is a marketplace source only, never a discovery root: nothing from it is loadable until the operator installs it, which keeps the install-then-activate contract and the per-skill scope choice in the operator's hands.
-
-Catalog packages win over index entries on a name collision, because the local files are the thing that installs. Neither source reaches the network; the hub opens on local data and never blocks. Only an index entry whose `sourceUrl` is a GitHub URL, and that no catalog also carries, needs the network at install time.
-
-The model sees the same lookup: `context(scope="skills")` lists installed skills and, under a `Marketplace (not installed)` heading, the entries this lookup would install. Loading a marketplace-only skill by name answers "not installed" and points at `/skill <name>`, never `unknown skill`.
-
-When both sources are absent (a source checkout with no `skills/` folder, or an incomplete package) the hub has nothing to list and says so, naming the remedy:
-
-```
-no skills installed and no local marketplace configured. install one with
-`clio-coder skills install <path|github-url>`, or point CLIO_CODER_SKILL_CATALOG_DIR at a
-skills/ catalog.
+```bash
+clio-coder library search grill --kind skill
+clio-coder library install skill:grill-me --project --dry-run
+clio-coder library install skill:grill-me --project
+clio-coder library skills --all --json
 ```
 
-The CLI reports the same state as `no local skill marketplace catalog or index configured`. A marketplace source that exists but fails (an unreadable index, a broken catalog package) is a diagnostic row in the hub, not a silent omission.
-
-The same index machinery can also describe agent recipes, prompt templates, and fleet contracts through typed entries and requirements. See [resource-library.md](resource-library.md) for the schema, private catalog, installation roots, and `clio-coder library` commands. Those kinds render on their own tabs in the hub, described below.
-
-## Using the hub
-
-| Key | Action |
-|---|---|
-| type | Filter all groups |
-| `←`/`→` | Switch tabs |
-| `Enter` | Use the selected row: insert `/skill <name> ` into the editor for the task text, or the invocation the row's kind is called by |
-| `Tab` | Toggle the detail pane (split layout on wide terminals) |
-| `i` | Install the selected row through the resolver its kind installs by |
-| `PgUp`/`PgDn` | Scroll the detail pane |
+The bundled index makes complete packages available without installing them. An ordinary packaged skill copies from Clio's shipped files without network access. Local user and project registrations can add packages. Automatic offers and `/skill <name>` use the same library entries and package installer. An unmanaged `SKILL.md` remains a valid runtime resource; preparing a distributable requires a package manifest as described in [authoring](authoring-plugins.md).
 
-Invoking an uninstalled marketplace skill with `/skill <name>` prompts before installing it. `i` runs the same install path eagerly from the hub.
-
-## Tabs
+## Operator ownership of installed skills
 
-The hub carries one tab per resource-library kind: Skills, Agents, Prompts, and
-Fleets. `←` and `→` move between them. The frame title names the active tab and
-the footer states its row count, so the numbers on screen always describe the
-tab being read. `/skill` opens Skills; `/resources library <kind>` opens the
-requested library tab.
+Active `.clio-coder/skills/`, `<configDir>/skills/`, and managed package trees are operator-owned. Main and worker tool admission refuses recognized model writes, edits, deletes and shell mutations to those trees at every autonomy level. Library install, update, registration, enable/disable, removal and pin actions are reserved for the operator; install/update `--dry-run`, search, inspection and draft validation remain available. This is a tool-admission boundary, not an operating-system sandbox for arbitrary scripts or dynamically constructed shell commands.
 
-The Skills tab is unchanged. The other three list the entries of their kind from `discoverLibrary()`, which is the same discovery `clio-coder library list --kind <kind>` reads, so the hub and the CLI never disagree about what exists. Each row carries the entry's origin and version, whether it is installed or available, the short form of its recorded pin hash, and, in the warning token, the names of any requirements it still needs. An entry the catalog refuses outright, because a requirement is missing, malformed, or cyclic, appears as a diagnostic row rather than being omitted.
+Draft outside active roots, for example `draft-skills/example/`. The operator can review `library validate draft-skills/example/SKILL.md`, then register and install a complete package. Explicitly accepted skill offers install through the library. A lexical match alone never grants installation authority, including at `full-auto`.
 
-`Enter` uses the selected row. An agent inserts `/run <agent> ` into the composer, a prompt inserts its `/<id> ` invocation, a skill does what the Skills tab does, and a fleet closes the hub and opens the `/fleet run` approval preview for that contract. A row that is not installed says so instead and points at `i`.
+## Library keys and runtime use
 
-`i` installs, through the same plan-then-write pair `clio-coder library add` runs. A framed confirmation states every destination path and SHA-256 hash before anything is written, which is the TUI spelling of the CLI's `--yes` gate; `Esc` there leaves every destination untouched. An entry whose requirements are not all installed is refused by name on the first `i`, and a second `i` opens the install-with-requirements confirmation, which names every entry it would write in dependency order.
+| Key | Action |
+| --- | --- |
+| Type | Filter rows |
+| Left / Right | Change kind tab |
+| `s` | Switch user/project action scope |
+| `Enter` | Use a selected runtime resource or inspect a plugin |
+| `i` | Review installation; a second request can include missing requirements |
+| `u` | Review update |
+| `e` | Enable or disable the selected installed copy |
+| `r` | Review removal |
+| `p` | Verify and show the recorded package pin |
+| `d` | Check installed drift |
+| `Esc` | Close or cancel |
 
-The CLI `clio-coder skills` commands manage local skill discovery, validation, and
-creation. Extension resource roots and share archives are documented in
-[extensions-and-sharing.md](extensions-and-sharing.md); this page owns the TUI
-Hub and marketplace behavior.
+`/skill <name> [task]` activates a skill; `/skill off` clears the session's tool-surface narrowing. Loading can narrow allowed tools but cannot grant tools the host disallows. At `read-only` and `suggest`, activation requires an operator request; `auto-edit` and `full-auto` may activate installed skills. Listing available skills does not load their bodies.
 
-## Remote entries and overlays
+Model-visible skills must be trusted and permit model invocation. Foreign project resources and all interop-adopted foreign skills require `integrations.projectResources.trustProjectImports`. A project resource adopted into user scope retains foreign trust. Disabled, incompatible or drifted package resources do not load. `/library reload` refreshes an active session after a lifecycle change.
 
-Some skills are worth carrying in the catalog without vendoring their content. `skills/remote.yaml` lists them: each entry names a skill, its category, a `sourceUrl` that must be a GitHub tree URL at a pinned tag, an `overlay` package inside the catalog, and an optional `exclude` list of upstream top-level members. `pnpm run skills:pin` publishes such an entry into `skills/skill-marketplace.json` with `origin: "remote"`, the upstream URL as its `sourceUrl`, and the `overlay` and `exclude` fields attached. The overlay's `SKILL.md` is pinned in `skills/registry.yaml` like every other catalog skill, so `pnpm run skills:check` fails when it drifts.
+For duplicate skill names or paths, trusted candidates take precedence over untrusted candidates. An untrusted `.claude/skills` or `.agents/skills` copy cannot hide a trusted Library installation. Normal scope precedence still decides between trusted copies, including project compatibility roots the operator explicitly trusts. A named load of an untrusted or manual-only skill reports that restriction instead of claiming the skill is unknown.
 
-`archify` is the worked example. Its entry points at `https://github.com/tt-a1i/archify/tree/v2.16.0/archify`, overlays `skills/planning/archify`, and excludes `test` and `package-lock.json`. Running `clio-coder skills install archify --project` clones that tag, drops the excluded members, copies the overlay over the clone so Clio's wrapper `SKILL.md` replaces the upstream one, validates the shaped tree, and swaps it into `.clio-coder/skills/archify/` with the usual provenance stamps. The renderer, its schemas, and its brand-mark notices come from upstream at install time and never enter the npm tarball. The wrapper omits upstream's update-awareness step on purpose: that step performs a network request during a chat turn, and no Clio chat turn depends on the network.
+## Matching, authoring and evals
 
-Discovery treats the overlay folder as part of the remote entry rather than as a skill of its own, so a bare-name install never lands the wrapper without the renderer it wraps. `clio-coder skills update` recovers the same overlay and exclude list from the marketplace, so an update refetches the pinned upstream and re-applies the wrapper instead of replacing it.
+Authored whole-phrase triggers rank before incidental name or description overlap. Matches are lexical suggestions, not evidence that a model will offer or successfully use a skill. Headless sessions emit passive library-install guidance and do not open an interview. Interactive offers require a bound operator answer.
 
-Two operational notes. A copy dropped into a project-scope `.claude/skills/archify` is a compat import and stays untrusted until `integrations.projectResources.trustProjectImports` is on; install through Clio to get a trusted, provenance-stamped copy. And since the skill's authoring loop is several `bash` calls (validate, deliver, verify), `auto-edit` is the sensible permission posture for a mapping session; full manual approval works but prompts on every command.
+House skills live in `library/skills/<category>/<name>/`, with `SKILL.md`, a package `plugin.json`, and authored `evals.md` scenarios. `skills:check` checks authoring metadata and normalized audit evidence; `library:check` verifies the distributable's complete tree. Only the latter is an installation pin. Explicit catalog-directory and old skill-index probes remain available to authoring utilities for unmanaged source audits; automatic library installation does not use those as a separate installer.
 
-Architecture mapping through Archify follows a structured pipeline across distinct stages: deterministic structural seed generation (`clio-coder context map`), model-authored refinement, deliverable validation (`validate`, `deliver`, profile checks, and Clio verifiers), and review. Clio derives the deterministic architecture seed from the structural codewiki without model calls; Archify validates and renders the model's semantic refinements. Standard validation checks schema conformance and layout composition, while verification commands check path and symbol citations against the workspace. Mechanical validation passes do not establish semantic claims or visual layout quality: source review assesses semantic claims, while visual review in a browser assesses layout presentation. Custom model-authored maps can remain layout-invalid until iteratively refined.
+Named suite evals use `clio-coder eval run --package skill:<name> --eval <suite>`. The experimental `clio-coder eval skill <name|path>` runs `evals.md` baseline, treatment and model-judge scenarios. Fixture commands require `--trust-fixtures`; network tools remain off unless `--allow-network` is requested. Those measurements are separate from deterministic package validation.
 
 ## Publishing a skill
 
-Add a directory under `skills/<category>/<name>/` (or `skills/<name>/`) in the repo containing a `SKILL.md` with `name` and `description` frontmatter. The directory name must match `[A-Za-z0-9][A-Za-z0-9._-]*`. Run `pnpm run skills:pin` to republish `skills/skill-marketplace.json`, which is the index consumers point `CLIO_CODER_SKILL_MARKETPLACE_INDEX` at or copy to `<configDir>/skill-marketplace.json`. Scientific and niche coding domains are the marketplace's focus; see the existing `skills/` tree for the house format.
-
-## Matching and offers
-
-Authored whole-phrase triggers rank before incidental description or name overlap. Matching remains lexical: interactive offer guidance asks the model to check installed alternatives and relevance before presenting an offer. A match does not guarantee that a model will offer or use the skill.
+To publish a skill, prepare a complete skill package with `SKILL.md` and a portable root `plugin.json`. Declare kind `skill`, an explicit Semantic Version, the skill resource root and one public skill component. Validate the package with `clio-coder library validate ./my-skill`, then register its local source with `clio-coder library register ./my-skill --project`. Registration records its full-tree digest without installing it. Install the candidate with `clio-coder library install skill:<name> --project` and verify its behavior before sharing.
 
-Interactive offers require a bound operator answer before installation. Headless runs emit a passive installation hint; that reminder opens no interview and performs no installation or activation. Installing a skill makes it discoverable; listing it or supplying an explicit skill path makes it available, while loading its body remains subject to activation policy. At `read-only` and `suggest`, activation requires an operator request; `auto-edit` and `full-auto` may activate installed skills. A suggestion alone continues the task without activation.
+For a curated contribution, add the reviewed package beneath `library/skills/<category>/<name>/`, include authored eval scenarios, and regenerate both the skill authoring records (`pnpm skills:pin`) and complete library package pins (`pnpm library:pin`). A shared remote index must name an explicit supported GitHub tree source, version and full-tree SHA-256. The [package authoring guide](authoring-plugins.md) defines the manifest and index fields; publishing does not itself install or activate the skill for another operator.

package/docs/guide/tool-usage.md

@@ -14,7 +14,7 @@ context) share one result envelope, implemented in `src/tools/observation.ts`.
 The OBSERVE policy plane also contains `credential_present`, whose deliberately
 minimal result does not use that envelope.
 
-Per-call byte caps: read 50KB (`safety.limits.readBytesPerCall`), grep 16KB for mode=content and 8KB for mode=files/count, find 8KB, ls 8KB, code_nav 16KB, context 16KB for scope=docs and 50KB for scope=skills/workspace.
+Per-call byte caps: read 50KB (`safety.limits.readBytesPerCall`), grep 16KB for mode=content and 8KB for mode=files/count, find 8KB, ls 8KB, code_nav 16KB, context 16KB for scope=docs and scope=library, and 50KB for scope=skills/workspace.
 
 Truncated text results append exactly one notice line:
 
@@ -428,16 +428,19 @@ git(op="diff", path="src/tools/safe-exec.ts")
 git(op="log", limit=10)
 ```
 
-## context: workspace snapshot, docs retrieval, and skills
+## context: workspace snapshot, docs retrieval, skills, and the library catalog
 
-One OBSERVE entry point for material about the working environment rather than the tree itself. Sources: `src/tools/context/index.ts`, `src/tools/context/docs-engine.ts`.
+One OBSERVE entry point for material about the working environment rather than the tree itself. Sources: `src/tools/context/index.ts`, `src/tools/context/docs-engine.ts`, `src/tools/context/library.ts`.
 
 Arguments:
 
-- `scope` (required). `workspace`, `docs`, or `skills`.
-- `query` (scope=docs). Question or terms; omit to list the corpus (files plus doc/section counts) instead of searching.
-- `limit` (scope=docs). Max sections; default 5, max 12.
+- `scope` (required). `workspace`, `docs`, `skills`, `library`, or `recall`.
+- `query` (scope=docs). Question or terms; omit to list the corpus (files plus doc/section counts) instead of searching. At scope=library, name, owner, or description terms.
+- `limit` (scope=docs). Max sections; default 5, max 12. At scope=library, max rows; default 20, max 50.
 - `name` (scope=skills). Skill to load; omit to list.
+- `kind` (scope=library). One of `skill`, `agent`, `prompt`, `fleet`, or `plugin`.
+- `ref` (scope=library). An exact `kind:name` package reference, a resource key, or a bare runtime name.
+- `offset` (scope=library, scope=recall). Zero-based; follow the reported `nextOffset`.
 - `include_tree` (scope=skills, boolean). List up to 50 files under the skill's base_dir.
 
 `scope="workspace"` returns the session's git/project snapshot as JSON, probing and caching it on first call. When model-visible skills are installed, the payload carries a one-line `skills` pointer (count plus the suggest protocol) so orientation surfaces the catalog; the pointer never includes catalog entries and never changes the load gate. It requires a bound session; worker registries without one get a clean error. 50KB cap.
@@ -449,11 +452,18 @@ vocabulary aliases, phrase boosts, and BM25-style body scoring. The JSON payload
 
 `scope="skills"` with no `name` lists installed skills with descriptions. A matching suggestion uses `Suggested skill: /skill <name>` and continues the task without activating a skill. At `read-only` and `suggest`, loading requires an explicit operator request; at `auto-edit` and `full-auto`, policy permits activation of installed skills without that request. Recipe-bound workers may load only their declared skills. Installation, availability, and activation are separate: even `full-auto` requires a bound operator acceptance for a marketplace installation. A pending request's task text is surfaced with the body. Marketplace-installed skills are drift-checked against their pinned hash; a mismatch annotates the result with a `skill_drift` warning but never blocks. 50KB cap; a truncated body offloads in full.
 
+`scope="library"` is the read-only recipe catalog, backed by the same bounded inventory `clio-coder library recipes --json` reads, and it activates, installs, registers and pins nothing. Rows are tagged and never mixed up with one another. A `resource` row is a recipe that actually loaded: its runtime name (skill frontmatter name, agent recipe id, prompt path with colons, fleet contract name), owning package or `core`/`user`/`project`/`compat` source class, scope, origin evidence, format, and the invocation that works. A `hint` row is a catalog claim about one member of a package: it names the owning package, that owner's installed copy states, and the member's own state (`not-installed` when the owner is not installed, `unknown` when the owner is installed and the member did not turn up), and it never carries an invocation because nothing loaded it. A `package` row is the install target itself with its version, origin, installed copies, and bounded `provides` hints; a package with no hints reports its contents as unknown until inspection rather than empty.
+
+The model view is the model audience: internal and shadow agents, untrusted, invalid, shadowed and manual-only resources are not listed. `kind="plugin"` returns plugin-kind install targets only; any recipe kind returns the loaded resources of that kind plus the installable owners that provide it, so an Agents or Prompts query finds the owning bundle before it is installed and without fetching its source. `ref` may match one exact resource key, several same-named records across kinds (the payload says so and each row carries its `key`), or a package, which opens that package's members. A run started with `--no-skills` lists no skill rows, because nothing in it can load one. Instruction bodies and absolute recipe paths are never returned. 16KB cap: the page is fitted to the remaining budget before it is rendered, so `limit` is an upper bound and `nextOffset` carries the remainder; `total` counts what the inventory returned and is flagged `totalIsLowerBound` when the inventory hit its own record cap. Worker registries have no library projection of their own and get a clean unavailable error.
+
 ```text
 context(scope="workspace")
 context(scope="docs", query="dispatch receipts evidence", limit=8)
 context(scope="skills")
 context(scope="skills", name="context-prime", include_tree=true)
+context(scope="library", kind="agent", query="materials")
+context(scope="library", ref="plugin:materio")
+context(scope="library", limit=20, offset=20)
 ```
 
 ## code_nav: navigate the codewiki index
@@ -725,6 +735,8 @@ Arguments:
 
 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.
 
+What the operator sees is one box above the composer, sized to the round: the question header, the question with bold spans and hanging numbered lists, then every option with its whole description. A round of several questions names them all in a strip at the top. A question longer than the box scrolls with PgUp/PgDn while its options stay on screen. Enter records the focused option; `t` records it and opens a multi-line answer field (Shift+Enter for a newline, Esc back to the options); an option whose label says the operator will type, such as "Provided details" or "Other", opens the field on Enter. Space toggles a multi-select option, Left/Right move between the questions of a round, `a` opens the answers recorded so far, and `?` shows the decision's tier, effect, and reversibility. Each answered round is recorded in the transcript as the question headers and the answers.
+
 Ask only when blocked on a decision the request does not answer. Never ask about anything the operator already stated: a request that names its own scope ("all tools", "read only") has answered the interview before it starts.
 
 ```text
@@ -745,7 +757,7 @@ Arguments:
 
 `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](../architecture/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.
+Skills are not artifacts. A skill is a `SKILL.md` folder, and the active skill trees (`.clio-coder/skills/`, `.clio-coder/plugins/`, `.clio-coder/extensions/`, and their user-scope counterparts) are operator-owned: model-side writes and deletes there are refused, reads are not. Draft a skill somewhere else in the workspace, check it with `clio-coder library validate <path>`, and leave installation to the operator through `clio-coder library install` or `/library`. The `skill-craft` shipped skill documents the format and craft rules.
 
 ```text
 artifact(kind="plan", content="# Migration plan\n\n## Step 1 ...")

package/docs/guide/troubleshooting.md

@@ -16,7 +16,7 @@ diagnostics in the current source tree.
 | `clio-coder run cannot confirm permission requests; rerun interactively to approve this action.` | A tool call required manual permission confirmation during a non-interactive headless `clio-coder run` execution. | Run the command interactively in the TUI (`clio`) to grant one-shot approval, adjust the workspace policy in `.clio-coder/safety.yaml`, or run with `--autonomy full-auto` if safe. |
 | `no trace database yet at <path>` | The trace mirror database has not been initialized because no interactive sessions or dispatches have executed yet. | Execute a turn or dispatch a task. In SQLite trace commands, this notice is informational (exit code `0`). |
 | `trace database not found: <path>` | An explicit `--db <path>` flag was provided pointing to a nonexistent database file. | Verify the database path or omit `--db` to use the default state directory database (`<stateDir>/trace.sqlite`); the next line prints that default path. |
-| `no local skill marketplace catalog or index configured` | No catalog directory (`CLIO_CODER_SKILL_CATALOG_DIR`, a `skills/` folder in the working tree, or the installed package's own `skills/` catalog) and no JSON index (`CLIO_CODER_SKILL_MARKETPLACE_INDEX`, `<configDir>/skill-marketplace.json`, or the package's `skills/skill-marketplace.json`) was found. On an npm install this means the package is incomplete; check `clio-coder doctor`. | Point `CLIO_CODER_SKILL_CATALOG_DIR` at a `skills/` catalog or `CLIO_CODER_SKILL_MARKETPLACE_INDEX` at a valid `skill-marketplace.json`, or install a skill directly via `clio-coder skills install <path\|github-url>`. |
+| `no local skill marketplace catalog or index configured` | No catalog directory (`CLIO_CODER_SKILL_CATALOG_DIR`, a `library/skills/` folder in the working tree, or the installed package's own `library/skills/` catalog) and no JSON index (`CLIO_CODER_SKILL_MARKETPLACE_INDEX`, `<configDir>/skill-marketplace.json`, or the package's `library/skills/skill-marketplace.json`) was found. On an npm install this means the package is incomplete; check `clio-coder doctor`. | Point `CLIO_CODER_SKILL_CATALOG_DIR` at a `library/skills/` catalog or `CLIO_CODER_SKILL_MARKETPLACE_INDEX` at a valid `skill-marketplace.json`, or install a skill directly via `clio-coder library install <path\|github-url>`. |
 | `<arg> is a global option and must come before the subcommand: clio-coder <usage> <command> ...` | A global CLI option (such as `--api-key`, `--no-context-files`, or `-nc`) was placed after the subcommand name. Directory roots are configured via `CLIO_CODER_*_DIR` environment variables. | Move the flag before the subcommand name (e.g. `clio-coder --api-key <key> run ...` instead of `clio-coder run --api-key <key> ...`). |
 | `target <id> is not registered` | The designated target ID does not exist in `settings.yaml`. | Run `clio-coder targets` to view available targets, or configure a new target using `clio-coder targets add`. |
 | `budget: ceiling must be >= 0 (got <val>)` | A negative session cost ceiling reached the scheduling budget (`src/domains/scheduling/budget.ts`). | Set a non-negative `safety.limits.sessionCostUsd` in `settings.yaml`, or edit Session ceiling (USD) in Settings → Budget. |

package/docs/process/development-pipeline.md

@@ -18,27 +18,27 @@ under pressure; git mechanics alone never justify a stage.
 
 | Stage | Skill | Output |
 | --- | --- | --- |
-| 1. File | [`file-ticket`](../../skills/git/file-ticket/) | A labeled GitHub issue with evidence and acceptance criteria |
-| 2. Fix | [`fix-issue`](../../skills/git/fix-issue/) | An uncommitted, verified change where failing tests preceded the fix, self-reviewed against the issue's acceptance criteria |
-| 3. Ship | [`ship`](../../skills/git/ship/) | An atomic conventional commit referencing the issue (`fixes #N`); contributors push it to their fork and open a PR, while maintainer work stays local for gated integration; merge is a human decision |
+| 1. File | [`file-ticket`](../../library/skills/git/file-ticket/) | A labeled GitHub issue with evidence and acceptance criteria |
+| 2. Fix | [`fix-issue`](../../library/skills/git/fix-issue/) | An uncommitted, verified change where failing tests preceded the fix, self-reviewed against the issue's acceptance criteria |
+| 3. Ship | [`ship`](../../library/skills/git/ship/) | An atomic conventional commit referencing the issue (`fixes #N`); contributors push it to their fork and open a PR, while maintainer work stays local for gated integration; merge is a human decision |
 
 Releases follow [release-cut-checklist.md](release-cut-checklist.md) as a
 human-gated checklist, not a skill. Worktrees
-([`worktree-create`](../../skills/git/worktree-create/),
-[`worktree-merge`](../../skills/git/worktree-merge/)),
-[`branch-closeout`](../../skills/git/branch-closeout/),
-[`resolve-merge-conflicts`](../../skills/git/resolve-merge-conflicts/), and
-[`tdd`](../../skills/coding/tdd/) are à-la-carte tools reached for when the
+([`worktree-create`](../../library/skills/git/worktree-create/),
+[`worktree-merge`](../../library/skills/git/worktree-merge/)),
+[`branch-closeout`](../../library/skills/git/branch-closeout/),
+[`resolve-merge-conflicts`](../../library/skills/git/resolve-merge-conflicts/), and
+[`tdd`](../../library/skills/coding/tdd/) are à-la-carte tools reached for when the
 situation calls for them, not stages every change passes through. An RCA
 written as the closing comment on the issue (`rca` label) is an artifact of
 hard bugs, not a mandatory toll booth. Batch ticket creation from a PRD
-bypasses stage 1 and uses [`backlog`](../../skills/planning/backlog/)
+bypasses stage 1 and uses [`backlog`](../../library/skills/planning/backlog/)
 instead; everything downstream is identical.
 
 ## Closeout
 
 A merged PR is not operationally finished until its local scaffolding is
-closed. The reusable [`branch-closeout`](../../skills/git/branch-closeout/) skill automates this verification and teardown safely. After the human merge decision:
+closed. The reusable [`branch-closeout`](../../library/skills/git/branch-closeout/) skill automates this verification and teardown safely. After the human merge decision:
 
 1. Fetch and prune, confirm the PR's merged state, and identify the resulting
    commit on `origin/main`. Direct ancestry proves an ordinary merge; a squash
@@ -59,7 +59,7 @@ closed. The reusable [`branch-closeout`](../../skills/git/branch-closeout/) skil
    `refs/heads/main`; every survivor needs an owner and purpose.
 
 Maintainer release candidates are local-only and use a compact branch name
-that cannot collide with their tag: branch `v043`, tag `v0.4.3`. Gate the exact
+that cannot collide with their tag: branch `v046`, tag `v0.4.6`. Gate the exact
 candidate, require fetched `origin/main` to be its ancestor, fast-forward local
 `main`, fetch again, and push only `refs/heads/main:refs/heads/main` with
 explicit authorization. After CI passes, push only the fully qualified
@@ -142,13 +142,13 @@ or bumped; the milestone closes when the tag is published.
 
 ## Dogfooding setup
 
-The marketplace copy under `skills/git/` is the committed source of truth,
-pinned in `skills/registry.yaml` by `pnpm run skills:pin`. Runtime roots are
+The marketplace copy under `library/skills/git/` is the committed source of truth,
+pinned in `library/skills/registry.yaml` by `pnpm run skills:pin`. Runtime roots are
 gitignored, so each developer installs locally:
 
 ```bash
-cp -r skills/git/file-ticket .clio-coder/skills/   # Clio Coder
-cp -r skills/git/file-ticket .claude/skills/       # Claude Code
+cp -r library/skills/git/file-ticket .clio-coder/skills/   # Clio Coder
+cp -r library/skills/git/file-ticket .claude/skills/       # Claude Code
 ```
 
 The other pipeline skills are model-invoked from the marketplace catalog the

package/docs/process/documentation-coverage.md

@@ -12,7 +12,7 @@ treated as current operator guidance.
 ## Headline
 
 - Markdown pages audited: **51**.
-- Dedicated HTML blueprints now present: **51**.
+- Dedicated HTML blueprints present after that audit: **51**.
 - Pages without a blueprint: **0**. Every Markdown page has one visual
   counterpart, so there are no exception reasons to record.
 - Pages with one or more source disagreements at `ff56ea3e`: **42**.
@@ -56,7 +56,7 @@ preserves that audit-time state.
 | `guide/exit-codes-and-output.md` | `src/cli/**`; `src/entry/**`; CLI smoke tests | `html/exit_codes_blueprint.html` | The JSON event table is described too broadly; full mode can pass additional `clio_coder_*` tool, permission, and plan frames. Core process exit codes are correct. |
 | `guide/extensions-and-sharing.md` | `src/domains/extensions/**`; `src/domains/resources/**`; `src/domains/share/**`; extension and share CLIs | `html/extensions_blueprint.html` | Extensions discover skills, prompts, agents, fleets, and reserved themes, not only prompts and skills. Judge eval arms are not full-auto. Share archives use `clio-coder-share-archive`, `clio-coder.share.v1`, and `clioCoderVersion`; old names are compatibility inputs. The exported settings fragment contains current v2 leaves rather than the documented old scope. |
 | `process/fleet-demo-runbook.md` | `src/domains/dispatch/**`; `src/domains/scheduling/**`; `src/cli/doctor.ts` | No; parity gap. | Current receipts use integrity v20, not v16, and older versions are retired rather than universally failing verification. |
-| `guide/fleet-dispatch.md` | `src/domains/dispatch/**`; `src/domains/scheduling/**`; dispatch tools | `html/fleet_dispatch_blueprint.html` | Current receipts use v20, not v19. Older receipts are retired and never read as evidence. Tool expansion provenance uses `clio-coder.tool.expand`, not `clio.tool.expand`. Agent-ledger citations point into the former dispatch monolith rather than `dispatch-runner.ts`. |
+| `guide/fleet-dispatch.md` | `src/domains/dispatch/**`; `src/domains/scheduling/**`; dispatch tools | `html/fleet_dispatch_blueprint.html` | Current receipts use v20, not v19. Older receipts are retired and never read as evidence. Output styles use `clio-coder.output.cycle`; worker previews follow the same preset regardless of origin. Agent-ledger citations point into the former dispatch monolith rather than `dispatch-runner.ts`. |
 | `process/git-commit-provenance.md` | `src/core/commit-attribution.ts`; `src/core/git-commit-attribution.ts`; `src/core/defaults.ts`; dispatch attribution tests | No; parity gap. | Canonical configuration is `integrations.git.commitAttribution`; `attribution.gitCommits` is migration-only. Commit trailers recognize and emit `receipt-v20`, not v19. |
 | `guide/glossary.md` | Owning types in `src/domains/dispatch/**`, `src/domains/session/**`, `src/domains/context/**`, and `src/tools/**` | `html/glossary_blueprint.html` | Receipt integrity is v20. Dispatch run and session IDs are 12-character random base36 identifiers, while session turn and entry IDs use UUIDv7. Route candidates contain more identity and policy fields than the four-field definition. Council is a current topology. `internal` is a dispatch request origin, not a worker run origin. Context ledger buckets are incomplete. |
 | `guide/installation-and-lifecycle.md` | `src/cli/upgrade.ts`; `src/cli/doctor.ts`; `src/cli/reset.ts`; `src/cli/uninstall.ts`; `src/domains/lifecycle/**`; `src/core/xdg.ts` | `html/lifecycle_blueprint.html` | Install metadata omits `repairedAt` and overgeneralizes preexisting-home detection beyond config, data, and state. The upgrade section presents a stale 0.3.x sequence as current and claims one migration, while the current registry has five migrations and 0.4.2 emits a generic notice. |
@@ -98,3 +98,30 @@ The source-alignment pass corrected all findings across the 42 affected
 Markdown pages. The table preserves what the audit found at `ff56ea3e`; it does
 not describe outstanding Markdown debt. Every HTML blueprint now renders the
 complete corrected counterpart and identifies its Markdown source explicitly.
+
+## Clio Coder 0.4.7 documentation refresh
+
+The 0.4.7 pass was a source-alignment pass, not a re-measurement of the 0.4.2
+audit above, whose table stands as the historical record.
+
+Pages carrying new or rewritten sections in this pass: `README.md`,
+`architecture/context-engine.md`, `architecture/library.md`,
+`architecture/model-catalog.md`, `architecture/pi-boundary.md`,
+`architecture/safety-model.md`, `architecture/session-lifecycle.md`,
+`architecture/tui-design.md`, `architecture/worker-context.md`,
+`guide/commands-and-modes.md`, `guide/configuration-reference.md`,
+`guide/extensions-and-sharing.md`, `guide/harness-extensions.md`,
+`guide/interop.md`, `guide/plugins.md`, `guide/resource-library.md`,
+`guide/skills-marketplace.md`, and `process/scientific-validation.md`, each with
+its paired blueprint.
+
+Two standing rules this pass reaffirmed. Every asserted behavior is anchored to
+the function or contract that implements it, named inline, rather than inferred
+from a UI label or a neighbouring paragraph. And a value that appears only in a
+test fixture is not a product default: the compiled defaults in
+`src/core/defaults.ts` are the authority for what ships unset.
+
+Per-run verification evidence for the refresh lives with the maintenance records
+for that sprint, not in this page. This page tracks documentation coverage, and
+run logs age out of usefulness faster than the docs they checked.
+

package/docs/process/documentation-guide.md

@@ -46,7 +46,8 @@ Classify claims clearly:
 | [configuration-reference.md](../guide/configuration-reference.md) | `src/core/defaults.ts`, `src/cli/**`, `src/tools/**`, `src/domains/agents/recipe-schema.ts`, `src/domains/providers/models/local-models/**` | Audited inventory of every settings key, environment variable, CLI flag, project-file key, frontmatter key, tool argument, and model tag with defaults and precedence. |
 | [safety-model.md](../architecture/safety-model.md) | `src/domains/safety/**`, `src/tools/registry.ts`, `src/tools/policy.ts`, `src/tools/verify/**`, `src/entry/orchestrator.ts`, `src/domains/dispatch/write-boundary.ts` | Operating posture, `resolveEffectiveAutonomy` / `resolveBaselineAutonomy`, detect-and-rollback write boundaries, approval axes, damage control, typed validation. |
 | [prompt-envelope-and-tools.md](../architecture/prompt-envelope-and-tools.md) | `src/domains/prompts/compiler.ts`, `src/interactive/chat-loop.ts`, `src/core/tool-names.ts`, `src/tools/registry.ts`, `src/tools/observation.ts`, `src/tools/agent-tools.ts` | Prompt envelope reuse, canonical tool delivery via single `agent-tools.ts` adapter, seven-plane tool surface, observation envelope, strict `ToolName` keying. |
-| [tool-usage.md](../guide/tool-usage.md) | `src/tools/agent-tools.ts`, `src/tools/registry.ts`, `src/tools/observation.ts` | In-depth reference for all 21 canonical tools, including conditional registration, parameters, typical payloads, normalizers, and error examples. |
+| [tool-usage.md](../guide/tool-usage.md) | `src/tools/agent-tools.ts`, `src/tools/registry.ts`, `src/tools/observation.ts` | In-depth reference for all 24 canonical tools, including conditional registration, parameters, typical payloads, normalizers, and error examples. |
+| [panes-and-files.md](../guide/panes-and-files.md) | `src/interactive/panes-runtime.ts`, `src/interactive/yazi-bridge.ts`, `src/domains/mux/operations.ts`, `src/domains/mux/yazi/theme.ts`, `src/cli/panes.ts` | Operator path to panes and the files pane: install, settings, doctor rows, `/files` and `Alt+E`, presets, what `/quit` closes, theme boundary, troubleshooting. |
 | [provider-adapter-cookbook.md](../architecture/provider-adapter-cookbook.md) | `src/domains/providers/registry.ts`, `src/domains/providers/types/runtime-descriptor.ts` | RuntimeDescriptor, probe(), probeReasoning(), synthesizeModel(), thinking mechanisms. |
 | [pi-boundary.md](../architecture/pi-boundary.md) | `src/engine/**`, `src/tools/truncate.ts`, `tests/boundaries/check-boundaries.ts` | Which Pi SDK capabilities Clio delegates to, which Clio-specific adapters remain, and the boundary tests that keep the split explicit. |
 | [alcf-provider.md](../architecture/alcf-provider.md) | `src/domains/providers/runtimes/cloud/alcf.ts`, `src/engine/alcf-oauth.ts` | Globus PKCE OAuth, openAuthStorage(), Sophia vLLM, Metis API, chatTemplateKwargsUnsupported. |
@@ -55,6 +56,7 @@ Classify claims clearly:
 | [fleet-dispatch.md](../guide/fleet-dispatch.md) | `src/domains/dispatch/**` | Multi-node SSH dispatch: process-safe admission, capacity leases, fleet contracts v1 through v5, v4 write boundaries, v5 plan and gate steps, bounded check/repair loops (`loop_bound_exhausted`), deterministic code steps, attestation, and receipts v20. |
 | [capacity-and-scheduling.md](../architecture/capacity-and-scheduling.md) | `src/domains/scheduling/**`, `src/domains/dispatch/capacity-lease.ts`, `src/domains/dispatch/reservation-store.ts` | Multi-process capacity leases (`dispatch-admission.json`), heartbeat TTLs, cross-process transaction locks (`dispatch-admission.json.lock`), and cluster drain controls. |
 | [worker-dispatch-mechanics.md](../architecture/worker-dispatch-mechanics.md) | `src/worker/**` | NDJSON parent-child socket protocols, control/bulk lane demuxing, watchdog timers, worker attestation (13 protocol fields), permission parking, exit codes. |
+| [worker-context.md](../architecture/worker-context.md) | `src/worker/spec-contract.ts`, `src/domains/dispatch/**`, `src/worker/**` | Worker context inheritance: isolated, fork, and splice context modes for native workers, historical message selection, and token limits. |
 | [fleet-demo-runbook.md](fleet-demo-runbook.md) | `src/domains/dispatch/**` | Multi-node fleet demo: SSH setup, C++ build/repair workflow, reviewer gates, and receipt verification v20. |
 | [session-lifecycle.md](../architecture/session-lifecycle.md) | `src/engine/session.ts`, `src/domains/session/**` | Session lifecycle, on-disk ledger format v4 (`current.jsonl`), tree branching (`tree.json`), active-path lineage selection, `/fork`, `/resume`, checkpoints, and write-ahead protected-artifact journal. |
 | [acp.md](../architecture/acp.md) | `src/engine/acp/**`, `src/cli/acp.ts` | Agent Client Protocol (ACP) server over stdio, tool mediation, non-stall permission handling, timeout bounds, and error taxonomy. |
@@ -65,19 +67,25 @@ Classify claims clearly:
 | [documentation-coverage.md](documentation-coverage.md) | `src/**` | Complete source-to-documentation mapping matrix and subsystem coverage status. |
 | [tui-design.md](../architecture/tui-design.md) | `src/interactive/theme/tokens.ts`, `src/interactive/theme/glyphs.ts` | TUI color system, glyph vocabulary (`contextReserve`), structural layouts, state choreography, code ink. |
 | [installation-and-lifecycle.md](../guide/installation-and-lifecycle.md) | `src/cli/paths.ts`, `src/cli/doctor.ts`, `src/cli/uninstall.ts`, `src/cli/removal.ts` | Installation, upgrade, reset, uninstallation, launcher ownership and what `--remove-binary` will and will not remove, partial-failure behavior, configuration folders (`credentials.yaml` `0o600`), and permissions. |
-| [release-cut-checklist.md](../history/release-cut-checklist.md) | `scripts/check-release.mjs`, `tests/smoke/installed-package.test.ts`, `.github/workflows/`, `package.json` | Historical v0.4.1 release procedure retained as evidence; future releases must draft and verify their own checklist. |
-| [development-pipeline.md](development-pipeline.md) | `skills/git/**`, `.github/**`, `scripts/check-release.mjs`, `package.json` | Issue-to-PR development lifecycle, validation, release inheritance, and the human merge boundary. |
+| [release-cut-checklist.md](release-cut-checklist.md) | `scripts/check-release.mjs`, `tests/smoke/installed-package.test.ts`, `.github/workflows/`, `package.json` | Standard release procedure: local candidate preparation, release gate verification, fast-forward landing on main, annotated tag publication, and npm publish. |
+| [release-cut-checklist.md (v0.4.1)](../history/release-cut-checklist.md) | `scripts/check-release.mjs`, `tests/smoke/installed-package.test.ts`, `.github/workflows/`, `package.json` | Historical v0.4.1 release procedure retained as evidence; future releases must draft and verify their own checklist. |
+| [development-pipeline.md](development-pipeline.md) | `library/skills/git/**`, `.github/**`, `scripts/check-release.mjs`, `package.json` | Issue-to-PR development lifecycle, validation, release inheritance, and the human merge boundary. |
 | [git-commit-provenance.md](git-commit-provenance.md) | `src/core/commit-attribution.ts`, `src/core/git-commit-attribution.ts`, `src/domains/dispatch/fleet-commit-attribution.ts` | Evidence-aware commit roles, trailers, managed hook chaining, and receipt v20 attribution. |
 | [observability.md](../architecture/observability.md) | `src/domains/observability/**`, `src/interactive/view/**`, `src/domains/dispatch/**`, `src/core/bus-events.ts` | `/view` artifact browsing, receipt verification, worker diagnostics, event routing, and cost snapshots. |
 | [performance-methodology.md](performance-methodology.md) | `src/interactive/render-trace.ts`, `src/interactive/**`, `tests/contracts/rendering-invariants.test.ts`, `tests/smoke/real-binary-boot.test.ts` | Reproducible terminal and model-path performance endpoints, trace interpretation, measurement controls, and reporting rules. |
 | [evidence-and-memory.md](../architecture/evidence-and-memory.md) | `src/domains/evidence/**`, `src/domains/memory/**`, `src/cli/evidence.ts`, `src/cli/memory.ts` | Evidence corpus layout, findings, memory lifecycle and prompt injection. |
 | [proactive-memory.md](../guide/proactive-memory.md) | `src/domains/memory/**` | Proactive task memory architecture, session task bank, intervention rules, and handoff carrying. |
-| [trace-store.md](../architecture/trace-store.md) | `src/cli/trace.ts`, `src/domains/observability/trace-store.ts` | WAL SQLite trace mirror database schema, rowid cursor queries, rebuildability, and eight `clio-coder trace` subcommands: `runs`, `phases`, `tail`, `procs`, `inspect`, `prune`, read-only `sql`, and `ui`. |
+| [trace-store.md](../architecture/trace-store.md) | `src/cli/trace.ts`, `src/domains/observability/trace-store.ts` | WAL SQLite trace mirror database schema, rowid cursor queries, rebuildability, and nine `clio-coder trace` subcommands: `runs`, `phases`, `tail`, `procs`, `code-steps`, `inspect`, `prune`, read-only `sql`, and `ui`. |
 | [eval-runner.md](eval-runner.md) | `src/domains/eval/**`, `src/cli/eval.ts` | Local YAML eval tasks, dual token accountings (`tokens.*` wire vs `receiptUsage.*` journal), fail-closed null totals, EvalArtifactV4 format, `verify.measure` task outcome recording. |
 | [evals-internal.md](evals-internal.md) | `src/domains/eval/**`, `evals/**` | Private suite handling, measurement design, and the boundary between shipped reference inputs and external campaigns. |
 | [extensions-and-sharing.md](../guide/extensions-and-sharing.md) | `src/domains/extensions/**`, `src/domains/resources/**`, `src/domains/share/**`, `src/cli/extensions.ts`, `src/cli/share.ts` | Prompt, skill, agent, fleet, and reserved theme resources; extension manifests; portable share archives. |
+| [library.md](../architecture/library.md) | `src/domains/plugins/**`, `src/domains/resources/library.ts`, `src/cli/library.ts` | Package kinds, catalog resolution, integrity, scope selection, and trust. |
 | [resource-library.md](../guide/resource-library.md) | `src/domains/resources/library.ts`, `src/cli/library.ts` | Catalog schemas, private and remote source policy, checksum pins, resource installation, and update checks. |
-| [skills-marketplace.md](../guide/skills-marketplace.md) | `src/interactive/overlays/skills-hub.ts`, `src/domains/resources/skills/marketplace.ts` | Skills Hub marketplace discovery through the install resolver, empty state, install actions, publishing flow. |
+| [skills-marketplace.md](../guide/skills-marketplace.md) | `src/interactive/overlays/library.ts`, `src/interactive/overlays/library-tabs.ts`, `src/domains/resources/skills/marketplace.ts` | Skills marketplace discovery through library overlays, catalog inspection, install actions, publishing flow. |
+| [plugins.md](../guide/plugins.md) | `src/domains/plugins/**`, `src/domains/resources/library.ts`, `src/cli/library.ts` | Portable domain bundles, library installation, enable/disable states, drift detection, pins, and package lifecycle. |
+| [authoring-plugins.md](../guide/authoring-plugins.md) | `library/**`, `src/domains/plugins/**`, `src/domains/resources/library-validation.ts` | Plugin and package structure, root plugin.json manifests, resource mapping, validation, and authoring guidelines. |
+| [harness-extensions.md](../guide/harness-extensions.md) | `src/domains/extensions/**`, `src/domains/plugins/**`, `src/interactive/**` | Harness extension lifecycle, command handlers, dynamic reload, and interaction with the Clio execution environment. |
+| [interop.md](../guide/interop.md) | `src/cli/interop.ts`, `src/domains/interop/**`, `src/interactive/overlays/interop.ts` | External coding agent interoperability: host discovery, resource inspection, safe adoption of prompts and skills into the library. |
 | [model-catalog.md](../architecture/model-catalog.md) | `src/domains/providers/catalog.ts`, `src/domains/providers/models/**`, `src/domains/providers/probe/**`, `src/domains/providers/model-capabilities.ts` | Model catalog, live probes (`--offline` toggle), exact-id selector `probeCapabilitiesForModel`, field-note promotion. |
 | [middleware-and-components.md](../architecture/middleware-and-components.md) | `src/domains/components/**`, `src/domains/middleware/**`, `src/cli/components.ts` | Active component snapshots, phase-aware middleware hook budgets (`DEFAULT_MIDDLEWARE_HOOK_BUDGETS_MS`). |
 | [scientific-validation.md](scientific-validation.md) | `src/domains/safety/rigor.ts`, `src/domains/safety/finish-contract.ts` | Advisory validation-contract patterns for scientific artifacts and HPC assumptions. |
@@ -133,8 +141,8 @@ Clio Coder maintains two complementary documentation formats:
 
 Blueprint coverage is explicit rather than inferred from document style. The
 page-level audit lives in
-[`documentation-coverage.md`](documentation-coverage.md). All 51 Markdown pages
-have a dedicated blueprint. `docs/html/index.html` groups those counterparts by
+[`documentation-coverage.md`](documentation-coverage.md). Every canonical Markdown page
+has a dedicated blueprint. Recheck the complete inventory during each release cut. `docs/html/index.html` groups those counterparts by
 the same Guide, Architecture, Process, and History tree, while a source meta tag
 provides the one-to-one machine-readable mapping. Every mapping must remain
 unique, complete, and free of orphaned Markdown or HTML pages.

package/docs/process/eval-runner.md

@@ -14,6 +14,9 @@ Source of truth: [src/domains/eval/](../../src/domains/eval/) and [src/cli/eval.
 The CLI commands under `clio-coder eval` support running, validating, reporting, comparing, and gating evaluation suites.
 
 ```bash
+clio-coder eval validate --package <path|kind:name> [--eval <name>] [--user|--project]
+clio-coder eval run --package <path|kind:name> [--eval <name>] [--user|--project] [--out <path>]
+clio-coder eval skill <name|path> [--scenario <id>] [--json]
 clio-coder eval validate --suite <suite.yaml>
 clio-coder eval run --suite <suite.yaml> [--trials <n>] [--target <id>] [--model <id>] [--out <path>] [--clio-coder-entry <path>]
 clio-coder eval run --task-file <tasks.yaml> [--repeat <n>] [--out <path>] [--clio-coder-entry <path>]
@@ -24,8 +27,9 @@ clio-coder eval inventory --json
 ```
 
 ### Command Roles
-* **`validate`**: Validates the structure and constraints of a Suite v2 YAML file without executing it.
-* **`run`**: Runs a Suite v2 (via `--suite`) or a compatibility v1 task file (via `--task-file`). Outputs a text summary and writes an eval artifact under `<dataDir>/evals/` and evidence under `<dataDir>/evidence/eval-<evalId>/`.
+* **`validate`**: Validates the structure and constraints of a Suite v2 YAML file (via `--suite`) or package evaluations (via `--package <path|kind:name> [--eval <name>]`) without executing them.
+* **`run`**: Runs a Suite v2 (via `--suite`), a compatibility v1 task file (via `--task-file`), or a packaged evaluation (via `--package <path|kind:name> [--eval <name>]`). Outputs a text summary and writes an eval artifact under `<dataDir>/evals/` and evidence under `<dataDir>/evidence/eval-<evalId>/`.
+* **`skill`**: Evaluates an individual skill directory or catalog entry against its baseline scenarios declared in `evals.md`.
 * **`report`**: Formats and prints a report from a saved `evalId`. Supports multiple `--format` outputs:
   * `text` (default): Human-readable stdout summary.
   * `json`: Raw JSON structure of the artifact.
@@ -41,7 +45,8 @@ Exit codes:
 | Command | Success | Failure |
 | --- | --- | --- |
 | `eval validate` | `0` when validation passes | `2` for validation issues |
-| `eval run` | `0` when all task repetitions pass | `1` when any task fails, `2` for invalid configs |
+| `eval run` | `0` when all task repetitions pass | `1` when any task/gate fails (including package evals), `2` for invalid configs or load errors |
+| `eval skill` | `0` when all scenarios pass | `1` for failures/regressions, `3` for unmeasured harness state or evidence errors, `2` for invalid arguments |
 | `eval report` | `0` when artifact loads | `1` if artifact cannot be read, `2` for invalid ID |
 | `eval compare` | `0` when both artifacts compare and the behavioral hard gate passes | `1` for a hard regression or unreadable artifact, `2` for invalid ID |
 | `eval gate` | `0` when correctness, safety, and hard threshold assertions pass | `1` for hard failures, unreadable inputs, and malformed threshold files; `2` for an invalid eval ID or usage error |

package/docs/process/performance-methodology.md

@@ -62,7 +62,7 @@ exit. This keeps diagnostic output from corrupting the temporary shell without
 changing the measured endpoints.
 
 ```bash
-CLIO_CODER_RENDER_TRACE=/tmp/clio-render.jsonl \
+CLIO_CODER_RENDER_TRACE=/tmp/clio-coder-render.jsonl \
 CLIO_CODER_TRACE_BOOT=1 \
 CLIO_CODER_INTERACTIVE=1 \
 node dist/cli/index.js

package/docs/process/release-cut-checklist.md

@@ -13,18 +13,21 @@ canonical remote state or publishes immutable packages.
 ## Part 1: Candidate Preparation on a Local Compact Branch
 
 Maintainers prepare release candidates on a local-only compact branch named after
-the version without punctuation, such as `v044` for version `0.4.4`. Dotted branch
-names like `v0.4.4` are forbidden because dotted names belong exclusively to immutable
+the version without punctuation, such as `v046` for version `0.4.6`. Dotted branch
+names like `v0.4.6` are forbidden because dotted names belong exclusively to immutable
 tags. The canonical repository hosts only `main`, and no release candidate branch is
 ever pushed to canonical origin.
 
 1. Ensure the working tree is clean and updated from canonical origin:
 
    ```bash
-   git checkout -b v044 origin/main
+   git checkout -b v046 origin/main
    ```
 
-2. Update `version` in `package.json` to the release version.
+2. Update `version` in `package.json` and `assets/acp-registry/agent.json` to the
+   release version. Update the README's source-install tag and remove any
+   development-only notices. Keep historical release records, protocol schema
+   versions, dependency versions, and migration fixtures unchanged.
 
 3. Retitle the active changelog section in `CHANGELOG.md` from `## Unreleased` to
    `## <version> - YYYY-MM-DD`. The release gate in `scripts/check-release.mjs` requires
@@ -75,6 +78,10 @@ Run deterministic local checks on the candidate commit before requesting authori
    npm pack --dry-run
    ```
 
+   Confirm the complete `library/` tree and `.claude-plugin/marketplace.json`
+   accompany `dist/`, `src/`, and the documented runtime resources. The repository's
+   `.agents/skills/` symlinks are clone conveniences and are not tarball contents.
+
 5. Validate an installed tarball in a clean temporary directory:
 
    Create a temporary directory, pack the tarball, install it via npm, and verify
@@ -112,7 +119,7 @@ an immutable package. Do not execute any of them without explicit maintainer aut
 
    ```bash
    git checkout main
-   git merge --ff-only v044
+   git merge --ff-only v046
    ```
 
 4. Verify that local `main` matches the reviewed candidate SHA exactly.
@@ -150,6 +157,15 @@ an immutable package. Do not execute any of them without explicit maintainer aut
 
 5. Inspect the GitHub Actions workflow run and confirm the GitHub release is published.
 
+6. Reconcile the release milestone against the tagged commits and each ticket's
+   acceptance evidence. `Fixes #123` or `Resolves #123` in a commit closes that
+   ticket when the commit reaches default-branch `main`; a bare `#123`, changelog
+   mention, tag, or GitHub release does not. Verify the resulting issue state.
+   Explicitly close completed tickets missed by automatic closure and retain
+   their implementing commit and validation references. Carry incomplete work
+   forward with its remaining criteria, then close the reconciled milestone.
+   Never infer completion from a release-note mention alone.
+
 ## Part 6: Package Publication to npm
 
 Publishing to npm is a manual maintainer step performed from the tagged commit.
@@ -195,7 +211,7 @@ Publishing to npm is a manual maintainer step performed from the tagged commit.
 3. Remove the local compact candidate branch:
 
    ```bash
-   git branch -d v044
+   git branch -d v046
    ```
 
    The canonical repository remains in its steady state containing only `main` and immutable tags.