@iowarp/clio-coder 0.4.1 → 0.4.3

package/docs/{proactive-memory.md → guide/proactive-memory.md}

@@ -1,6 +1,7 @@
 # Proactive task memory
 
-> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Proactive task memory visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/proactive_memory_blueprint.html).
 
 Clio's proactive task memory protects long-running work from behavioral state
 decay: a requirement, environment fact, failed attempt, or diagnosis can still
@@ -10,10 +11,10 @@ Long-Horizon Agents* (2026), adapted to Clio's visible middleware and local-mode
 routing.
 
 The rules-only tier is enabled by default and makes no model calls. An LLM memory
-tier is opt-in through the independent `background` route. The action agent's
-system prompt and tool surface do not change, and disabling
-`memory.intervention.enabled` removes observation, bank writes, model resolution,
-reminders, handoff offers, and handoff seeding.
+tier is opt-in through the independent `context.memory.target` and
+`context.memory.model` route. The action agent's system prompt and tool surface
+do not change, and disabling `context.memory.enabled` removes observation, bank
+writes, model resolution, reminders, handoff offers, and handoff seeding.
 
 ## Architecture
 
@@ -116,11 +117,11 @@ than discarding the writes that came with it. A timeout, provider failure,
 malformed response, or telemetry failure is silent and never blocks a tool.
 
 ### Intervention Defaults & Cadence Knobs
-- `memory.intervention.enabled` (default `true`): Enables observation, task bank writes, and reminder injection.
-- `memory.intervention.everyNTools` (default `10`): Minimum completed-tool interval between background interventions.
-- `memory.intervention.windowSteps` (default `8`): Completed tool-trajectory window analyzed during background evaluation.
-- `memory.intervention.maxTokens` (default `400`): Bounds the rendered memory-bank and reminder context budget; the policy model output cap is a separate fixed `4,000`-token contract in `task-memory-policy.ts`, sized so that a model which reasons anyway still reaches its envelope.
-- `memory.intervention.timeoutMs` (default `30000`): Wall-clock limit for one background memory-policy request. The step is detached, so this deadline never delays a turn, but it does hold a request slot on a real inference endpoint that your own turns and your dispatched workers queue against. The default is what a turn boundary can wait for rather than what a long-tailed route eventually answers in: on the reference route below, 23 of 60 steps ran past 30 seconds and 531 of the measured 1,666 seconds were spent beyond that mark. Raise it only if you have measured that your route's slow steps are the ones producing reminders, and read the trade in "Cost and the default decision" first.
+- `context.memory.enabled` (default `true`): Enables observation, task bank writes, and reminder injection.
+- `context.memory.cadenceToolCalls` (default `10`): Minimum completed-tool interval between background interventions.
+- `context.memory.trajectorySteps` (default `8`): Completed tool-trajectory window analyzed during background evaluation.
+- `context.memory.maxOutputTokens` (default `2000`): Bounds the rendered memory-bank context and the ordinary policy-model completion. An always-on-thinking model receives additional reasoning headroom, at least `4,000` tokens when its model cap permits, so it can still reach the strict envelope.
+- `context.memory.timeoutMs` (default `60000`): Wall-clock limit for one background memory-policy step, including its one permitted chat fallback attempt. The step is detached, so this deadline never delays a turn, but it does hold a request slot on a real inference endpoint that your own turns and dispatched workers queue against. Raise it only after inspecting the timeout and hit-rate evidence for the selected route.
 
 ## Trigger semantics
 
@@ -130,7 +131,7 @@ it runs detached from it.
 
 | Trigger | Behavior |
 | --- | --- |
-| Interval | After `memory.intervention.everyNTools` completed tools since the last prompted step; default 10. This is the nondeterministic/citation-gated path. |
+| Interval | After `context.memory.cadenceToolCalls` completed tools since the last prompted step; default 10. This is the nondeterministic/citation-gated path. |
 | Tool-error streak | Two consecutive error outcomes. A successful tool resets the streak. |
 | Loop signal | Reuses the orchestrator loop guard's verdict; it does not infer a second competing loop detector. |
 | Repeated failure | The rules tier records failed operation fingerprints and annotates the failing tool result once the same failure appears twice in the bounded trajectory. |
