@klhapp/skillmux 1.7.1 → 1.9.0

package/docs/configuration.md

@@ -203,9 +203,9 @@ enabled = false
 token_env = "SKILLMUX_ADMIN_TOKEN"
 ```
 
-Defaults are loopback-only (`hostname = "127.0.0.1"`) with CORS deny-by-default (`allowed_origins = []`) — a zero-config `skillmux serve --transport http` is not reachable from the network or from a browser tab on another origin. Docker sets `hostname` to `0.0.0.0` automatically (`RUNNING_IN_DOCKER=true`) since port-mapping needs the container to accept connections on all interfaces.
+Defaults are loopback-only (`hostname = "127.0.0.1"`) with CORS deny-by-default (`allowed_origins = []`), so a zero-config `skillmux serve --transport http` is not reachable from the network or from a browser tab on another origin. Docker sets `hostname` to `0.0.0.0` automatically (`RUNNING_IN_DOCKER=true`) since port-mapping needs the container to accept connections on all interfaces.
 
-Before exposing HTTP beyond localhost, set `hostname` to a reachable interface, `auth_enabled = true` with a token, and populate `allowed_origins` with the specific origins that need browser access. `rate_limit.trust_proxy` should stay `false` unless a trusted reverse proxy sets `X-Forwarded-For` — it's otherwise a client-controlled, spoofable header and trusting it defeats per-client rate limiting.
+Before exposing HTTP beyond localhost, set `hostname` to a reachable interface, `auth_enabled = true` with a token, and populate `allowed_origins` with the specific origins that need browser access. `rate_limit.trust_proxy` should stay `false` unless a trusted reverse proxy sets `X-Forwarded-For`: it's otherwise a client-controlled, spoofable header, and trusting it defeats per-client rate limiting.
 
 `server.auth_token_env` names the MCP token for AI clients calling `/mcp`.
 `server.admin.token_env` names a distinct administrative token for operators
@@ -242,13 +242,13 @@ skills = ["pdf-extractor"]           # must not overlap [core]
 [targets.claude-code]
 dir = "/Users/you/.claude/skills"
 host = "workhorse"                    # optional; init adds the current hostname
-project_groups = ["repo1"]           # which [project.*] groups materialize into this target — [] means none
+project_groups = ["repo1"]           # which [project.*] groups materialize into this target; [] means none
 ```
 
