@iowarp/clio-coder 0.4.9 → 0.5.0

package/docs/guide/proactive-memory.md

@@ -13,6 +13,16 @@ tier is opt-in through the independent `context.memory.target` and
 do not change, and disabling `context.memory.enabled` removes observation, bank
 writes, model resolution, reminders, handoff offers, and handoff seeding.
 
+## Inspect or configure memory
+
+| You want to… | Use |
+| --- | --- |
+| Inspect the bank and recent memory steps | `/memory` |
+| Select a background model or change memory controls | `/settings` → **Context & Memory** |
+| Review recorded cost | `/cost` or `clio-coder usage report` |
+| Look up the default values and routing example | [Operator setup](#operator-setup) |
+| Understand what survives a handoff | [Handoff continuity](#handoff-continuity) |
+
 ## Architecture
 
 ```mermaid
@@ -24,7 +34,7 @@ flowchart LR
   D -->|background configured| L[two-phase local model policy]
   S --> V[visible advisory reminder]
   L --> V
-  V --> U[next user turn and session ledger]
+  V --> U[next tool-batch or prompt boundary and session ledger]
   R -. counts and outcomes only .-> J[bounded state JSONL]
   B -. explicit context-handoff .-> H[redacted handoff snapshot]
 ```
@@ -33,9 +43,10 @@ The task bank is in `src/domains/memory/` and belongs to one live session. It is
 separate from both durable approved lessons and the regenerable repository
 context engine.
 
-- **Private status** is the memory policy's short progress model. It can be
-  inspected with `/memory`, but is never rendered to either model, injected into
-  the action turn, or exported to a handoff.
+- **Private status** is the memory policy's short progress model. Inspect it
+  with `/memory`. It stays out of ordinary reminders, the memory model's bank
+  input, and handoffs. After compaction, Clio can include it in the restored
+  state sent to the action agent.
 - **Knowledge** contains stable task facts such as requirements, paths,
   environment facts, and constraints.
 - **Procedural memory** contains attempts and outcomes such as failed commands,
@@ -43,9 +54,11 @@ context engine.
 
 Knowledge and procedural entries have stable short IDs. A visible reminder is
 one `Memory:` advisory block and records the cited entry IDs' injection counts.
-The existing middleware path places that block in the next submitted user turn
-and persists its attribution in the session ledger; there is no hidden
-`transformContext` injection.
+
+The existing middleware path delivers that block at the first boundary that can
+carry it, which is either a native tool-batch boundary inside the running turn or
+the next accepted prompt, and persists its attribution in the session ledger.
+There is no hidden `transformContext` injection.
 
 ## Paper mapping and Clio constraints
 
@@ -59,6 +72,9 @@ and persists its attribution in the session ledger; there is no hidden
 | Learned intervention calibration | Structural authority gate: spontaneous reminders must cite a bank entry; deterministic triggers may be uncited |
 | Passive and always-on ablations | A/B harness compares baseline, rules, and LLM tiers and flags always-noisy ties as regressions |
 
+<details>
+<summary>The two-line envelope grammar and what the parser tolerates</summary>
+
 Model output uses a strict two-line grammar parsed by `src/domains/memory/task-memory-policy.ts`:
 
 ```text
@@ -113,6 +129,8 @@ reminder; an over-budget reminder is recorded as `gated` and suppressed rather
 than discarding the writes that came with it. A timeout, provider failure,
 malformed response, or telemetry failure is silent and never blocks a tool.
 
+</details>
+
 ### Intervention Defaults & Cadence Knobs
 - `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.
@@ -150,9 +168,13 @@ repeated failure uses exactly one of them:
   reads the advisory on its very next round. This is spent once per operation
   fingerprint per turn and re-earned in a later turn, because the same command
   failing again after an operator turn is news again.
-- **Next-turn reminder.** Post-compaction reactivation and any background-model
-  reminder ride the `inject_reminder` buffer into the next submitted turn, inside
-  the visible `<system-reminder>` block, and persist in the session ledger.
+- **Next-turn and tool-batch reminders.** Post-compaction reactivation and background-model
+  reminders ride the `inject_reminder` buffer into the visible `<system-reminder>` block
+  and persist in the session ledger. During active multi-tool execution loops, deferred
+  reminders from completed background evaluations can also drain at native tool-batch
+  boundaries (`prepareToolContinuation`), injecting actionable guidance between tool
+  iterations without waiting for the operator to submit a new prompt. Reminders for
+  aborted turns are dropped.
 
 A boundary that already spoke through the annotation stays silent at turn end and
 records one telemetry row, not two.
@@ -166,9 +188,12 @@ 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
-delivered through the deferred-reminder path into the next submitted turn, which
-is exactly where an awaited turn_end reminder would have been buffered anyway.
+immediately; the turn ends on schedule. When the step resolves, its reminder
+joins the deferred-reminder buffer that an awaited `turn_end` reminder would have
+landed in anyway, and drains at the next boundary that can carry it: a native
+tool-batch boundary if the session is still executing tools, otherwise the next
+accepted prompt.
+
 Two consequences follow, both deliberate:
 
 - At most one background step is alive per session. A boundary that arrives while
@@ -191,27 +216,37 @@ procedural ID or it is recorded as `gated` and remains invisible.
 
 ### Outcome semantics
 
-The `/memory` overlay displays `last <decision>` where `<decision>` is the
-combined outcome of the most recent actual memory boundary. A **memory boundary**
-is a turn-end evaluation that includes newly completed tools or an explicit
-deterministic trigger (interval, error-streak, loop signal). A no-tool
-middleware continuation is another turn-end with no new tools since the previous
-boundary. It is not a new memory boundary and does not replace the prior outcome.
-Thus `last` remains `injected` across such continuations until a later
-tool-bearing or explicitly triggered memory step produces a new outcome (e.g.,
-a healthy tool leading to `silent`).
+The `/memory` overlay displays `last <decision>`, the combined outcome of the most
+recent actual memory boundary. A **memory boundary** evaluates newly completed
+tools or an explicit deterministic trigger, such as an interval, error streak, or
+loop signal. Model-backed evaluation can run at a settled native tool-batch
+boundary as well as at turn end.
+
+A no-tool middleware continuation is another turn-end with no new tools since the
+previous boundary, so it is not a new memory boundary and does not replace the
+prior outcome. `last` therefore remains `injected` across such continuations until
+a later tool-bearing or explicitly triggered step produces a new outcome, such as
+a healthy tool leading to `silent`.
 
 ## Cost and the default decision
 
 The LLM tier costs real tokens, real seconds of model time, and a request slot on
-a server that is usually the same machine the operator's own turns run on. Every
-step is therefore accounted for the way a `/btw` side question is: one cost entry
-under the `background-memory` label, which `/cost` shows as its own `memory steps`
-row, and one durable row in `<stateDir>/usage/out-of-turn.jsonl` carrying the
-usage, the call's duration, and the backend's prefill facts, which
-`clio-coder usage report` folds after the process exits. `/memory` shows the
-lifetime figures folded from `steps.jsonl`: steps, tokens, model time, and the
-hit rate.
+a server that is usually the same machine the operator's own turns run on.
+
+Every step is therefore accounted for the way a `/btw` side question is: one cost
+entry under the `background-memory` label, which `/cost` shows as its own
+`memory steps` row, and one durable row in `<stateDir>/usage/out-of-turn.jsonl`
+carrying the usage, the call's duration, and the backend's prefill facts.
+`clio-coder usage report` folds those rows after the process exits, and `/memory`
+shows the lifetime figures folded from `steps.jsonl`: steps, tokens, model time,
+and the hit rate.
+
+The measurements below are one operator's dated testbed run on one route. They
+are evidence for the default that was chosen, not a figure any other route will
+reproduce.
+
+<details>
+<summary>The 274-row operator export from 2026-08-14 to 2026-08-29</summary>
 
 ### The measurement
 
@@ -233,6 +268,8 @@ Four further injections in the same window came from the free rules tier, so the
 lifetime total of 10 injections is not the model tier's score. Rules-tier
 injections cost nothing.
 
+</details>
+
 ### The decision
 
 The default does not change, and it is a deliberate default rather than an
@@ -257,7 +294,14 @@ unexamined one:
 
 ### Dedicated routing, chat fallback and endpoint capacity
 
-Clio prefers the explicitly configured memory target and model. If that route is
+Clio prefers the explicitly configured memory target and model, uses the active
+chat route when that one is known unavailable, and skips the step entirely when
+the endpoint has no request capacity left.
+
+<details>
+<summary>Exactly which failures permit a chat attempt, and how capacity is counted</summary>
+
+If the dedicated 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
@@ -283,17 +327,20 @@ 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.
+its URL. Distinct model routes can share that gateway URL (for example, separate
+chat and memory target profiles pointing to the same LiteLLM proxy); 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.
 
+</details>
+
 ## Choosing a background model
 
 Memory reads a trajectory and writes a fixed envelope. It does not plan, and it
@@ -351,37 +398,43 @@ context:
 ```
 
 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 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.
+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 and only an actual injection
+reaches the transcript. It carries counts and outcomes only, never bank or
+trajectory text.
+
+`/settings` exposes controls for every key above, with shorter operator-facing
+row labels. The saved background-memory target is the Memory target row in
+Settings → Context & Memory, independent of the chat target and the fleet default. A
+running session owns its routing snapshot; the saved selection becomes the
+default for new sessions.
 
 An example gateway topology keeps the three backend routes distinct:
 
+<details>
+<summary>A worked three-route gateway topology and its role selection</summary>
+
 | 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 |
+| Chat and memory fallback | `chat-target` | LiteLLM at `http://192.168.1.20:4000` | `chat-profile/qwen3.8-27b` | Gateway-owned unless an explicit or observed endpoint bound is available |
+| Preferred background memory | `memory-dedicated` | Same LiteLLM gateway | `memory-profile/ornith-1.5-35b-a3b` | Same capacity evidence rules |
+| Alternative memory candidate | `memory-fallback` | Same LiteLLM gateway | `memory-profile/ornith1.5-35b-moe` | Same capacity evidence rules |
 
-The corresponding role selection is:
+The corresponding role selection in `settings.yaml` is:
 
 ```yaml
 chat:
-  target: dynamo
-  model: dynamo/qwen3.8-27b
+  target: chat-target
+  model: chat-profile/qwen3.8-27b
 context:
   memory:
-    target: zbook
-    model: zbook/ornith-1.5-35b-a3b
+    target: memory-dedicated
+    model: memory-profile/ornith-1.5-35b-a3b
 ```
 
 These are example configured target/model IDs, not built-in routes. Compare a
@@ -389,6 +442,8 @@ 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.
 
+</details>
+
 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 `60000` is a bounded compromise,
 and a step that exceeds it records `timeout` with
@@ -402,8 +457,8 @@ real target surfaces to verify the route:
 
 ```bash
 clio-coder targets --probe
-clio-coder models --target mini
-clio-coder models --target dynamo
+clio-coder models --target memory-dedicated
+clio-coder models --target chat-target
 clio-coder
 ```
 
@@ -425,6 +480,7 @@ the operator, the entries it cited are also proposed into the durable store at
 `<dataDir>/memory/records.json`, unapproved, scoped to the repository the session
 is working in, with provenance naming the session and the source entry. That is
 the one automatic writer of that file; everything else about it is unchanged.
+
 `/memory` and `clio-coder memory list` show the proposal, and
 `clio-coder memory approve <id>` is still a separate operator action, so nothing
 the background plane produced reaches a system prompt without review. A step with
@@ -439,6 +495,11 @@ promotable by hand from `/memory`.
 
 ## What the LLM tier actually writes
 
+The historical measurements below describe one model and route; they are not guarantees for other models.
+
+<details>
+<summary>What one measured model produced across ten live steps and forty runs</summary>
+
 Measured on the shipped prompt against `google/gemma-4-26b-a4b-qat`, across ten
 live steps and forty controlled runs on the same route.
 
@@ -481,6 +542,8 @@ malformed envelope, usually `<operations>` with no list followed by
 model behavior rather than a route fault. The boundary drop rate remains 0% at
 shipped settings.
 
+</details>
+
 ## Handoff continuity
 
 The bank normally dies with the session. When `context-handoff` is explicitly
@@ -504,7 +567,12 @@ Each completed memory-policy attempt appends one content-free record to:
 ```
 
 Use `clio-coder paths --json` to resolve the state directory (the `"state"` property). The log rotates after 1 MiB and
-keeps one previous generation as `steps.jsonl.1`. Every exact-schema record has:
+keeps one previous generation as `steps.jsonl.1`.
+
+<details>
+<summary>Every field in a steps.jsonl record and what each outcome means</summary>
+
+Every exact-schema record has:
 
 - timestamp and schema version;
 - one to three coalesced trigger reasons;
@@ -539,8 +607,19 @@ Note that routine no-tool continuation checks do not emit telemetry rows, as the
 are not considered new memory boundaries. Only actual tool-bearing or explicitly
 triggered memory steps produce rows.
 
+</details>
+
 ## Evaluation and promotion bar
 
+The bar for promoting the LLM tier is a measured pass-rate gain from a small
+number of specific, usually cited reminders at an acceptable added token and
+latency cost. Injecting at least once per task while merely tying or losing to
+baseline is a regression, even when every reminder is cited, and one anecdotal
+task is not evidence.
+
+<details>
+<summary>How the A/B harness runs, what it reports, and how to compare live</summary>
+
 `src/domains/eval/proactive-memory.ts` exports a fixed three-task, matched A/B
 harness. It executes `baseline`, `rules`, and `llm` variants in stable order and
 accepts any `{ id, model }` target. A runner adapter owns isolated task execution
@@ -561,18 +640,23 @@ There is therefore no maintained direct test coverage or standalone
 explicit measurement campaign.
 
 For a live local comparison, an adapter should route only the `llm` variant
-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.
-Injecting at least once per task while merely tying or losing to baseline is
-always a regression, even when every reminder is cited.
+through the request's target/model (e.g., using a dedicated local memory target
+such as `memory-dedicated` / `ornith1.5-35b-moe`), keep baseline memory telemetry
+empty, and run all nine trials in equivalent isolated workspaces.
+
+</details>
 
 ## Worker growth path
 
-Worker-side intervention is intentionally not implemented in this sprint. The
-bank, policy client, telemetry, and registration interfaces carry no interactive
+Worker-side memory intervention is not implemented. Nothing in
+`src/domains/memory/` is worker-aware, and no worker path registers a memory
+policy. What exists today is a set of interfaces that were kept free of
+interactive chat-loop types so a per-worker instantiation stays possible.
+
+<details>
+<summary>The seams a future worker-side memory would use</summary>
+
+The bank, policy client, telemetry, and registration interfaces carry no interactive
 chat-loop types, so they can be instantiated per worker later without moving the
 policy into the action agent.
 
@@ -594,3 +678,5 @@ The future sequence is therefore worker events → worker-local registration →
 bounded steering advisory between batches. It must preserve the current receipt,
 safety, timeout, and permission semantics, and it should ship only after a
 Terminal-Bench-style long-run evaluation shows a selective benefit.
+
+</details>

package/docs/guide/resource-library.md

@@ -2,6 +2,8 @@
 
 The **library** is Clio's collection of installable **packages**. Each package has one kind: `plugin`, `skill`, `agent`, `prompt`, or `fleet`. Every kind uses a root `plugin.json`, an explicit Semantic Version, a full-tree SHA-256 pin, and the same installation state. A plugin bundles several resources; each other kind exposes one public resource and may include supporting files.
 
+Bundled packages are available on a fresh installation, but none are installed automatically. Built-in runtime tools and helper recipes remain available independently of optional library packages.
+
 ## Browse and install
 
 ```bash
@@ -34,6 +36,8 @@ clio-coder library update plugin:materio --project
 clio-coder library remove plugin:materio --project
 ```
 
+The list labels drifted copies `damaged`, not `shadowed`. Inspect changes before running `clio-coder library update kind:name --user --force` (or `--project`) to restore the recorded source; edited files are preserved in a recovery backup. Enabling alone cannot repair drift.
+
 Drift prevents resources from loading. `pin` verifies and reports the recorded pin; it never blesses local changes. Updates of registered packages use the current index version and pin. Local installations update from their recorded directory. Update and replacement preserve disabled state. Removal preserves edited content and reports the recovery path. Installed state remains addressable after its index entry disappears.
 
 Interop adoption records `{kind: "interop", host, source}` and `trust: "foreign"`. Foreign skills and prompts require `integrations.projectResources.trustProjectImports`, including foreign project files adopted to user scope. Updates and forced replacement of an interop-origin package are refused: remove it and review a new adoption so omitted host executables cannot reappear. See [interoperability](interop.md).

package/docs/guide/skills-marketplace.md

@@ -9,11 +9,11 @@ clio-coder library install skill:grill-me --project
 clio-coder library skills --all --json
 ```
 
-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).
+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. The `/skill` install offer lets you choose the active user profile or the current project. Slash commands are entered in Clio, not in a shell. An unmanaged `SKILL.md` remains a valid runtime resource; preparing a distributable requires a package manifest as described in [authoring](authoring-plugins.md).
 
 ## Operator ownership of installed skills
 
-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.
+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. Canonical `clio-coder library` mutations through the model’s bash tool require one-shot operator approval, including at full-auto. Explicit operator requests can therefore be carried out by the agent using the managed installer; direct instruction-file edits remain blocked. Legacy resource mutation commands remain operator-only; 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.
 
 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`.
 
@@ -35,9 +35,9 @@ Draft outside active roots, for example `draft-skills/example/`. The operator ca
 
 `/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.
 
-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.
+Model-visible skills must be trusted and permit model invocation. Loose compatibility skills are discovery-only at user and project scope and require explicit import. Imported 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.
 
-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.
+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 imported packages that the operator explicitly trusts. A named load of an untrusted or manual-only skill reports that restriction instead of claiming the skill is unknown.
 
 ## Matching, authoring and evals
 
@@ -52,3 +52,7 @@ Named suite evals use `clio-coder eval run --package skill:<name> --eval <suite>
 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.
 
 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.
+
+The model-facing `context(scope="skills")` inventory separates Clio-local/plugin skills, discovered compatibility or explicit-path skills, and uninstalled marketplace entries. Discovered entries retain their source, scope, and file path. Availability through another agent’s skill root does not mean Clio installed or copied that skill; resetting Clio does not remove those external files.
+
+Inventory distinguishes ready skills from installed package state. An install performed in another process appears as installed even before `/library reload` admits it into the session. Disabled, damaged, untrusted, and pending-reload copies are not advertised as ready. Marketplace suggestions exclude actual Clio copies, not loose discoveries from other agents.

package/docs/guide/slurm.md

@@ -0,0 +1,88 @@
+# Slurm through the clio-kit MCP server
+
+Clio Coder reaches Slurm through the Slurm MCP server that
+[clio-kit](https://github.com/iowarp/clio-kit) ships, over the same local stdio
+MCP gateway every other MCP server uses. There is no Slurm transport inside
+Clio and no `srun` or `sbatch` worker tier: the agent submits, polls, and
+cancels jobs by calling five gateway capabilities, and the scheduler does the
+rest.
+
+## Set it up
+
+Install clio-kit so `clio-kit` is on `PATH` (for example
+`uv tool install clio-kit`), on a host where `sbatch`, `squeue`, `scontrol`,
+and `scancel` reach your cluster. Then declare the server in the user file
+`<Clio config directory>/mcp.yaml` (`clio-coder paths` prints the directory):
+
+```yaml
+version: 1
+servers:
+  - id: slurm
+    command: clio-kit
+    args: [mcp-server, slurm]
+    timeoutMs: 120000
+```
+
+The id `slurm` is what the library skill expects. The first launch lets
+clio-kit prepare its private runtime for the server, which can take longer
+than the 15 second initialize bound on a cold cache; run
+`clio-kit mcp-server slurm` once in a terminal first and stop it with Ctrl-C.
+A project can declare the same server in `.clio-coder/mcp.yaml`; it then needs
+`clio-coder mcp trust slurm` before it ever launches. See
+[local stdio MCP configuration and trust](configuration-reference.md#local-stdio-mcp-configuration-and-trust).
+
+`clio-coder doctor` reports the pieces: a `slurm clio-kit` row (the binary and
+whether its build ships the Slurm server), a `slurm mcp server` row (which
+`mcp.yaml` declares it, its scope, and its trust), and a `slurm scheduler` row
+(`sbatch` and `squeue`). On an install with none of them there is one
+informational `slurm mcp` row. None of these rows ever fails doctor.
+
+## The five capabilities
+
+The gateway lists them as `mcp_slurm__<tool>`. Find them with
+`gateway(op="find", query="slurm")` and read a tool's parameters with
+`gateway(op="describe", capability="mcp_slurm__slurm_submit")`.
+
+| Capability | What it does |
+| --- | --- |
+| `mcp_slurm__slurm_submit` | Submits one job or array from `script_path` with `cores`, `memory`, `time_limit`, and optional `job_name`, `partition`, and `array`. Returns the scheduler job id. Not idempotent. |
+| `mcp_slurm__slurm_list` | Lists a bounded number of jobs, filtered by `user`, `state`, and `partition`. |
+| `mcp_slurm__slurm_describe` | Describes one job: state, whether it is terminal, scheduler properties, and optional bounded stdout and stderr tails (`output`, `max_output_chars`). |
+| `mcp_slurm__slurm_cluster` | One snapshot of partitions and the queue, with node details on request. |
+| `mcp_slurm__slurm_cancel` | Cancels one job. `confirm_job_id` must repeat `job_id` exactly or the server refuses without calling `scancel`. |
+
+The server also exposes its older tool names (`submit_slurm_job`,
+`check_job_status`, and so on). Prefer the five above.
+
+## How autonomy treats them
+
+An MCP server carries one action class for all of its tools, and the server's
+own annotations never choose it. A user-scope declaration gets the class
+`unknown`, and `unknown` asks for one-shot approval at `suggest`, `auto-edit`,
+and `full-auto` and is denied at `read-only`. So with the declaration above:
+
+- `slurm_submit` and `slurm_cancel` always ask before they reach the
+  scheduler. A denied call never launches a job.
+- `slurm_list`, `slurm_describe`, and `slurm_cluster` ask too, although they
+  only read. Polling a job costs one approval per poll.
+- A headless `clio-coder run` answers every ask with a denial, so it cannot
+  submit through this path.
+
+A project declaration can be trusted with another class:
+`clio-coder mcp trust slurm --action-class read` makes all five run without
+asking, submissions and cancellations included, because the class is per
+server. Do that only in a workspace where an unattended `sbatch` is
+acceptable. `--action-class execute` routes the server's launch command
+through the bash policy and then follows the execute row of the
+[autonomy table](../architecture/safety-model.md#autonomy-levels). There is no
+per-tool class today.
+
+## The skill
+
+`clio-coder library install skill:slurm-jobs --project`, then
+`/skill slurm-jobs <script and what to report>`. It checks that the server is
+declared, looks at the partition, submits once, polls
+`mcp_slurm__slurm_describe` with a growing wait until the state is terminal,
+fetches bounded output, and ends its answer with
+`Slurm job <id>: <state>, exit <code>, stdout <path>, stderr <path>`. It never
+falls back to `sbatch` through `bash`.