@@ -163,9 +164,9 @@ records one telemetry row, not two.
 
 The agent loop does not become idle until every `agent_end` listener settles, so a
 memory step awaited at that boundary would add its full latency to the visible
-end of every triggered turn. Measured on the reference route below, step latency
-has a median of 18.6 seconds and ranges up to 220.8 seconds. This makes an awaited
-step intolerable as an end-of-turn pause.
+end of every triggered turn. Historical operator measurements below put a
+typical step in the tens of seconds. This makes an awaited step intolerable as
+an end-of-turn pause.
 
 The prompted step is therefore detached. `evaluateAsync` starts it and returns
 immediately; the turn ends on schedule. When the step resolves, its reminder is
@@ -217,8 +218,8 @@ hit rate.
 
 ### The measurement
 
-From one operator's `steps.jsonl`, 274 rows spanning 2026-08-14 to 2026-08-29 on
-a small local background route:
+From one operator's dated `steps.jsonl` export, 274 rows spanning 2026-08-14 to
+2026-08-29 on a small local background route:
 
 | Figure | Value |
 | --- | --- |
@@ -240,75 +241,88 @@ injections cost nothing.
 The default does not change, and it is a deliberate default rather than an
 unexamined one:
 
-- `memory.intervention.enabled` stays `true`. It runs the rules tier, which makes
+- `context.memory.enabled` stays `true`. It runs the rules tier, which makes
   no model calls, spends no tokens, and produced 4 of the 10 injections.
-- The LLM tier stays opt-in through `background.target` and `background.model`,
+- The LLM tier stays opt-in through `context.memory.target` and `context.memory.model`,
   which is already the case: an unset background role never resolves a client.
   A 10 percent hit rate at 22,868 tokens per injection does not earn a default-on
   position, and it is not so poor that it earns removal from an operator who has
   measured their own route and wants it.
