@klhapp/skillmux 1.7.1 → 1.9.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.9.0](https://github.com/klhq/skillmux/compare/v1.8.0...v1.9.0) (2026-08-30)
+
+
+### Added
+
+* track skill provenance and add outdated/update commands ([#133](https://github.com/klhq/skillmux/issues/133)) ([4d4f8c9](https://github.com/klhq/skillmux/commit/4d4f8c94a7e34e1ad030f9904995d02fa5fa2712))
+
+
+### Fixed
+
+* **install:** guard findSymlinks against a symlinked skill_path directory itself ([#146](https://github.com/klhq/skillmux/issues/146)) ([a264afc](https://github.com/klhq/skillmux/commit/a264afc19710206c4f77c61e3a9dccafb54c2894))
+* **install:** prevent symlink smuggling in skill content ([#136](https://github.com/klhq/skillmux/issues/136)) ([2df318c](https://github.com/klhq/skillmux/commit/2df318cfdc974b0f7b9042c3d68fa4fece9109d9))
+* **provenance:** refuse to hash a symlinked SKILL.md instead of following it ([#141](https://github.com/klhq/skillmux/issues/141)) ([74d1b9c](https://github.com/klhq/skillmux/commit/74d1b9c2f8fb2891ce743ccf09b9632fea58aa84))
+* **provenance:** refuse to read a symlinked .skillmux-origin sidecar ([#144](https://github.com/klhq/skillmux/issues/144)) ([c9c0b32](https://github.com/klhq/skillmux/commit/c9c0b327f8cf26e1a9cd9971263cfa4f35235de3))
+* **scan:** guard readTextFileOrNull against symlinks at every call site ([#143](https://github.com/klhq/skillmux/issues/143)) ([6692060](https://github.com/klhq/skillmux/commit/66920601bb4969911063407afa3dbffcf09c00be))
+* **scan:** refuse to scan a symlinked SKILL.md in single-skill-dir mode ([#142](https://github.com/klhq/skillmux/issues/142)) ([b20cd66](https://github.com/klhq/skillmux/commit/b20cd6621a30067643034dd155383afab3540cf2))
+* **security:** validate provenance sidecar values before they reach git subprocess calls ([#135](https://github.com/klhq/skillmux/issues/135)) ([01d643a](https://github.com/klhq/skillmux/commit/01d643a789e353d0d944b7b467f3c9f0894718ce))
+* **sync:** skip symlinking core skill dirs with internal links ([#137](https://github.com/klhq/skillmux/issues/137)) ([f992b39](https://github.com/klhq/skillmux/commit/f992b39720dcdd3e946c6628817bd11b54380f40))
+* **update:** skip file:// source_url in outdated/update by default ([#147](https://github.com/klhq/skillmux/issues/147)) ([9b127d0](https://github.com/klhq/skillmux/commit/9b127d0a65f89cfd32e6ed8d75155ba388349fae))
+* **vault:** guard against a symlinked skill directory, not just its leaf files ([#145](https://github.com/klhq/skillmux/issues/145)) ([63d34e3](https://github.com/klhq/skillmux/commit/63d34e32bc4d91221f03fbbfdf22d3a0fdc7a492))
+* **vault:** refuse to read a symlinked SKILL.md ([#140](https://github.com/klhq/skillmux/issues/140)) ([3220fe3](https://github.com/klhq/skillmux/commit/3220fe393a81922f76729284d156644662f177f2))
+* **vault:** secure listSupportingFiles against symlinks and traversal ([#138](https://github.com/klhq/skillmux/issues/138)) ([6343a30](https://github.com/klhq/skillmux/commit/6343a30747844c5f83b810cbfe3d19ed569ca7cd))
+
+
+### Changed
+
+* **update:** skip cloning drifted skills before fetching ([1b247b6](https://github.com/klhq/skillmux/commit/1b247b6379b021692c839a77d44a81bd736f2bea))
+
+## [1.8.0](https://github.com/klhq/skillmux/compare/v1.7.1...v1.8.0) (2026-08-28)
+
+
+### Added
+
+* **audit:** add fetch-outcome routing quality flywheel ([#131](https://github.com/klhq/skillmux/issues/131)) ([c55e5ec](https://github.com/klhq/skillmux/commit/c55e5ec794453ccbdbf7ffe9263684356d2a71de))
+
 ## [1.7.1](https://github.com/klhq/skillmux/compare/v1.7.0...v1.7.1) (2026-08-21)
 
 

package/README.md

@@ -1,5 +1,8 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/klhq/skillmux/main/docs/assets/logo.png" alt="skillmux" width="400">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/klhq/skillmux/main/docs/assets/logo-dark.png">
+    <img src="https://raw.githubusercontent.com/klhq/skillmux/main/docs/assets/logo-light.png" alt="skillmux" width="400">
+  </picture>
 </p>
 
 <p align="center">
@@ -9,9 +12,12 @@
   <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
 </p>
 
-Skillmux manages [`SKILL.md`](https://agentskills.io) collections across AI
-coding clients. Keep one **vault source of truth**—the logical skill
-collection—pin a small set into native skill directories, and retrieve the
+<p align="center"><strong>One skill vault. Every AI coding client. Nothing lost in translation.</strong></p>
+
+Every AI coding client wants its own skill folder and its own format. Skillmux
+manages [`SKILL.md`](https://agentskills.io) collections across all of them
+from one place. Keep one **vault source of truth** (the logical skill
+collection), pin a small set into native skill directories, and retrieve the
 rest through MCP. A **vault checkout** is a physical copy of that collection.
 On one machine, `~/skills` can be both the source of truth and its checkout.
 
@@ -55,7 +61,10 @@ command to run; see the [container command contract](docs/deployment.md#containe
 ## One vault source of truth, three ways to use it
 
 <p align="center">
-  <img src="docs/assets/architecture.svg" alt="Three ways to use Skillmux: manage native skills, add local MCP retrieval, or run a shared MCP service" width="100%">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/architecture-dark.svg">
+    <img src="docs/assets/architecture-light.svg" alt="Three ways to use Skillmux: manage native skills, add local MCP retrieval, or run a shared MCP service" width="100%">
+  </picture>
 </p>
 
 “Local” describes where Skillmux runs. “Local inference” means the embedding
@@ -204,6 +213,7 @@ Useful management commands:
 
 ```sh
 skillmux scan ~/skills
+skillmux outdated
 skillmux core pin csv-formatter --yes
 skillmux project pin my-project code-context --yes
 skillmux skill which csv-formatter

package/docs/assets/architecture-dark.svg

@@ -0,0 +1,160 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 720" role="img" aria-labelledby="title desc">
+  <title id="title">One vault source of truth, three ways to use Skillmux</title>
+  <desc id="desc">One Git-backed vault source of truth holds one SKILL.md per child directory and feeds a client checkout and a server checkout. On a client machine, Skillmux CLI manages native skills and serves local stdio MCP; a server checkout serves shared Streamable HTTP MCP. resolve_skill fuses lexical and vector results and optionally reranks them; fetch_skill returns the current SKILL.md bytes with a SHA-256. Git and deployment own checkout replication and freshness.</desc>
+
+  <defs>
+    <filter id="shadow" x="-15%" y="-15%" width="130%" height="140%">
+      <feDropShadow dx="0" dy="5" stdDeviation="8" flood-color="#000000" flood-opacity="0.35"/>
+    </filter>
+    <marker id="arrow-teal" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto">
+      <path d="M0 0L10 5L0 10Z" fill="#2dd4bf"/>
+    </marker>
+    <marker id="arrow-blue" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto">
+      <path d="M0 0L10 5L0 10Z" fill="#60a5fa"/>
+    </marker>
+    <marker id="arrow-violet" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto">
+      <path d="M0 0L10 5L0 10Z" fill="#a78bfa"/>
+    </marker>
+    <style>
+      text {
+        font-family: "DejaVu Sans", Arial, sans-serif;
+      }
+      .title {
+        font-size: 27px;
+        font-weight: 750;
+        fill: #e2e8f0;
+      }
+      .subtitle {
+        font-size: 16px;
+        font-weight: 400;
+        fill: #94a3b8;
+      }
+      .card-title {
+        font-size: 21px;
+        font-weight: 750;
+        fill: #e2e8f0;
+      }
+      .label {
+        font-size: 15px;
+        font-weight: 650;
+        fill: #cbd5e1;
+      }
+      .body {
+        font-size: 14px;
+        font-weight: 400;
+        fill: #94a3b8;
+      }
+      .mono {
+        font-family: "DejaVu Sans Mono", Consolas, monospace;
+        font-size: 14px;
+        font-weight: 650;
+        fill: #cbd5e1;
+      }
+      .mono-light {
+        fill: #ffffff;
+      }
+      .chip {
+        font-size: 12px;
+        font-weight: 750;
+        letter-spacing: .5px;
+      }
+    </style>
+  </defs>
+
+  <rect width="1200" height="720" rx="24" fill="#0d1117"/>
+  <rect x="1" y="1" width="1198" height="718" rx="23" fill="none" stroke="#30363d" stroke-width="2"/>
+
+  <text x="48" y="50" class="title">One vault source of truth, three ways to use Skillmux</text>
+  <text x="48" y="78" class="subtitle">Git and deployment replicate checkouts; Skillmux uses each checkout where it runs.</text>
+
+  <g filter="url(#shadow)">
+    <rect x="280" y="106" width="640" height="118" rx="18" fill="#161b22" stroke="#30363d" stroke-width="2"/>
+    <circle cx="324" cy="147" r="18" fill="#334155"/>
+    <path d="M314 141H327L333 147L327 153H314M320 135V159" fill="none" stroke="#ffffff" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"/>
+    <text x="358" y="144" class="card-title">Git-backed vault source of truth</text>
+    <text x="358" y="172" class="mono">SKILL.md per child directory</text>
+    <text x="358" y="200" class="body">A checkout is a physical copy of it on one machine.</text>
+    <rect x="751" y="155" width="137" height="34" rx="9" fill="#1e293b" stroke="#475569"/>
+    <text x="819.5" y="177" text-anchor="middle" class="mono">skillmux.toml</text>
+  </g>
+
+  <path d="M520 224V252H410V277" fill="none" stroke="#2dd4bf" stroke-width="3" marker-end="url(#arrow-teal)"/>
+  <path d="M720 224V252H980V277" fill="none" stroke="#a78bfa" stroke-width="3" marker-end="url(#arrow-violet)"/>
+  <text x="394" y="270" text-anchor="end" class="body">client checkout</text>
+  <text x="996" y="270" text-anchor="start" class="body">server checkout</text>
+
+  <g filter="url(#shadow)">
+    <rect x="40" y="284" width="740" height="302" rx="18" fill="#161b22" stroke="#0f766e" stroke-width="2"/>
+    <rect x="62" y="306" width="124" height="26" rx="13" fill="#134e4a"/>
+    <text x="124" y="324" text-anchor="middle" class="chip" fill="#5eead4">SKILLMUX CLI</text>
+    <text x="62" y="365" class="card-title">On one client machine</text>
+    <text x="62" y="390" class="body">Manage native skills, add local MCP retrieval, or do both.</text>
+
+    <rect x="62" y="414" width="276" height="48" rx="10" fill="#0f2e2b" stroke="#0f766e"/>
+    <circle cx="85" cy="438" r="11" fill="#2dd4bf"/>
+    <text x="85" y="442.5" text-anchor="middle" style="font-size: 13px; font-weight: 750" fill="#0d1117">1</text>
+    <text x="200" y="433" text-anchor="middle" class="label" style="font-size: 17px">Manage native skills</text>
+    <text x="200" y="453" text-anchor="middle" class="mono">skillmux init · sync</text>
+    <path d="M200 462V487" fill="none" stroke="#2dd4bf" stroke-width="2.5" marker-end="url(#arrow-teal)"/>
+    <rect x="62" y="493" width="276" height="49" rx="10" fill="#1e293b" stroke="#475569"/>
+    <text x="200" y="514" text-anchor="middle" class="label">Native skill directories</text>
+    <text x="200" y="533" text-anchor="middle" class="body">managed core and project links</text>
+
+    <text x="62" y="570" class="body">Install Skillmux CLI with</text>
+    <rect x="270" y="550" width="85" height="27" rx="8" fill="#0f172a" stroke="#334155"/>
+    <text x="312.5" y="568" text-anchor="middle" class="chip" style="font-size: 10px" fill="#ffffff">BUN PACKAGE</text>
+    <rect x="361" y="550" width="87" height="27" rx="8" fill="#1e293b" stroke="#475569"/>
+    <text x="404.5" y="561" text-anchor="middle" class="chip" style="font-size: 10px" fill="#cbd5e1"><tspan x="404.5">LINUX</tspan><tspan x="404.5" dy="11">EXECUTABLE</tspan></text>
+  </g>
+
+  <g filter="url(#shadow)">
+    <rect x="420" y="414" width="338" height="128" rx="10" fill="#172554" stroke="#3b82f6"/>
+    <circle cx="453" cy="435" r="11" fill="#60a5fa"/>
+    <text x="453" y="439.5" text-anchor="middle" style="font-size: 13px; font-weight: 750" fill="#0d1117">2</text>
+    <text x="476" y="441" class="label" style="font-size: 17px">Add local MCP retrieval</text>
+    <text x="442" y="463" class="body">Reaches the whole indexed vault on demand.</text>
+
+    <rect x="442" y="475" width="92" height="48" rx="10" fill="#1e293b" stroke="#475569"/>
+    <text x="488" y="505" text-anchor="middle" class="label">AI client</text>
+    <path d="M534 499H578" fill="none" stroke="#60a5fa" stroke-width="2.5" marker-end="url(#arrow-blue)"/>
+    <text x="559" y="489" text-anchor="middle" class="body">stdio</text>
+    <rect x="584" y="470" width="152" height="62" rx="10" fill="#161b22" stroke="#3b82f6"/>
+    <text x="660" y="492" text-anchor="middle" class="mono">skillmux serve</text>
+    <text x="660" y="511" text-anchor="middle" class="body">default: FTS5 +</text>
+    <text x="660" y="527" text-anchor="middle" class="body">local GTE-small</text>
+
+  </g>
+
+  <g filter="url(#shadow)">
+    <rect x="800" y="284" width="360" height="302" rx="18" fill="#161b22" stroke="#7c3aed" stroke-width="2"/>
+    <rect x="822" y="306" width="136" height="26" rx="13" fill="#312e81"/>
+    <text x="890" y="324" text-anchor="middle" class="chip" fill="#c4b5fd">SKILLMUX SERVER</text>
+    <circle cx="833" cy="358" r="11" fill="#a78bfa"/>
+    <text x="833" y="362.5" text-anchor="middle" style="font-size: 13px; font-weight: 750" fill="#0d1117">3</text>
+    <text x="856" y="365" class="card-title">Run a shared MCP service</text>
+    <text x="822" y="390" class="body">Read a server checkout to serve several clients.</text>
+
+    <rect x="822" y="414" width="92" height="48" rx="10" fill="#1e293b" stroke="#475569"/>
+    <text x="868" y="435" text-anchor="middle" class="label">AI clients</text>
+    <text x="868" y="453" text-anchor="middle" class="body">one or more</text>
+    <path d="M914 438H963" fill="none" stroke="#a78bfa" stroke-width="2.5" marker-end="url(#arrow-violet)"/>
+    <text x="939" y="428" text-anchor="middle" class="body">HTTP</text>
+    <rect x="969" y="414" width="169" height="48" rx="10" fill="#2e1065" stroke="#7c3aed"/>
+    <text x="1053.5" y="435" text-anchor="middle" class="label">Skillmux server</text>
+    <text x="1053.5" y="453" text-anchor="middle" class="body" style="font-size: 13px">Streamable HTTP /mcp</text>
+
+    <rect x="822" y="484" width="148" height="58" rx="10" fill="#2e1065" stroke="#7c3aed"/>
+    <text x="896" y="507" text-anchor="middle" class="label">Full image</text>
+    <text x="896" y="530" text-anchor="middle" class="body">GTE-small included</text>
+    <rect x="982" y="484" width="156" height="58" rx="10" fill="#1e293b" stroke="#475569"/>
+    <text x="1060" y="507" text-anchor="middle" class="label">Slim image</text>
+    <text x="1060" y="530" text-anchor="middle" class="body">remote or lexical</text>
+
+    <text x="822" y="570" class="body">Full image is the default deployment.</text>
+  </g>
+
+  <rect x="420" y="608" width="740" height="82" rx="14" fill="#1e293b"/>
+  <text x="444" y="633" class="chip" fill="#cbd5e1">MCP TOOL CONTRACT · STDIO + HTTP</text>
+  <text x="444" y="655" class="mono mono-light" style="font-size: 12px">resolve_skill → lexical + vector → RRF → optional rerank → top_k → ranked candidates</text>
+  <text x="444" y="677" class="mono mono-light" style="font-size: 12px">fetch_skill → current SKILL.md bytes + SHA-256</text>
+</svg>

package/docs/assets/{architecture.svg → architecture-light.svg}

@@ -1,6 +1,6 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 720" role="img" aria-labelledby="title desc">
   <title id="title">One vault source of truth, three ways to use Skillmux</title>
-  <desc id="desc">One Git-backed vault source of truth has a client checkout for Skillmux CLI native management and local MCP retrieval, plus a server checkout for shared Streamable HTTP MCP. Resolve uses retrieval, fusion, and optional reranking; fetch returns the current SKILL.md directly. Git and deployment own checkout replication and freshness.</desc>
+  <desc id="desc">One Git-backed vault source of truth holds one SKILL.md per child directory and feeds a client checkout and a server checkout. On a client machine, Skillmux CLI manages native skills and serves local stdio MCP; a server checkout serves shared Streamable HTTP MCP. resolve_skill fuses lexical and vector results and optionally reranks them; fetch_skill returns the current SKILL.md bytes with a SHA-256. Git and deployment own checkout replication and freshness.</desc>
 
   <defs>
     <filter id="shadow" x="-15%" y="-15%" width="130%" height="140%">
@@ -68,14 +68,14 @@
   <text x="48" y="78" class="subtitle">Git and deployment replicate checkouts; Skillmux uses each checkout where it runs.</text>
 
   <g filter="url(#shadow)">
-    <rect x="330" y="106" width="540" height="118" rx="18" fill="#ffffff" stroke="#cbd5e1" stroke-width="2"/>
-    <circle cx="374" cy="147" r="18" fill="#0f172a"/>
-    <path d="M364 141H377L383 147L377 153H364M370 135V159" fill="none" stroke="#ffffff" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"/>
-    <text x="408" y="144" class="card-title">Git-backed vault source of truth</text>
-    <text x="408" y="172" class="mono">logical SKILL.md collection</text>
-    <text x="408" y="200" class="body">Git + deployment own replication and freshness</text>
-    <rect x="701" y="139" width="137" height="34" rx="9" fill="#f1f5f9" stroke="#cbd5e1"/>
-    <text x="769.5" y="161" text-anchor="middle" class="mono">skillmux.toml</text>
+    <rect x="280" y="106" width="640" height="118" rx="18" fill="#ffffff" stroke="#cbd5e1" stroke-width="2"/>
+    <circle cx="324" cy="147" r="18" fill="#0f172a"/>
+    <path d="M314 141H327L333 147L327 153H314M320 135V159" fill="none" stroke="#ffffff" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"/>
+    <text x="358" y="144" class="card-title">Git-backed vault source of truth</text>
+    <text x="358" y="172" class="mono">SKILL.md per child directory</text>
+    <text x="358" y="200" class="body">A checkout is a physical copy of it on one machine.</text>
+    <rect x="751" y="155" width="137" height="34" rx="9" fill="#f1f5f9" stroke="#cbd5e1"/>
+    <text x="819.5" y="177" text-anchor="middle" class="mono">skillmux.toml</text>
   </g>
 
   <path d="M520 224V252H410V277" fill="none" stroke="#0f766e" stroke-width="3" marker-end="url(#arrow-teal)"/>
@@ -87,11 +87,13 @@
     <rect x="40" y="284" width="740" height="302" rx="18" fill="#ffffff" stroke="#99d5cc" stroke-width="2"/>
     <rect x="62" y="306" width="124" height="26" rx="13" fill="#ccfbf1"/>
     <text x="124" y="324" text-anchor="middle" class="chip" fill="#115e59">SKILLMUX CLI</text>
-    <text x="62" y="365" class="card-title">Skillmux CLI</text>
-    <text x="62" y="390" class="body">A client-machine checkout supports native management and/or local MCP.</text>
+    <text x="62" y="365" class="card-title">On one client machine</text>
+    <text x="62" y="390" class="body">Manage native skills, add local MCP retrieval, or do both.</text>
 
     <rect x="62" y="414" width="276" height="48" rx="10" fill="#f0fdfa" stroke="#99d5cc"/>
-    <text x="200" y="435" text-anchor="middle" class="label">Native management</text>
+    <circle cx="85" cy="438" r="11" fill="#0f766e"/>
+    <text x="85" y="442.5" text-anchor="middle" style="font-size: 13px; font-weight: 750" fill="#ffffff">1</text>
+    <text x="200" y="433" text-anchor="middle" class="label" style="font-size: 17px">Manage native skills</text>
     <text x="200" y="453" text-anchor="middle" class="mono">skillmux init · sync</text>
     <path d="M200 462V487" fill="none" stroke="#0f766e" stroke-width="2.5" marker-end="url(#arrow-teal)"/>
     <rect x="62" y="493" width="276" height="49" rx="10" fill="#f8fafc" stroke="#cbd5e1"/>
@@ -107,17 +109,19 @@
 
   <g filter="url(#shadow)">
     <rect x="420" y="414" width="338" height="128" rx="10" fill="#eff6ff" stroke="#93c5fd"/>
-    <text x="442" y="441" class="label">Local MCP retrieval</text>
-    <text x="442" y="463" class="body">Skillmux CLI beside one MCP client.</text>
-
-    <rect x="442" y="475" width="102" height="48" rx="10" fill="#f8fafc" stroke="#cbd5e1"/>
-    <text x="493" y="505" text-anchor="middle" class="label">AI client</text>
-    <path d="M544 499H573" fill="none" stroke="#2563eb" stroke-width="2.5" marker-end="url(#arrow-blue)"/>
-    <text x="558" y="489" text-anchor="middle" class="body">stdio</text>
-    <rect x="579" y="470" width="157" height="62" rx="10" fill="#ffffff" stroke="#93c5fd"/>
-    <text x="657.5" y="492" text-anchor="middle" class="label">Skillmux CLI</text>
-    <text x="657.5" y="511" text-anchor="middle" class="body">default: FTS5 +</text>
-    <text x="657.5" y="527" text-anchor="middle" class="body">local GTE-small</text>
+    <circle cx="453" cy="435" r="11" fill="#2563eb"/>
+    <text x="453" y="439.5" text-anchor="middle" style="font-size: 13px; font-weight: 750" fill="#ffffff">2</text>
+    <text x="476" y="441" class="label" style="font-size: 17px">Add local MCP retrieval</text>
+    <text x="442" y="463" class="body">Reaches the whole indexed vault on demand.</text>
+
+    <rect x="442" y="475" width="92" height="48" rx="10" fill="#f8fafc" stroke="#cbd5e1"/>
+    <text x="488" y="505" text-anchor="middle" class="label">AI client</text>
+    <path d="M534 499H578" fill="none" stroke="#2563eb" stroke-width="2.5" marker-end="url(#arrow-blue)"/>
+    <text x="559" y="489" text-anchor="middle" class="body">stdio</text>
+    <rect x="584" y="470" width="152" height="62" rx="10" fill="#ffffff" stroke="#93c5fd"/>
+    <text x="660" y="492" text-anchor="middle" class="mono">skillmux serve</text>
+    <text x="660" y="511" text-anchor="middle" class="body">default: FTS5 +</text>
+    <text x="660" y="527" text-anchor="middle" class="body">local GTE-small</text>
 
   </g>
 
@@ -125,17 +129,19 @@
     <rect x="800" y="284" width="360" height="302" rx="18" fill="#ffffff" stroke="#c4b5fd" stroke-width="2"/>
     <rect x="822" y="306" width="136" height="26" rx="13" fill="#ede9fe"/>
     <text x="890" y="324" text-anchor="middle" class="chip" fill="#6d28d9">SKILLMUX SERVER</text>
-    <text x="822" y="365" class="card-title">Run a shared MCP service</text>
+    <circle cx="833" cy="358" r="11" fill="#7c3aed"/>
+    <text x="833" y="362.5" text-anchor="middle" style="font-size: 13px; font-weight: 750" fill="#ffffff">3</text>
+    <text x="856" y="365" class="card-title">Run a shared MCP service</text>
     <text x="822" y="390" class="body">Read a server checkout to serve several clients.</text>
 
-    <rect x="822" y="414" width="102" height="48" rx="10" fill="#f8fafc" stroke="#cbd5e1"/>
-    <text x="873" y="435" text-anchor="middle" class="label">AI clients</text>
-    <text x="873" y="453" text-anchor="middle" class="body">one or more</text>
-    <path d="M924 438H953" fill="none" stroke="#7c3aed" stroke-width="2.5" marker-end="url(#arrow-violet)"/>
-    <text x="938" y="428" text-anchor="middle" class="body">HTTP</text>
-    <rect x="959" y="414" width="179" height="48" rx="10" fill="#f5f3ff" stroke="#c4b5fd"/>
-    <text x="1048.5" y="435" text-anchor="middle" class="label">Skillmux server</text>
-    <text x="1048.5" y="453" text-anchor="middle" class="body" style="font-size: 13px">Streamable HTTP /mcp</text>
+    <rect x="822" y="414" width="92" height="48" rx="10" fill="#f8fafc" stroke="#cbd5e1"/>
+    <text x="868" y="435" text-anchor="middle" class="label">AI clients</text>
+    <text x="868" y="453" text-anchor="middle" class="body">one or more</text>
+    <path d="M914 438H963" fill="none" stroke="#7c3aed" stroke-width="2.5" marker-end="url(#arrow-violet)"/>
+    <text x="939" y="428" text-anchor="middle" class="body">HTTP</text>
+    <rect x="969" y="414" width="169" height="48" rx="10" fill="#f5f3ff" stroke="#c4b5fd"/>
+    <text x="1053.5" y="435" text-anchor="middle" class="label">Skillmux server</text>
+    <text x="1053.5" y="453" text-anchor="middle" class="body" style="font-size: 13px">Streamable HTTP /mcp</text>
 
     <rect x="822" y="484" width="148" height="58" rx="10" fill="#f5f3ff" stroke="#c4b5fd"/>
     <text x="896" y="507" text-anchor="middle" class="label">Full image</text>
@@ -144,11 +150,11 @@
     <text x="1060" y="507" text-anchor="middle" class="label">Slim image</text>
     <text x="1060" y="530" text-anchor="middle" class="body">remote or lexical</text>
 
-    <text x="822" y="570" class="body">Recommended for a shared HTTP deployment</text>
+    <text x="822" y="570" class="body">Full image is the default deployment.</text>
   </g>
 
   <rect x="420" y="608" width="740" height="82" rx="14" fill="#0f172a"/>
   <text x="444" y="633" class="chip" fill="#cbd5e1">MCP TOOL CONTRACT · STDIO + HTTP</text>
   <text x="444" y="655" class="mono mono-light" style="font-size: 12px">resolve_skill → lexical + vector → RRF → optional rerank → top_k → ranked candidates</text>
-  <text x="444" y="677" class="mono mono-light" style="font-size: 12px">fetch_skill → exact current SKILL.md + SHA-256</text>
+  <text x="444" y="677" class="mono mono-light" style="font-size: 12px">fetch_skill → current SKILL.md bytes + SHA-256</text>
 </svg>

package/docs/cli.md

@@ -21,10 +21,11 @@ or [Managing skills](skill-management.md).
 
 The Docker image is a shared-server runtime, not a replacement for the host
 CLI. Its `skillmux --help` surface is intentionally limited to `serve`,
-`index`, `doctor`, `report`, `scan`, `skill which`, and read-only `config`
-inspection (`show`, `get`, `validate`, `diff`, and `status`). Run `init`,
-`install`, pinning, `sync`, project or target management, model downloads,
-contexts, evaluation, and configuration changes on the host.
+`index`, `doctor`, `report`, `audit prune`, `eval promote`, `scan`,
+`skill which`, and read-only `config` inspection (`show`, `get`, `validate`,
+`diff`, and `status`). Run `init`, `install`, pinning, `sync`, project or
+target management, model downloads, contexts, and bare `eval` (vault ranking
+evaluation, which needs local embeddings and the vault) on the host.
 
 When the image rejects one of those commands, it exits with code 2. JSON mode
 uses `CONTAINER_COMMAND_UNSUPPORTED` and includes `rejected_command`,
@@ -247,7 +248,7 @@ command prints the preserved path so cleanup remains an explicit user action.
 
 ## Core skills (`skillmux core`)
 
-Pin or unpin skills into `[core]` — the tier every target receives by
+Pin or unpin skills into `[core]`, the tier every target receives by
 default, capped at 25 skills:
 
 ```sh
@@ -287,6 +288,63 @@ skillmux skill which csv-formatter
 
 ---
 
+## Observability and evaluation (`skillmux report`, `audit`, `eval`)
+
+`resolve_skill` records every request to an audit log; `fetch_skill` records
+what was actually opened and, when the caller passes back the `request_id`
+from a prior resolve, correlates the fetch to that resolve and its rank in
+the shortlist. `skillmux report` summarizes this data, `skillmux audit prune`
+reclaims space, and `skillmux eval promote` turns correlated fetches into
+eval cases.
+
+```sh
+# Summarize activity from the local state or a remote server
+skillmux report --since 7d
+skillmux report --server https://skillmux.internal:3000 --since 24h
+skillmux report --db ~/.local/state/skillmux/audit.sqlite3 --since 2026-08-01
+
+# Prune audit rows older than the configured retention window (default 90 days)
+skillmux audit prune --yes
+skillmux audit prune --older-than 30d --dry-run
+skillmux audit prune --older-than 30d --json
+
+# Promote observed, correlated fetches into an eval case file
+skillmux eval promote --since 7d --dry-run
+skillmux eval promote --since 7d --yes
+skillmux eval promote --since 7d --target eval/observed.json --yes
+```
+
+`report` reads `--server <url>`, `--db <path>` (an explicit SQLite file,
+opened read-only), or the configured local `state_dir` by default;
+`--server` and `--db` are mutually exclusive. Alongside request totals,
+empty-shortlist rate, retrieval-lane totals, degradation counts, and
+per-skill candidate counts, `report` prints an acceptance signal derived
+from correlated fetches: `acceptance_rate`, `observed_mrr` (reciprocal rank
+of the first fetched candidate), and `top1_acceptance_rate`, each computed
+over resolves that returned at least one candidate. When a window has no
+correlated fetches, `report` marks the signal `unavailable` and states the
+uncorrelated fetch count instead of printing a misleading `0.000`. It also
+lists the top queries that returned candidates but received no correlated
+fetch, distinct from the existing top empty-shortlist list.
+
+`audit prune` deletes resolve and fetch rows older than `--older-than` (same
+window syntax as `--since`), or `audit.retention_days` from configuration
+(default 90; `0` disables pruning). `--dry-run` reports counts without
+writing. Non-interactive runs require `--yes`. The server also prunes
+automatically once at startup and at most once per 24 hours while running;
+manual pruning is for on-demand cleanup or a tighter window.
+
+`eval promote` reads correlated fetches since `--since`, deduplicates them by
+normalized query, and writes `{ query, split: "observed", relevant_skill_ids
+}` cases to `--target` (default an `eval-observed.json` file under
+`state_dir`; never the hand-curated `eval/queries.json` unless given
+explicitly). It never rewrites a case for a query already present in the
+target file; skipped counts are reported in the summary. Because promoted
+cases carry raw user queries, `eval promote` always prints a stderr warning.
+Both `--dry-run` and `--yes` behave as elsewhere in the CLI.
+
+---
+
 ## Administrative HTTP API (`/admin/v1/*`)
 
 The HTTP server has two separate surfaces:

package/docs/concepts.md

@@ -63,6 +63,16 @@ checkout over HTTP.
 
 ## Deployment topologies
 
+```mermaid
+flowchart TD
+    V[Git-backed vault source of truth]
+    V -->|client checkout| CLI[Skillmux CLI]
+    V -->|server checkout| SRV[Skillmux server]
+    CLI --> NM[Native management: filesystem links]
+    CLI --> LM[Local MCP: stdio]
+    SRV --> SM[Shared MCP: Streamable HTTP]
+```
+
 | Topology | Process location | Transport | Typical installation |
 | --- | --- | --- | --- |
 | Native management | Client machine | Filesystem links | Skillmux CLI |