-- `[core].skills` — symlinked into every `[targets.*]` dir on `sync`. Capped at 25 skills; `sync` fails if a listed skill id isn't actually in the vault.
-- `[project.<group>].skills` — symlinked only into `<path>/<relative path from $HOME to the target dir>`, for each `paths` entry, and only for targets whose `project_groups` names that group. `paths` entries must resolve under `$HOME` (that's how the pin path is derived). A skill can't appear in both `[core]` and the same `[project.*]` group.
-- `[project.<group>].paths` can list the same project's checkout on more than one machine (e.g. `["/home/alice/code/repo1", "/Users/alice/code/repo1"]`) — `sync` silently skips any entry that doesn't exist on the machine it's running on (see below), so one shared manifest can span machines with different checkout locations without needing per-machine manifests.
-- `[targets.<name>]` — one entry per adopted surface. `skillmux init --target <name> --yes` writes these and scopes newly added targets to the current hostname. Hand-editing is fine as long as `sync` is still allowed to own the directory (see below). An optional `host` limits the target to an exact machine-hostname match; omit it for a global, backward-compatible target. A host mismatch is reported and skipped before any target filesystem operation. `project_groups` is an explicit list, not a boolean — a target only receives the specific groups it names, never every group in the manifest.
+- `[core].skills`: symlinked into every `[targets.*]` dir on `sync`. Capped at 25 skills; `sync` fails if a listed skill id isn't actually in the vault.
+- `[project.<group>].skills`: symlinked only into `<path>/<relative path from $HOME to the target dir>`, for each `paths` entry, and only for targets whose `project_groups` names that group. `paths` entries must resolve under `$HOME` (that's how the pin path is derived). A skill can't appear in both `[core]` and the same `[project.*]` group.
+- `[project.<group>].paths` can list the same project's checkout on more than one machine (e.g. `["/home/alice/code/repo1", "/Users/alice/code/repo1"]`). `sync` silently skips any entry that doesn't exist on the machine it's running on (see below), so one shared manifest can span machines with different checkout locations without needing per-machine manifests.
+- `[targets.<name>]`: one entry per adopted surface. `skillmux init --target <name> --yes` writes these and scopes newly added targets to the current hostname. Hand-editing is fine as long as `sync` is still allowed to own the directory (see below). An optional `host` limits the target to an exact machine-hostname match; omit it for a global, backward-compatible target. A host mismatch is reported and skipped before any target filesystem operation. `project_groups` is an explicit list, not a boolean: a target only receives the specific groups it names, never every group in the manifest.
 
 **Pin/unpin without hand-editing.** `skillmux core pin`/`unpin` mutate `[core]` for you, and `skillmux project pin`/`unpin` mutate `[project.*]`, validating with the same rules `sync` enforces (skill must resolve from `vault_path`, no duplicate pins, `[core]` stays under the 25-skill cap) before writing anything:
 
@@ -261,16 +261,16 @@ skillmux core unpin csv-formatter pdf-extractor --yes                    # unpin
 skillmux project unpin repo1 pdf-extractor --yes                         # remove from a group (group stays, even if empty)
 ```
 
-Both commands accept one or more `skill_id` arguments per call; all of them are validated and applied against a single in-memory manifest before anything is written, so if any one of them is already pinned elsewhere (or, for unpin, not currently pinned), the whole call fails and the manifest file is left untouched — no partial pins. To pin into a `[project.<group>]` tier that doesn't exist yet, create it first with `skillmux project add-path <group> <path> --yes`. Hand-editing `skillmux.toml` directly is still fully supported; these commands are a convenience layer over the same file, not a replacement for it.
+Both commands accept one or more `skill_id` arguments per call; all of them are validated and applied against a single in-memory manifest before anything is written, so if any one of them is already pinned elsewhere (or, for unpin, not currently pinned), the whole call fails and the manifest file is left untouched: no partial pins. To pin into a `[project.<group>]` tier that doesn't exist yet, create it first with `skillmux project add-path <group> <path> --yes`. Hand-editing `skillmux.toml` directly is still fully supported; these commands are a convenience layer over the same file, not a replacement for it.
 
-> **Breaking change:** `skillmux manifest pin`/`unpin` is removed. `[core]` pinning is now `skillmux core pin`/`unpin`; `[project.*]` pinning was already available as `skillmux project pin`/`unpin` and is now the only way to do it — there's no more `--path`-based inline group creation from a pin call, use `project add-path` to create the group first.
+> **Breaking change:** `skillmux manifest pin`/`unpin` is removed. `[core]` pinning is now `skillmux core pin`/`unpin`; `[project.*]` pinning was already available as `skillmux project pin`/`unpin` and is now the only way to do it. There's no more `--path`-based inline group creation from a pin call; use `project add-path` to create the group first.
 >
 > **Breaking change:** `[targets.<name>].project` (a boolean) has been replaced by `project_groups` (an array of `[project.*]` names). A manifest still using the old field fails to parse with an error pointing at the new one. To migrate, replace `project = true` with `project_groups = [...]` listing every group that target previously received (previously *all* groups, unconditionally); replace `project = false` with `project_groups = []`.
 >
-> **Breaking change:** `[project.<group>].repos` has been renamed to `paths` — it was never required to be a git repository, just a local directory, and the old name collided in meaning with `skillmux install <repo>`'s unrelated git-source `repo` concept. A manifest still using `repos` fails to parse with an error pointing at `paths`; migrate by renaming the key (values are unchanged).
+> **Breaking change:** `[project.<group>].repos` has been renamed to `paths`. It was never required to be a git repository, just a local directory, and the old name collided in meaning with `skillmux install <repo>`'s unrelated git-source `repo` concept. A manifest still using `repos` fails to parse with an error pointing at `paths`; migrate by renaming the key (values are unchanged).
 
 Every `[core]`/`[project.*]` skill_id must resolve from the configured
-`vault_path` checkout — pinning a skill that only exists in a
+`vault_path` checkout. Pinning a skill that only exists in a
 `local_vault_paths` entry (see below) fails `sync` with a distinct error, since
 the manifest is meant to be portable across machines and a machine-local
 override wouldn't exist elsewhere. `doctor` validates the manifest as part of
@@ -286,7 +286,7 @@ Skillmux created. Sync removes only those tracked entries, preserves unrelated
 content, and rejects a desired skill that collides with an unmanaged entry
 before changing anything.
 
-`sync` refuses to touch a directory that exists but has no marker — run
+`sync` refuses to touch a directory that exists but has no marker; run
 `skillmux init --target <name> --yes` first, which either creates the
 directory fresh or adopts an existing one in place (contents untouched).
 `sync --restore-monolith` likewise refuses a `local_vault` marker or any
@@ -302,34 +302,34 @@ cannot be inferred.
 
 ### Local vault overlays
 
-`local_vault_paths` (in `config.toml`, alongside `vault_path`) lets one machine layer override-only skills on top of the shared vault — a skill being authored locally, a machine-specific script, or a patched copy of an upstream skill — without touching `vault_path` itself:
+`local_vault_paths` (in `config.toml`, alongside `vault_path`) lets one machine layer override-only skills on top of the shared vault (a skill being authored locally, a machine-specific script, or a patched copy of an upstream skill) without touching `vault_path` itself:
 
 ```toml
 vault_path = "~/skills"                 # configured checkout; owns skillmux.toml and the sync git hook
 local_vault_paths = ["~/skills-local"]   # optional, default []: override-only, checked first
 ```
 
-- **Resolution order**: for any given `skill_id`, `local_vault_paths` entries are checked first, in array order; `vault_path` is the fallback. This applies everywhere a skill's on-disk location matters — indexing, `resolve_skill`/`fetch_skill` delivery, and `sync`'s symlink target.
+- **Resolution order**: for any given `skill_id`, `local_vault_paths` entries are checked first, in array order; `vault_path` is the fallback. This applies everywhere a skill's on-disk location matters: indexing, `resolve_skill`/`fetch_skill` delivery, and `sync`'s symlink target.
 - **`vault_path` keeps its exact existing meaning.** `skillmux.toml` and the `sync --install-hook` git hook only ever live in `vault_path`; `skillmux doctor` warns if it finds a stray manifest inside a `local_vault_paths` entry instead.
-- **`[core]`/`[project.*]` pins must resolve from `vault_path`.** Since the manifest is meant to be portable, `sync`/`doctor` reject a pin backed only by a `local_vault_paths` entry — see the manifest section above.
+- **`[core]`/`[project.*]` pins must resolve from `vault_path`.** Since the manifest is meant to be portable, `sync`/`doctor` reject a pin backed only by a `local_vault_paths` entry; see the manifest section above.
 - **Not yet covered**: `startVaultWatcher`'s live filesystem watch still only watches `vault_path`; a change inside a `local_vault_paths` entry is picked up lazily (on the next `resolve_skill`/`fetch_skill`/`sync` call, via the same mtime staleness check `vault_path` already uses), not instantly.
 
-**Visibility.** A `skill_id` present in more than one root is silently resolved via the precedence above with no output during normal use — two commands make that resolution visible on demand:
+**Visibility.** A `skill_id` present in more than one root is silently resolved via the precedence above with no output during normal use. Two commands make that resolution visible on demand:
 
-- `skillmux skill which <skill_id>` — prints which root actually serves that skill, and names every root it shadows:
+- `skillmux skill which <skill_id>`: prints which root actually serves that skill, and names every root it shadows:
   ```
   $ skillmux skill which my-skill
   my-skill: serving from /home/user/skills-local
     shadows: /home/user/skills
   ```
   Exits non-zero with `<skill_id>: not found in vault_path or local_vault_paths` if no root has it.
-- `skillmux doctor` reports every shadowed skill_id as an informational check (`shadowed:<skill_id>`, always `ok`) alongside its existing vault/manifest/embedding checks — so a scan of `doctor` output surfaces every override in one place, not just the one you thought to ask about.
+- `skillmux doctor` reports every shadowed skill_id as an informational check (`shadowed:<skill_id>`, always `ok`) alongside its existing vault/manifest/embedding checks, so a scan of `doctor` output surfaces every override in one place, not just the one you thought to ask about.
 
-**Discoverability.** A `local_vault_paths` entry is otherwise just a bare directory — nothing on disk says it belongs to skillmux or which `vault_path` it overlays. `skillmux local-vault init <path>` writes a `.skillmux` marker recording that relationship:
+**Discoverability.** A `local_vault_paths` entry is otherwise just a bare directory. Nothing on disk says it belongs to skillmux or which `vault_path` it overlays. `skillmux local-vault init <path>` writes a `.skillmux` marker recording that relationship:
 
 ```sh
 skillmux local-vault init ~/skills-local
 # wrote /home/user/skills-local/.skillmux (role: local_vault, vault_path: /home/user/skills)
 ```
 
-`<path>` must already be one of the configured `local_vault_paths` entries and must exist on disk — the command only ever writes the marker, it never adds the path to `config.toml` for you. `skillmux doctor` reports each entry's marker status (`local_vault_marker:<path>`): `ok: false` if no marker exists yet (with the exact `local-vault init` command to fix it), or if the marker's recorded `vault_path` no longer matches the one currently configured (drift — e.g. after copying the directory to a machine with a different `vault_path`).
+`<path>` must already be one of the configured `local_vault_paths` entries and must exist on disk; the command only ever writes the marker, it never adds the path to `config.toml` for you. `skillmux doctor` reports each entry's marker status (`local_vault_marker:<path>`): `ok: false` if no marker exists yet (with the exact `local-vault init` command to fix it), or if the marker's recorded `vault_path` no longer matches the one currently configured (drift: e.g. after copying the directory to a machine with a different `vault_path`).

package/docs/deployment.md

@@ -248,7 +248,7 @@ The HTTP server provides:
 
 The Docker health check calls `/health/ready`.
 
-`GET /stats` returns JSON aggregated from audit rows over a query window (using `?since=`, defaulting to 24 hours). The response contains `since`, `until`, `total_requests`, `empty_shortlist_count`, `empty_shortlist_rate`, `retrieval_totals` (counts for `exact`, `reranked`, `hybrid`, and `lexical`), `degraded_count`, `average_latency_ms`, per-skill candidate counts in `skills` (`skill_id`, `candidate_count`), and `top_empty_shortlist_queries` (`query`, `count`). See [Managing skills](skill-management.md#use-routing-data-to-tune-tiers) for using these statistics to tune delivery tiers.
+`GET /stats` returns JSON aggregated from audit rows over a query window (using `?since=`, defaulting to 24 hours). The response contains `since`, `until`, `total_requests`, `empty_shortlist_count`, `empty_shortlist_rate`, `retrieval_totals` (counts for `exact`, `reranked`, `hybrid`, and `lexical`), `degraded_count`, `average_latency_ms`, per-skill candidate counts in `skills` (`skill_id`, `candidate_count`), `top_empty_shortlist_queries` (`query`, `count`), an `acceptance` signal derived from fetches correlated to their resolve (`acceptance_rate`, `observed_mrr`, `top1_acceptance_rate`, `accepted_count`, `resolves_with_candidates`, and `uncorrelated_fetch_count`, or `available: false` with just the uncorrelated count when a window has no correlated fetches), and `top_unused_shortlist_queries` (`query`, `count`) for queries that returned candidates but received no correlated fetch. See [Managing skills](skill-management.md#use-routing-data-to-tune-tiers) for using these statistics to tune delivery tiers.
 
 Prometheus metrics cover request totals, resolve latency histograms, errors,
 rate-limit rejections, degraded retrieval totals by stage and reason, readiness
@@ -289,13 +289,26 @@ their mounted vault checkout and do not manage host agent directories.
 
 ## Persistent data and backups
 
-Persist `state_dir` to retain the index and audit log.
-Skill content remains in the server's vault checkout and should use its own
-backup or Git workflow.
-
-Treat the state database as sensitive because audit rows can contain raw user
+Persist `state_dir` to retain both state files it holds: `index.sqlite3`
+(retrieval index and vector matrix) and `audit.sqlite3` (resolve and fetch
+audit rows). Skill content remains in the server's vault checkout and should
+use its own backup or Git workflow.
+
+The two files are independent and can be backed up on different schedules.
+Copying or backing up `index.sqlite3` alone never carries raw user queries;
+only `audit.sqlite3` does. `audit.sqlite3` is created with WAL journaling and
+incremental auto-vacuum, so `skillmux audit prune` reclaims space without
+taking a lock on `index.sqlite3`. On first startup after an upgrade from a
+version that kept audit rows inside `index.sqlite3`, Skillmux migrates them
+into `audit.sqlite3` once, transactionally; the migration is idempotent, so
+it is safe to leave running unattended.
+
+Treat `audit.sqlite3` as sensitive because its rows can contain raw user
 queries. Stop the process or use SQLite-safe backup tooling before copying a
-live database.
+live database. `audit.retention_days` (default 90; `0` disables pruning) ages
+out old rows automatically at startup and at most once per 24 hours while the
+server runs; see [CLI reference](cli.md#observability-and-evaluation-skillmux-report-audit-eval)
+for the on-demand `skillmux audit prune` command.
 
 ## Native pins with shared retrieval
 

package/docs/getting-started.md

@@ -3,6 +3,17 @@
 Skillmux supports three setup paths. Pick the result you want before choosing
 an installation.
 
+```mermaid
+flowchart LR
+    Q{What do you need?}
+    Q -->|Managed links in client skill directories| A[Manage native skills]
+    Q -->|Local stdio MCP| B[Add local MCP retrieval]
+    Q -->|Streamable HTTP MCP for several clients| C[Run a shared MCP service]
+    A --> A1[Skillmux CLI]
+    B --> B1[Skillmux CLI]
+    C --> C1[Skillmux server, full image]
+```
+
 | Goal | Skill delivery | Recommended installation |
 | --- | --- | --- |
 | [Manage native skills](#manage-native-skills) | Managed links in client skill directories | Skillmux CLI |

package/docs/mcp-routing.md

@@ -79,6 +79,7 @@ Skillmux returns a ranked candidates response:
 
 ```json
 {
+  "request_id": "3fae2b8e-6c2d-4b1a-9d7a-2b6c5b6a9e10",
   "retrieval": "reranked",
   "candidates": [
     {
@@ -91,6 +92,7 @@ Skillmux returns a ranked candidates response:
 }
 ```
 
+- `request_id`: a unique id minted for this resolve. Pass it back to `fetch_skill` to correlate a fetch outcome with this resolve and the fetched skill's rank in this shortlist.
 - `retrieval`: the effective retrieval capability (`reranked`, `hybrid`, or `lexical`).
 - `candidates`: zero through effective `top_k` candidates ordered by descending score with contiguous 1-based ranks.
 - If reranking or embedding fails, degradation metadata (`degraded_from`, `degradation_reason`) is included.
@@ -101,13 +103,18 @@ Input:
 
 ```json
 {
-  "skill_id": "csv-formatter"
+  "skill_id": "csv-formatter",
+  "request_id": "3fae2b8e-6c2d-4b1a-9d7a-2b6c5b6a9e10"
 }
 ```
 
 The response contains the current `SKILL.md` body as text content.
 `structuredContent` contains the skill ID, title, content SHA-256, and
-supporting-file paths. Fetch does not depend on an earlier resolve call.
+supporting-file paths. `request_id` is optional. When it names a resolve that
+minted it, the recorded fetch outcome links to that resolve and its rank in
+the shortlist. An absent, unknown, or malformed `request_id` still succeeds
+and records an uncorrelated fetch — delivery never fails because telemetry
+could not correlate. Fetch does not depend on an earlier resolve call.
 
 The complete wire contract lives in [schema.json](schema.json).
 
@@ -117,11 +124,26 @@ Give the calling client these rules:
 
 1. Call `resolve_skill` when a task may benefit from a specialized workflow.
 2. Review the returned ranked candidates shortlist.
-3. If a relevant candidate exists, call `fetch_skill` with its `skill_id` to retrieve complete instructions.
+3. If a relevant candidate exists, call `fetch_skill` with its `skill_id` to retrieve complete instructions, passing back the resolve's `request_id` when the client retains it.
 4. If no candidate is relevant (or `candidates` is empty), continue under your normal workflow.
 
+Passing `request_id` is optional and never required for delivery, but it is
+what lets Skillmux measure whether a returned shortlist was actually used.
+
 ## Retrieval pipeline
 
+```mermaid
+flowchart LR
+    Q[Query] --> L[Lexical: FTS5 + BM25]
+    Q --> E[Embeddings: local or remote]
+    L --> F[Reciprocal-rank fusion]
+    E --> F
+    F --> RR[Optional reranker]
+    RR --> K[Ranked candidates: top_k]
+    F -. reranker unavailable .-> K
+    Q -. embedding unavailable: lexical only .-> K
+```
+
 Skillmux builds candidates in stages:
 
 1. SQLite FTS5 ranks lexical matches with BM25.
@@ -173,12 +195,24 @@ access.
 
 Each resolve request records:
 
-- timestamp and query;
+- timestamp, `request_id`, and query;
 - retrieval capability;
 - degradation metadata (`degraded_from`, `degradation_reason`) when degraded;
 - candidates with scores;
 - latency in milliseconds.
 
-Skillmux stores audit rows in the SQLite database under `state_dir`. Use
-`skillmux report` to summarize activity. Treat raw queries as private user
-data when backing up or sharing the database.
+Each fetch request records:
+
+- timestamp and `skill_id`;
+- the `request_id` supplied by the caller, or null when absent, unknown, or malformed;
+- the originating resolve's audit row id, or null when the fetch is uncorrelated;
+- `rank_at_resolve`: the fetched skill's rank in that resolve's shortlist, or null when the fetch is uncorrelated or the skill was absent from that shortlist.
+
+Skillmux stores audit rows in `audit.sqlite3` under `state_dir`, a file
+separate from the retrieval index. Use `skillmux report` to summarize
+activity, `skillmux audit prune` to reclaim space under
+`audit.retention_days` (default 90 days), and `skillmux eval promote` to turn
+correlated fetches into eval cases — see [CLI
+reference](cli.md#observability-and-evaluation-skillmux-report-audit-eval)
+for all three. Treat raw queries as private user data when backing up or
+sharing the database.

package/docs/schema.json

@@ -55,6 +55,18 @@
       "required": ["rank", "skill_id", "description", "score"],
       "additionalProperties": false
     },
+    "RequestId": {
+      "type": "string",
+      "description": "Per-resolve correlation id minted by resolve_skill. Lowercase UUIDv4.",
+      "format": "uuid",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "InboundRequestId": {
+      "type": "string",
+      "description": "request_id as supplied by the caller to fetch_skill. Deliberately not pattern-validated: an unknown or malformed value must still succeed and record an uncorrelated fetch (AC7); correlation validity is decided by the server, not the schema.",
+      "minLength": 1,
+      "maxLength": 128
+    },
     "ResolveSkillInput": {
       "type": "object",
       "properties": {
@@ -76,6 +88,7 @@
       "type": "object",
       "description": "Ranked candidates response from resolve_skill.",
       "properties": {
+        "request_id": { "$ref": "#/$defs/RequestId" },
         "retrieval": { "enum": ["exact", "reranked", "hybrid", "lexical"] },
         "degraded_from": { "enum": ["reranked", "hybrid"] },
         "degradation_reason": { "$ref": "#/$defs/DegradationReason" },
@@ -85,13 +98,14 @@
           "description": "Shortlist of candidates in descending score order with contiguous 1-based ranks."
         }
       },
-      "required": ["retrieval", "candidates"],
+      "required": ["request_id", "retrieval", "candidates"],
       "additionalProperties": false
     },
     "FetchSkillInput": {
       "type": "object",
       "properties": {
-        "skill_id": { "$ref": "#/$defs/SkillId" }
+        "skill_id": { "$ref": "#/$defs/SkillId" },
+        "request_id": { "$ref": "#/$defs/InboundRequestId" }
       },
       "required": ["skill_id"],
       "additionalProperties": false
@@ -146,7 +160,7 @@
         },
         "state_dir": {
           "type": "string",
-          "description": "All router writes are confined here (AC9): index SQLite (incl. audit log), vector matrix.",
+          "description": "All router writes are confined here (AC9): index SQLite (index.sqlite3), audit SQLite (audit.sqlite3), vector matrix.",
           "default": "~/.local/state/skillmux"
         },
         "recall": {
@@ -179,11 +193,24 @@
           "additionalProperties": false
         },
         "inference": { "$ref": "#/$defs/InferenceConfig" },
-        "server": { "$ref": "#/$defs/ServerConfig" }
+        "server": { "$ref": "#/$defs/ServerConfig" },
+        "audit": { "$ref": "#/$defs/AuditConfig" }
       },
       "required": ["vault_path", "state_dir", "recall", "output", "inference"],
       "additionalProperties": false
     },
+    "AuditConfig": {
+      "type": "object",
+      "properties": {
+        "retention_days": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 90,
+          "description": "Age in days beyond which audit and fetch rows are pruned. 0 disables pruning and retains rows indefinitely."
+        }
+      },
+      "additionalProperties": false
+    },
     "InferenceConfig": {
       "oneOf": [
         {

package/docs/skill-management.md

@@ -55,6 +55,38 @@ With no path, `scan` checks the configured vault. `--json` wraps the result in
 the standard CLI automation envelope, while `--format json` selects the
 scanner's raw JSON rendering.
 
+## Check and pull upstream updates
+
+Every skill `install` places in the vault gets a `.skillmux-origin` sidecar
+recording the source repo, resolved commit, and a content hash. Check which
+installed skills have moved upstream:
+
+```sh
+skillmux outdated
+skillmux outdated --json
+```
+
+Skills you authored by hand, or installed before this sidecar existed, carry
+no `.skillmux-origin` and are silently omitted — `outdated` only reports on
+skills it can trace back to a source. A repo that has become unreachable is
+reported per-skill as `check_failed` with a reason; it does not stop the rest
+of the check.
+
+Pull an update for one skill, or every outdated skill at once:
+
+```sh
+skillmux update csv-formatter --dry-run
+skillmux update csv-formatter --yes
+skillmux update --yes
+```
+
+`--dry-run` reports the old and new commit and whether content actually
+changed, without writing anything. A real update re-runs the same scan
+`install` does (`--fail-on` applies the same way) and refuses to overwrite a
+skill whose on-disk content has drifted from what was last installed —
+someone may have hand-edited it. Pass `--force` to overwrite anyway. Like
+`audit prune`, a non-interactive or `--json` run needs `--yes`.
+
 ## Plan client delivery
 
 Use product names for common clients:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klhapp/skillmux",
-  "version": "1.7.1",
+  "version": "1.9.0",
   "description": "Skill management and retrieval for AI agents: sync native skills across clients and route the long tail over MCP",
   "type": "module",
   "private": false,

package/src/audit.ts

@@ -5,6 +5,7 @@ export function buildAuditRow(row: AuditRow): AuditRow {
   const built: AuditRow = {
     id: row.id,
     ts: row.ts,
+    request_id: row.request_id,
     query: row.query,
     retrieval: row.retrieval,
     candidates: row.candidates.map((c) => ({ skill_id: c.skill_id, score: c.score })),

package/src/cli.ts

@@ -12,7 +12,7 @@ import {
   migrateLegacyPaths,
   resolveConfigPath,
 } from "./config";
-import { openIndex } from "./db";
+import { openAudit } from "./db";
 import { diagnose } from "./doctor";
 import { getEffectiveConfig } from "./config-service";
 import { evalVault } from "./eval";
@@ -42,10 +42,14 @@ import {
   cloneToTemp,
   deriveRepoName,
   installIntoVault,
+  resolveCloneCommit,
   resolveRepoSource,
   resolveSkillDir,
   validateSkillCandidate,
 } from "./install";
+import { runOutdated } from "./commands/outdated";
+import { runUpdate } from "./commands/update";
+import { hashSkillContent, writeSkillOrigin } from "./provenance";
 import {
   parseManifest,
   resolveManifestPath,
@@ -106,7 +110,9 @@ import {
   suggestCorrection,
 } from "./output";
 import { generateCompletions, type ShellType } from "./completions";
+import { runAudit } from "./commands/audit";
 import { handleConfigCommand } from "./commands/config";
+import { runEvalPromote } from "./commands/eval";
 import { runCore } from "./commands/core";
 import { configuredTargetForSurface, runProject } from "./commands/project";
 import { confirmAction, confirmIfNeeded } from "./commands/shared";
@@ -124,8 +130,11 @@ const KNOWN_COMMANDS = [
   "target",
   "core",
   "report",
+  "audit",
   "scan",
   "install",
+  "outdated",
+  "update",
   "eval",
   "doctor",
   "models",
@@ -139,18 +148,23 @@ function isDockerHostManagementCommand(command: string, subCommand: string): boo
       "init",
       "sync",
       "install",
+      "outdated",
+      "update",
       "project",
       "target",
       "core",
       "local-vault",
       "models",
       "context",
-      "eval",
     ].includes(command)
   ) {
     return true;
   }
 
+  // eval promote only touches the mounted state_dir, unlike bare `eval`
+  // (vault ranking evaluation), which needs local embeddings and the vault.
+  if (command === "eval" && subCommand !== "promote") return true;
+
   return command === "config" && ["init", "set"].includes(subCommand);
 }
 
@@ -322,14 +336,29 @@ async function main() {
       case "report":
         await runReport(rawArgv.slice(1), { isJson });
         break;
+      case "audit":
+        await runAudit(subCommand, commandArgs, { isJson, dryRun: isDryRun });
+        break;
       case "scan":
         await runScan(rawArgv.slice(1), { isJson });
         break;
       case "install":
         await runInstall(rawArgv.slice(1), { isJson });
         break;
+      case "outdated":
+        await runOutdated(rawArgv.slice(1), { isJson });
+        break;
+      case "update":
+        await runUpdate(rawArgv.slice(1), { isJson });
+        break;
       case "eval":
-        await runEval({ isJson });
+        if (subCommand === "promote") {
+          await runEvalPromote(commandArgs, { isJson, dryRun: isDryRun });
+        } else if (subCommand === "") {
+          await runEval({ isJson });
+        } else {
+          throw new Error(`usage: skillmux eval [promote --since <window> [--target <path>] [--dry-run] [--yes] [--json]]`);
+        }
         break;
       case "doctor":
         await runDoctor({ isJson });
@@ -359,7 +388,7 @@ async function main() {
         const suggestion = suggestCorrection(command, KNOWN_COMMANDS);
         const msg = suggestion
           ? `Unknown command "${command}". Did you mean "${suggestion}"?`
-          : `usage: skillmux <serve|index|sync|init|project|target|core pin/unpin|report|scan|install|eval|doctor|skill which|local-vault init|config show|models download>`;
+          : `usage: skillmux <serve|index|sync|init|project|target|core pin/unpin|report|audit prune|scan|install|outdated|update|eval|doctor|skill which|local-vault init|config show|models download>`;
         throw new Error(msg);
       }
     }
@@ -507,7 +536,7 @@ Default:
   serve --transport http
 
 Supported commands:
-  serve, index, doctor, report, scan, skill which
+  serve, index, doctor, report, audit prune, eval promote, scan, skill which
   config show|get|validate|diff|status
 
 Native skill management:
@@ -540,9 +569,16 @@ Init clients:
 Init targets:
   agent-skills, claude-code, codex, custom
 
+Operations:
+  skillmux report [--server <url> | --db <path>] --since <window> [--json]
+  skillmux audit prune [--older-than <window>] [--dry-run] [--yes] [--json]
+  skillmux eval promote --since <window> [--target <path>] [--dry-run] [--yes] [--json]
+  skillmux outdated [--allow-local-source] [--json]
+  skillmux update [skill-id] [--yes] [--dry-run] [--force] [--allow-local-source] [--fail-on low|medium|high] [--json]
+
 Commands:
-  serve, index, sync, init, project, target, core, report, scan, install, eval, doctor, skill,
-  local-vault, config, models, context, completions`);
+  serve, index, sync, init, project, target, core, report, audit, scan, install, outdated, update,
+  eval, doctor, skill, local-vault, config, models, context, completions`);
 }
 
 // ---------------------------------------------------------------------------
@@ -807,6 +843,11 @@ async function runSync(args: string[]): Promise<void> {
     console.log(
       `${targetName}: +${result.added.length} -${result.removed.length}${suffix}`,
     );
+    if (result.skipped.length > 0) {
+      console.log(
+        `  warning: refused to sync ${result.skipped.join(", ")} — skill directory contains a symlink`,
+      );
+    }
 
     if (target.project_groups.length > 0) {
       const allGroups = manifest.project ?? {};
@@ -821,6 +862,11 @@ async function runSync(args: string[]): Promise<void> {
         console.log(
           `  ${projectResult.group} -> ${projectResult.pinDir}: +${projectResult.added.length} -${projectResult.removed.length}${suffix}`,
         );
+        if (projectResult.skipped.length > 0) {
+          console.log(
+            `    warning: refused to sync ${projectResult.skipped.join(", ")} — skill directory contains a symlink`,
+          );
+        }
       }
     }
   }
@@ -1453,7 +1499,7 @@ async function runReport(
 
   const db = dbPath
     ? new Database(dbPath, { readonly: true })
-    : openIndex(expandHome((await loadConfig()).state_dir));
+    : openAudit(expandHome((await loadConfig()).state_dir));
   const stats = getStats(db, since);
   emitSuccess({ isJson: options.isJson }, stats, () =>
     console.log(renderStatsText(stats)),
@@ -1592,12 +1638,20 @@ async function runInstall(
       return;
     }
 
+    const commit = resolveCloneCommit(cloneDir);
     const targetDir = installIntoVault(
       vaultPath,
       resolved.skillId,
       resolved.dir,
       force,
     );
+    writeSkillOrigin(targetDir, {
+      source_url: source.url,
+      skill_path: source.skillPath,
+      commit,
+      installed_at: new Date().toISOString(),
+      content_hash: hashSkillContent(targetDir),
+    });
     emitSuccess(
       { isJson: options.isJson },
       { skill_id: resolved.skillId, installed_at: targetDir },