-- The step deadline drops from 180 s to 30 s. This is the one behavioral change,
-  and it is a genuine trade: at 30 s, two of the six observed injections, at
-  53.6 s and 57.7 s, would have been cut, while 531 s of the 1,666 s spent would
-  not have been spent at all. The deadline is the bound on what one optional call
-  may hold a shared local server for, not a prediction of when a route answers.
-- A step that would run on the endpoint the chat target is streaming against is
-  skipped with reason `endpoint_busy`, and the skip is recorded. On a single-slot
-  llama.cpp router the alternative is queueing behind the operator's own decoding
-  or evicting the resident model, and neither is a cost an optional call may
-  impose.
-
-### What a background target costs on a shared local server
-
-If `background.target` names the same server as `orchestrator.target`, that
-server's slots are shared. On a llama.cpp router started with `--parallel 1`
-there is exactly one, and the memory step and the operator's turn contend for it.
-
-The consequence is worth stating plainly: a shared endpoint suppresses the model
-tier rather than merely delaying it. A step is started from the `turn_end` hook,
-which fires inside the streaming run at `agent_end`
-(`src/interactive/turn-runtime.ts`), while the chat loop still holds its
-foreground registration on that endpoint; the loop releases the hold afterwards,
-in the `finally` around the run (`src/interactive/chat-loop.ts`). Every boundary
-therefore finds the endpoint busy and records `dropped`/`endpoint_busy`. That is
-the intended trade: an optional call may not take the one slot the operator's own
-turn is using, and it may not make the server swap the resident model out. The
-`/memory` step list and `steps.jsonl` say so on every boundary, so the tier is
-visibly declining rather than quietly idle.
-
-The second mechanism is an `expected cold` stamp, for the case where a step did
-run on the chat endpoint. Its prompt is a trajectory rather than the chat prefix,
-so the next turn's prefill is expected to be cold; `/context` names
-`background_memory` as the reason instead of reporting an unexplained cold
-prefix.
-
-Pointing the background role at a second machine avoids both effects and is the
-arrangement the tier is designed for.
+- `context.memory.timeoutMs` is `60000` in the current defaults. The dated study
+  considered a 30-second counterfactual: two of six observed injections, at
+  53.6 and 57.7 seconds, would have been cut, while 531 of 1,666 model seconds
+  would not have been spent. The current 60-second deadline is the source-backed
+  bound on what one optional call may hold a shared local server for, not a
+  prediction of when a route answers.
+- A step whose known endpoint occupancy exhausts the resolved request capacity is
+  skipped with reason `endpoint_busy`. The same gateway URL alone does not imply
+  a single request slot or a single physical model server.
+
+### Dedicated routing, chat fallback and endpoint capacity
+
+Clio prefers the explicitly configured memory target and model. If that route is
+known unavailable (missing target/runtime, down target, absent model in a known
+catalog, or a model reported unloaded/loading), Clio selects the active chat
+route for that step. A runtime client error on the dedicated route permits one
+chat attempt within the original remaining deadline. It does not retry after a
+timeout, cancellation, session/branch switch, malformed envelope, or a model's
+explicit silence. The fallback never falls back again. Both routes unavailable
+produce a visible `client_error` outcome. An unset memory role remains rules-only;
+chat fallback does not enable model-based memory by default.
+
+A runtime notice names the selected chat fallback and its reason. Routing stays
+session-local and does not edit saved settings. Each attempted call records its
+own known usage under its actual target/model and emits its own telemetry outcome;
+failed dedicated usage is retained alongside fallback usage. The final policy
+result describes the final attempt, without merging different provider identities.
+A generation change discards late content while preserving the original usage owner.
+
+Capacity follows the same existing evidence as dispatch: explicit target
+`maxConcurrentRequests`, current discovery, a valid discovery prior, then the
+conservative one-slot default for a local-native runtime. Known occupancy includes
+this process's foreground requests, active dispatch leases and held reservation
+waves. A two-slot endpoint with one foreground request can admit memory; a full
+one-slot endpoint skips it. Known dedicated saturation does not itself initiate
+chat fallback. Larger declared capacities work without a new constant.
+
+LiteLLM is a gateway protocol, so Clio does not invent a local one-slot limit for
+its URL. Distinct model routes such as dynamo, mini and zbook can share that URL;
+the gateway owns their physical routing and backend residency. An explicit or
+observed endpoint-wide bound still applies when present. Clio's process-local
+foreground holds and observed dispatch state are not a global scheduler for every
+client using the gateway. Slot holds are released on success, failure and abort.
+
+The existing `background_memory` expected-cold stamp remains keyed by endpoint
+URL. It records a possible shared-endpoint cache disturbance, including after a
+failed request, rather than proving that a different model behind the gateway
+actually evicted the chat prefix.
 
 ## Choosing a background model
 
 Memory reads a trajectory and writes a fixed envelope. It does not plan, and it
 does not need to be clever. A small non-reasoning model is the right choice, and
-Clio always requests the background route with thinking off regardless of
-`background.thinkingLevel`.
+Clio always requests the memory route with thinking off. Version 2 therefore
+has no configurable memory thinking-level key.
 
-That request reaches the wire wherever the runtime carries a thinking control:
+The off request depends on the resolved runtime and model metadata:
 llama.cpp reads `chat_template_kwargs.enable_thinking`, and LM Studio reads
-`reasoning_effort`, where `none` is the off value.
+`reasoning_effort`, with the off value selected by the model family. A gateway
+needs a recognized, unanimous upstream runtime declaration; unknown metadata
+does not establish a dialect. Requesting off does not prove server compliance.
 
 A model that reasons anyway still works. Some genuinely cannot be silenced, and
 the catalog records those as always-on so the level reads `forced` rather than
-`off`; the shipped background model `qwopus3.5-9b-v3` is one of them. Reasoning
+`off`; the shipped model catalog classifies `qwopus3.5-9b-v3` that way. No model
+is selected for background memory by default. Reasoning
 blocks are discarded and only the envelope is kept, and the output budget is
 sized to let a reasoning preamble run its course first. The cost is latency,
 which the detached step absorbs.
 
-One configuration is refused rather than degraded. If the background role names
-the same target and model as the orchestrator, and that model reasons, the LLM
-memory tier stays off and memory runs on its free deterministic tier. A single
-reasoning model already driving chat, workers, and shadow agents cannot also
-deliberate over memory steps without contending with the work the operator
-actually asked for.
+The active chat model may also serve memory, including a reasoning model, when
+request capacity permits. Memory still requests thinking off and uses its own
+bounded envelope and output budget. A dedicated small model is preferred for
+latency and resource use; sharing a model is a capacity decision rather than an
+unconditional refusal.
 
 This is a mix-and-match plane, not a local-only one. The background role resolves
 through the same target machinery as every other role, so the useful shapes are:
@@ -328,52 +342,59 @@ KV caches, and parallel slots must all fit the target's available memory.
 The shipped defaults are:
 
 ```yaml
-background:
-  target: null
-  model: null
-  thinkingLevel: off
-
-memory:
-  intervention:
+context:
+  memory:
     enabled: true
-    everyNTools: 10
-    windowSteps: 8
-    maxTokens: 400
-    timeoutMs: 30000
+    target: null
+    model: null
+    cadenceToolCalls: 10
+    trajectorySteps: 8
+    maxOutputTokens: 2000
+    timeoutMs: 60000
 ```
 
-With `background.target` and `background.model` unset, Clio stays in the
+With `context.memory.target` and `context.memory.model` unset, Clio stays in the
 zero-cost rules tier. `/memory` shows the current tier, last decision, approved
 durable lessons, the live bank, and a bounded history of the last twenty memory
 steps with their trigger, decision, write count, cited-entry count, tier, and
 latency. That history is the only place a capture, a gate, or a timeout becomes
 visible, since those outcomes produce no transcript entry by design; only an
 actual injection reaches the transcript. It carries counts and outcomes only,
-never bank or trajectory text. `/settings` exposes every key above; the saved
+never bank or trajectory text. `/settings` exposes controls for every key above;
+its compact row labels retain shorter operator-facing names. The saved
 background-memory target is the Memory target row in Settings → Orchestrator,
 independent of the chat target and the fleet default. A running session owns
 its routing snapshot, while the saved
 selection becomes the default for new sessions.
 
-The reference live configuration is an LM Studio server on the `node-a` node with
-the wire model `example-background-model`:
+An example gateway topology keeps the three backend routes distinct:
+
+| Role | Target | Runtime and endpoint | Model | Capacity |
+| --- | --- | --- | --- | --- |
+| Chat and memory fallback | `dynamo` | LiteLLM at `http://gateway:4000` | `dynamo/qwen3.8-27b` | Gateway-owned unless an explicit or observed endpoint bound is available |
+| Preferred background memory | `zbook` | Same LiteLLM gateway | `zbook/ornith-1.5-35b-a3b` | Same capacity evidence rules |
+| Alternative memory candidate | `mini` | Same LiteLLM gateway | `mini/ornith1.5-35b-moe` | Same capacity evidence rules |
+
+The corresponding role selection is:
 
 ```yaml
-background:
-  target: node-a
-  model: example-background-model
-  thinkingLevel: off
+chat:
+  target: dynamo
+  model: dynamo/qwen3.8-27b
+context:
+  memory:
+    target: zbook
+    model: zbook/ornith-1.5-35b-a3b
 ```
 
-A small model is the intended shape for this role. Across 60 measured steps on
-that route, latency ran 4.4 to 220.8 seconds with a median of 18.6, a 90th
-percentile of 79.9, and a 95th of 131.6. Capability is not the constraint;
-latency is, its spread is wide, and the detached step above is what makes the
-tier usable anyway.
+These are example configured target/model IDs, not built-in routes. Compare a
+slow dedicated model with an alternative using actual step latency, valid bank
+writes and known usage; the active chat route remains the fallback. Do not create
+aliases or change endpoint URLs just to bypass capacity accounting.
 
 The deadline is a bound on what an optional call may hold that server for, not a
-figure sized to capture the tail. The shipped 30000 sits above the median and
-below the tail deliberately, and a step that exceeds it records `timeout` with
+figure sized to capture the tail. The shipped `60000` is a bounded compromise,
+and a step that exceeds it records `timeout` with
 its work discarded. A route whose steps mostly record `timeout` is a
 misconfigured deadline before it is a slow model, so read the ledger before
 raising it: `/memory` shows the hit rate the raise would be buying.
@@ -384,17 +405,19 @@ real target surfaces to verify the route:
 
 ```bash
 clio-coder targets --probe
-clio-coder models --target node-a
+clio-coder models --target mini
+clio-coder models --target dynamo
 clio-coder
 ```
 
-Then inspect `/targets`, `/settings`, and `/memory`. Local co-residency still
+Then inspect `/settings targets`, `/settings`, and `/memory`. Local co-residency still
 matters: the background model, action model, their KV caches, and parallel slots
-must fit the target's available memory. Increase `timeoutMs` for a deliberately
-slow local route; lowering `maxTokens` bounds the visible reminder but does not
-change the background model's strict output grammar.
+must fit the target's available memory. Increase `context.memory.timeoutMs` for
+a deliberately slow local route; lowering `context.memory.maxOutputTokens`
+bounds the visible reminder and ordinary completion budget but does not change
+the background model's strict output grammar.
 
-For an immediate kill switch, set `memory.intervention.enabled` to `false` in
+For an immediate kill switch, set `context.memory.enabled` to `false` in
 `/settings`. Removing the background target instead returns to rules-only
 operation while leaving deterministic protection active.
 
@@ -477,7 +500,7 @@ clear the prior heap bank before the new session can observe it.
 
 ## Telemetry
 
-Each completed memory step appends one content-free record to:
+Each completed memory-policy attempt appends one content-free record to:
 
 ```text
 <stateDir>/memory/steps.jsonl
@@ -500,7 +523,7 @@ folds out of this file.
 `dropped` is the one outcome that ran no step. It has two causes, separated by
 the row's reason: `step_in_flight` means the boundary triggered while an earlier
 step still held the single in-flight slot, and `endpoint_busy` means the step
-would have called the endpoint the chat target was streaming against. Both cost
+found the known endpoint request capacity exhausted. Both cost
 no tokens and no latency, both leave their triggers pending for the next free
 boundary, and neither replaces the operator-visible last decision. Counting
 `dropped` rows against `llm` rows over a session is how a starved cadence becomes
@@ -533,15 +556,16 @@ trial. The report provides:
 - total and baseline-relative added tokens and latency;
 - an `alwaysNoisyRegression` verdict.
 
-The deterministic end-to-end harness contract can be run directly:
-
-```bash
-npm run test:file -- tests/contracts/proactive-memory-eval.test.ts
-```
+The source-level harness remains available to a runner adapter, and the eval
+platform remains active. Its former dedicated contract test was retired, and
+the current test tree has no direct reference to `runProactiveMemoryEval`.
+There is therefore no maintained direct test coverage or standalone
+`npm run test:file` invocation for this harness. Treat a live comparison as an
+explicit measurement campaign.
 
 For a live local comparison, an adapter should route only the `llm` variant
-through the request's target/model (the reference is `node-a` /
-`example-background-model`), keep baseline memory telemetry empty, and run all
+through the request's target/model (the reference memory route is `mini` /
+`ornith1.5-35b-moe`), keep baseline memory telemetry empty, and run all
 nine trials in equivalent isolated workspaces. Do not promote the LLM tier from
 one anecdotal task. The evidence bar is a pass-rate gain from a small number of
 specific, usually cited reminders at acceptable added token and latency cost.

package/docs/{resource-library.md → guide/resource-library.md}

@@ -1,5 +1,8 @@
 # Resource Library
 
+> **Visual blueprint:** The source checkout includes the complete
+> [Resource Library visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/resource_library_blueprint.html).
+
 The resource library extends the existing local skills marketplace catalog to carry agent recipes, prompt templates, and fleet contracts. It does not change the Agent Skills format, discovery roots, trust gating, or existing skill installation sources.
 
 ## Catalog schema
@@ -21,11 +24,11 @@ skills:
 
 ## Private catalog and remote gating
 
-`library.catalog` selects a private catalog and defaults to `<configDir>/library.yaml`. Relative sources in that file resolve beside the catalog. `library.remote` records an optional git remote URL. `library.sync` defaults to false, and no git process is started while it remains false.
+`integrations.library.catalog` selects a private catalog and defaults to `<configDir>/library.yaml`. Relative sources in that file resolve beside the catalog. `integrations.library.remote` records an optional git remote URL. `integrations.library.sync` defaults to false, and no git process is started while it remains false.
 
-The private catalog repository must name its git remote `library`. Clio checks it with `git remote get-url library`. Run `clio-coder library remote confirm <url>` once after reviewing the configured URL. When `library.remote` is unset, confirmation records the URL as both the configured and confirmed remote. A confirmation that differs from an existing `library.remote` refuses with `library_remote_mismatch`. A missing confirmation or a later settings change refuses synchronization and publishing with `library_remote_unconfirmed`.
+The private catalog repository must name its git remote `library`. Clio checks it with `git remote get-url library`. Run `clio-coder library remote confirm <url>` once after reviewing the configured URL. When `integrations.library.remote` is unset, confirmation records the URL as both the configured and confirmed remote. A confirmation that differs from an existing `integrations.library.remote` refuses with `library_remote_mismatch`. A missing confirmation or a later settings change refuses synchronization and publishing with `library_remote_unconfirmed`.
 
-When `library.sync` is false, both `library sync` and `library push` refuse with `library_sync_disabled` before any process starts. When synchronization is enabled, `library sync` runs `git fetch library` followed by `git merge --ff-only FETCH_HEAD`, and `library push` runs `git push library`. Both commands execute git as an argument vector without a shell.
+When `integrations.library.sync` is false, both `library sync` and `library push` refuse with `library_sync_disabled` before any process starts. When synchronization is enabled, `library sync` runs `git fetch library` followed by `git merge --ff-only FETCH_HEAD`, and `library push` runs `git push library`. Both commands execute git as an argument vector without a shell.
 
 ## CLI
 
@@ -43,7 +46,13 @@ clio-coder library remote confirm <url>
 
 ## In the TUI
 
-The Skills Hub carries one tab per kind. `/library <kind>` opens it on that kind's tab and `/library` alone opens it on Skills, which is also where `/skill` opens. Each tab lists the entries this same discovery finds, with the requirements an entry still needs named in the warning token. Installing from a row runs the same plan-then-write pair `library add` runs, behind a confirmation that states every destination and hash and writes nothing when it is cancelled, and an entry with unresolved requirements is refused by name before an install-with-requirements confirmation offers to write them all. `Enter` on an installed row leads where that kind is invoked from: the composer for an agent, a prompt, or a skill, and the `/fleet run` approval preview for a fleet. See [skills-marketplace.md](skills-marketplace.md) for the key table.
+The Skills Hub carries one tab per kind. `/resources library <kind>` opens the
+requested tab, while `/skill` opens Skills. Each tab lists discovered entries
+and any unresolved requirements. Installing from a row uses the same
+plan-then-write path as `clio-coder library add`, behind a confirmation that
+states every destination and hash and writes nothing when cancelled. `Enter`
+on an installed row leads to its invocation surface. See
+[Skills Marketplace](skills-marketplace.md) for the key table.
 
 ## Installation roots and validation
 

package/docs/{skills-marketplace.md → guide/skills-marketplace.md}

@@ -1,10 +1,18 @@
 # Skills Marketplace
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/skills_blueprint.html](html/skills_blueprint.html) (Version: 0.4.0).
+> **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).
 
 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.
 
+## 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:
@@ -45,7 +53,11 @@ Invoking an uninstalled marketplace skill with `/skill <name>` prompts before in
 
 ## Tabs
 
-The hub carries one tab per resource library kind: Skills, Agents, Prompts, and Fleets. `←` and `→` move between them, which is the key vocabulary the Settings Center already uses to move between sections. 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 the hub on Skills. `/library <kind>` opens it on that kind's tab, and `/library` alone opens it on 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.
 
 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.
 
@@ -58,6 +70,16 @@ 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.
 
+## Remote entries and overlays
+
+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. `npm 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 `npm run skills:check` fails when it drifts.
+
+`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.
+
+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.
+
+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.
+
 ## 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 `npm 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.