@klhapp/skillmux 1.9.3 → 1.10.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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.10.0](https://github.com/klhq/skillmux/compare/v1.9.3...v1.10.0) (2026-09-01)
+
+
+### Added
+
+* **cli:** reject remote context for local-only commands ([#165](https://github.com/klhq/skillmux/issues/165)) ([934bb18](https://github.com/klhq/skillmux/commit/934bb18bce2b86dca8ac44cd8431ebdb53d12024))
+* **cli:** remote admin parity for report, audit prune, eval, doctor ([#166](https://github.com/klhq/skillmux/issues/166)) ([615a396](https://github.com/klhq/skillmux/commit/615a396212d5c0e2df07712bf588c25e91e99773))
+
+
+### Changed
+
+* **cli:** align context terminology ([#163](https://github.com/klhq/skillmux/issues/163)) ([e942075](https://github.com/klhq/skillmux/commit/e94207584d10e16c17d6d2f5ca9c23bd8aa7846f))
+* **server:** consolidate redactedErrorLog into logger.ts ([#169](https://github.com/klhq/skillmux/issues/169)) ([f7f29e4](https://github.com/klhq/skillmux/commit/f7f29e4ed6ea516e243d47d677e7ede207e47937))
+* split db.ts, extract cli.ts commands, consolidate flag parsing ([#168](https://github.com/klhq/skillmux/issues/168)) ([28a798a](https://github.com/klhq/skillmux/commit/28a798abacfb830aff7a6510c6e892bb28009e5c))
+
 ## [1.9.3](https://github.com/klhq/skillmux/compare/v1.9.2...v1.9.3) (2026-08-31)
 
 

package/README.md

@@ -189,7 +189,7 @@ for all three setups.
 | Surface | User | Purpose | CLI required |
 | --- | --- | --- | --- |
 | `/mcp` | AI clients | Resolve and fetch skills | No |
-| `/admin/v1/*` | Operators | Inspect or update server configuration | Yes, when using named CLI contexts |
+| `/admin/v1/*` (and `GET /stats`) | Operators | Inspect/update config, stats, audit prune, evaluation, and remote diagnostics | Yes, when using named CLI contexts |
 
 MCP clients authenticate only to `/mcp` with the MCP bearer token. Operators
 use a separate administrative bearer token for `/admin/v1/*`; neither token

package/docs/README.md

@@ -34,7 +34,7 @@ to customize behavior; see [Configuration](configuration.md#machine-config-boots
 | Surface | User | Purpose | CLI required |
 | --- | --- | --- | --- |
 | `/mcp` | AI clients | Resolve and fetch skills | No |
-| `/admin/v1/*` | Operators | Inspect or update server configuration | Yes, when using named CLI contexts |
+| `/admin/v1/*` (and `GET /stats`) | Operators | Inspect/update config, stats, audit prune, evaluation, and remote diagnostics | Yes, when using named CLI contexts |
 
 The MCP and administrative surfaces use separate bearer tokens; possession of
 one does not grant access to the other. A named CLI context administers the

package/docs/cli.md

@@ -14,6 +14,9 @@ In this guide, **local target** means the filesystem and process selected by
 the built-in CLI context. It does not describe local inference. A local target
 can call remote inference endpoints.
 
+Run `skillmux --help` for the full command list, or `skillmux <command> --help`
+(`-h` also works) for one command's usage and flags.
+
 For task-oriented workflows, start with [Getting started](getting-started.md)
 or [Managing skills](skill-management.md).
 
@@ -25,13 +28,31 @@ CLI. Its `skillmux --help` surface is intentionally limited to `serve`,
 `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.
+evaluation, which needs an embeddings client 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`,
 `recommended_host_command`, and a deployment-guide URL. See [the container
 command contract](deployment.md#container-command-contract) for examples.
 
+## Local-only commands and remote context rejection
+
+Commands that operate directly on the local vault checkout reject `--context` and
+`--server` (or a configured remote default context) with exit code 2. These 14
+commands are local-only: `install`, `update`, `outdated`, `sync`, `core`,
+`project`, `target`, `local-vault`, `index`, `models`, `scan`, `init`, `serve`,
+and `skill which`.
+
+When one of these commands receives a remote context, it exits with code 2.
+Human-mode output reports:
+
+```
+error: `<command>` operates on the local vault only; --context/--server isn't supported here
+```
+
+In `--json` mode, the CLI emits a structured error envelope with `code: "REMOTE_CONTEXT_UNSUPPORTED"`
+and includes `rejected_command`.
+
 ## Global options and target resolution
 
 Every target-aware command resolves its execution target deterministically in this order:
@@ -52,6 +73,27 @@ Every target-aware command resolves its execution target deterministically in th
 | `--allow-insecure` | Allow plaintext HTTP admin requests to non-loopback addresses |
 | `--verbose` | Output diagnostic stack traces for errors |
 
+`--context`/`--server` selects which Skillmux admin instance a command talks to
+over `/admin/v1/*` — nothing more. That's one of three independent axes in this
+system:
+
+1. Which vault checkout backs Core/Project pinning — always a local Git checkout
+   on the machine running the CLI. `install`/`update`/`sync`/`core`/`project`/
+   `target`/`local-vault`/`index`/`models`/`scan`/`init`/`outdated`/`serve`/
+   `skill which` operate on it. There is no remote version of this — Git and the
+   deployment process move content between checkouts, not Skillmux's own
+   commands.
+2. Which MCP server an agent queries for Routed retrieval — the agent's own MCP
+   client configuration (local stdio vs. remote HTTP), entirely separate from
+   `skillmux context`.
+3. Which Skillmux instance the CLI's admin commands act on — `config`, `report`,
+   `audit prune`, `eval`/`eval promote`, and `doctor`. This is the only thing
+   `--context`/`--server` actually selects.
+
+The commands above belong entirely to axis 1. `--context` has no meaning for
+them — not "risky," a category error, the same way `--context prod` wouldn't
+mean anything on `ls`.
+
 ---
 
 ## Context management (`skillmux context`)
@@ -286,6 +328,11 @@ Show which root actually serves a skill_id, and every root it shadows:
 skillmux skill which csv-formatter
 ```
 
+> [!NOTE]
+> `skill which` performs local vault-checkout shadow resolution (which root
+> wins on the local filesystem) and is unrelated to semantic MCP skill routing
+> (`resolve_skill`/`fetch_skill`).
+
 ---
 
 ## Observability and evaluation (`skillmux report`, `audit`, `eval`)
@@ -352,10 +399,10 @@ The HTTP server has two separate surfaces:
 | Surface | User | Purpose | CLI required |
 | --- | --- | --- | --- |
 | `/mcp` | AI clients | Resolve and fetch skills | No |
-| `/admin/v1/*` | Operators | Inspect or update server configuration | Yes, when using named CLI contexts |
+| `/admin/v1/*` (and `GET /stats`) | Operators | Inspect/update config, stats, audit prune, evaluation, and remote diagnostics | Yes, when using named CLI contexts |
 
 The MCP bearer token applies only to `/mcp`. The administrative bearer token
-below applies only to `/admin/v1/*`; neither credential grants access to the
+below applies only to `/admin/v1/*` (and `GET /stats`); neither credential grants access to the
 other surface. Named contexts use the latter to administer the deployed server,
 not any remote client skill directory.
 
@@ -374,6 +421,30 @@ Requests require `Authorization: Bearer <token>` where `<token>` matches the env
 | `/admin/v1/capabilities` | `GET` | Advertises server features (`config_read`, `config_write`, `persistence`) |
 | `/admin/v1/config` | `GET` | Returns desired/effective config, sources, and `ETag` revision hash |
 | `/admin/v1/config` | `PATCH` | Applies dotted-key updates; requires matching `If-Match` header |
+| `/admin/v1/audit/prune` | `POST` | Prunes audit/fetch/admin_audit rows older than cutoff; requires `confirm: true` unless `dry_run: true` |
+| `/admin/v1/eval` | `POST` | Runs vault ranking evaluation server-side and returns `EvalReport` |
+| `/admin/v1/eval/promote` | `POST` | Returns candidate promoted eval cases from the server's audit database; requires `since` |
+
+### Remote command capabilities
+
+Named CLI contexts (`--context <name>` or `--server <url>`) support the following administrative and diagnostic operations:
+
+- `skillmux config` (`show`, `get`, `set`, `validate`, `diff`, `status`): inspect and modify remote server configuration over `/admin/v1/*`.
+- `skillmux report --since <window>`: fetches usage and retrieval metrics from the remote server's `GET /stats`.
+- `skillmux audit prune [--older-than <window>] [--dry-run] [--yes]`: prunes or dry-run counts audit records on the remote server via `POST /admin/v1/audit/prune`.
+- `skillmux eval`: executes ranking evaluation against the remote server's in-process runtime via `POST /admin/v1/eval`.
+- `skillmux eval promote --since <window>`: fetches promotable candidates from the remote server's audit db via `POST /admin/v1/eval/promote`, dedups against the local fixture file, and writes locally.
+- `skillmux doctor`: inspects remote server status, readiness, deployment runtime, and capabilities without requiring local vault access.
+
+---
+
+## Color
+
+Interactive terminal output uses a small amount of color: red for error
+messages, yellow for `warning:` lines, green/red for `doctor`'s `ok`/`fail`
+checks, and bold table headers. Color is automatic — it's on only when
+stdout is a TTY and off whenever `NO_COLOR` is set or output is piped or
+redirected. `--json` output never includes color codes.
 
 ---
 

package/docs/concepts.md

@@ -94,7 +94,7 @@ An HTTP server has two separate surfaces:
 | Surface | User | Purpose | CLI required |
 | --- | --- | --- | --- |
 | `/mcp` | AI clients | Resolve and fetch skills | No |
-| `/admin/v1/*` | Operators | Inspect or update server configuration | Yes, when using named CLI contexts |
+| `/admin/v1/*` (and `GET /stats`) | Operators | Inspect/update config, stats, audit prune, evaluation, and remote diagnostics | Yes, when using named CLI contexts |
 
 MCP authentication protects `/mcp`; administrative authentication protects
 `/admin/v1/*`. Their bearer tokens are distinct and do not grant access across

package/docs/configuration.md

@@ -184,7 +184,7 @@ The HTTP server provides separate MCP and administrative surfaces:
 | Surface | User | Purpose | CLI required |
 | --- | --- | --- | --- |
 | `/mcp` | AI clients | Resolve and fetch skills | No |
-| `/admin/v1/*` | Operators | Inspect or update server configuration | Yes, when using named CLI contexts |
+| `/admin/v1/*` (and `GET /stats`) | Operators | Inspect/update config, stats, audit prune, evaluation, and remote diagnostics | Yes, when using named CLI contexts |
 
 ```toml
 [server]

package/docs/deployment.md

@@ -180,7 +180,7 @@ The shared server exposes two distinct HTTP surfaces:
 | Surface | User | Purpose | CLI required |
 | --- | --- | --- | --- |
 | `/mcp` | AI clients | Resolve and fetch skills | No |
-| `/admin/v1/*` | Operators | Inspect or update server configuration | Yes, when using named CLI contexts |
+| `/admin/v1/*` (and `GET /stats`) | Operators | Inspect/update config, stats, audit prune, evaluation, and remote diagnostics | Yes, when using named CLI contexts |
 
 Configure and distribute separate bearer tokens. An MCP token authenticates an
 AI client to `/mcp` only; an administrative token authenticates an operator to
@@ -280,6 +280,9 @@ skillmux context add prod \
   --token-env SKILLMUX_PROD_ADMIN_TOKEN
 skillmux context use prod
 skillmux config status
+skillmux --context prod report --since 7d
+skillmux --context prod audit prune --dry-run
+skillmux --context prod doctor
 ```
 
 The context stores the token environment variable name. Export its value in
@@ -291,11 +294,12 @@ Enable the admin API and use a separate admin token in server configuration.
 Read [CLI reference](cli.md#administrative-http-api-adminv1) for routes and
 [Configuration](configuration.md#http-server) for reload behavior.
 
-Named contexts administer the deployed server configuration only. They do not
-install, pin, synchronize, or otherwise manage skill directories on remote
-client machines. Run those filesystem-management commands through Skillmux CLI
-on the machine that owns the directories. The full and slim server images read
-their mounted vault checkout and do not manage host agent directories.
+Named contexts administer the deployed server only — configuration, stats,
+audit prune, evaluation, and remote diagnostics. They do not install, pin,
+synchronize, or otherwise manage skill directories on remote client machines.
+Run those filesystem-management commands through Skillmux CLI on the machine
+that owns the directories. The full and slim server images read their mounted
+vault checkout and do not manage host agent directories.
 
 ## Persistent data and backups
 

package/docs/getting-started.md

@@ -261,7 +261,7 @@ The server keeps its two HTTP surfaces separate:
 | Surface | User | Purpose | CLI required |
 | --- | --- | --- | --- |
 | `/mcp` | AI clients | Resolve and fetch skills | No |
-| `/admin/v1/*` | Operators | Inspect or update server configuration | Yes, when using named CLI contexts |
+| `/admin/v1/*` (and `GET /stats`) | Operators | Inspect/update config, stats, audit prune, evaluation, and remote diagnostics | Yes, when using named CLI contexts |
 
 Configure separate MCP and administrative bearer tokens; one never grants
 access to the other. Named CLI contexts can administer this deployed server,

package/docs/skill-management.md

@@ -267,6 +267,12 @@ true` with a token, or it refuses to start. `--stats-port` is rejected
 alongside `--transport http`, since that transport already serves `/stats` on
 `--port`.
 
+`--context`/`--server` work the same way for `audit prune`, `eval`, `eval
+promote`, and `doctor` — each hits the matching `/admin/v1/*` route on the
+named deployment instead of the local vault and audit db. See [CLI
+reference](cli.md#administrative-http-api-adminv1) for the full remote
+command surface and route table.
+
 ## Target ownership and recovery
 
 `skillmux target remove <name> --yes` removes the manifest record and preserves

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klhapp/skillmux",
-  "version": "1.9.3",
+  "version": "1.10.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/adapters.ts

@@ -14,8 +14,11 @@ import {
   type ConfigStatusResponse,
   type SetConfigResult,
 } from "./config-service";
-import type { ResolvedTarget } from "./context";
+import type { ResolvedContext } from "./context";
 import type { Clients, Config } from "./types";
+import { getStats, parseSince, type StatsResponse } from "./stats";
+import { countPrunable, openAudit, pruneAuditBefore, type PruneResult } from "./db";
+import { buildPromotedCases, evalVault, queryPromotableFetches, type EvalCase, type EvalReport } from "./eval";
 
 export interface Capabilities {
   config_read: boolean;
@@ -31,6 +34,21 @@ export interface TargetAdapterOptions {
   clients?: Clients;
 }
 
+export interface AuditPruneOptions {
+  older_than?: string;
+  dry_run?: boolean;
+  confirm?: boolean;
+}
+
+export interface AuditPruneResult extends PruneResult {
+  dry_run: boolean;
+  cutoff: string | null;
+}
+
+/**
+ * Target adapter: `local` = this CLI process has the Skillmux runtime (vault, index,
+ * audit db, embeddings/reranker clients) in-process; `remote` = thin network client to an external process.
+ */
 export interface TargetAdapter {
   getCapabilities(): Promise<Capabilities>;
   getConfigShow(): Promise<{ effective: Config; sources: Record<string, string>; active_revision: string }>;
@@ -39,6 +57,11 @@ export interface TargetAdapter {
   configDiff(): Promise<{ diff: Record<string, { prior: unknown; resulting: unknown }> }>;
   configSet(key: string, rawValStr: string, opts?: { dryRun?: boolean }): Promise<SetConfigResult>;
   configStatus(): Promise<ConfigStatusResponse>;
+  getStats(since: string): Promise<StatsResponse>;
+  auditPrune(opts?: AuditPruneOptions): Promise<AuditPruneResult>;
+  auditCount(older_than?: string): Promise<AuditPruneResult>;
+  evalRun(): Promise<EvalReport>;
+  evalPromote(since: string): Promise<EvalCase[]>;
 }
 
 export function isLoopbackHost(hostname: string): boolean {
@@ -116,6 +139,75 @@ export class LocalAdapter implements TargetAdapter {
   async configStatus(): Promise<ConfigStatusResponse> {
     return getLocalConfigStatus(this.configPath);
   }
+
+  async getStats(since: string): Promise<StatsResponse> {
+    const config = await loadConfig(this.configPath);
+    const stateDir = expandHome(config.state_dir);
+    const db = openAudit(stateDir);
+    try {
+      return getStats(db, since);
+    } finally {
+      db.close();
+    }
+  }
+
+  async auditPrune(opts?: AuditPruneOptions): Promise<AuditPruneResult> {
+    const config = await loadConfig(this.configPath);
+    const stateDir = expandHome(config.state_dir);
+    const olderThan = opts?.older_than;
+    const dryRun = opts?.dry_run ?? false;
+
+    let cutoff: Date;
+    if (olderThan) {
+      cutoff = parseSince(olderThan);
+    } else {
+      const retentionDays = config.audit?.retention_days ?? 90;
+      if (retentionDays <= 0) {
+        return {
+          audit_deleted: 0,
+          fetch_deleted: 0,
+          admin_audit_deleted: 0,
+          dry_run: dryRun,
+          cutoff: null,
+        };
+      }
+      cutoff = new Date(Date.now() - retentionDays * 86_400_000);
+    }
+    const cutoffIso = cutoff.toISOString();
+
+    const db = openAudit(stateDir);
+    try {
+      if (dryRun) {
+        const counts = countPrunable(db, cutoffIso);
+        return { ...counts, dry_run: true, cutoff: cutoffIso };
+      }
+      const counts = pruneAuditBefore(db, cutoffIso);
+      return { ...counts, dry_run: false, cutoff: cutoffIso };
+    } finally {
+      db.close();
+    }
+  }
+
+  async auditCount(older_than?: string): Promise<AuditPruneResult> {
+    return this.auditPrune({ older_than, dry_run: true });
+  }
+
+  async evalRun(): Promise<EvalReport> {
+    return evalVault();
+  }
+
+  async evalPromote(since: string): Promise<EvalCase[]> {
+    const sinceDate = parseSince(since);
+    const sinceIso = sinceDate.toISOString();
+    const config = await loadConfig(this.configPath);
+    const stateDir = expandHome(config.state_dir);
+    const db = openAudit(stateDir);
+    try {
+      return buildPromotedCases(queryPromotableFetches(db, sinceIso));
+    } finally {
+      db.close();
+    }
+  }
 }
 
 export class RemoteAdapter implements TargetAdapter {
@@ -281,9 +373,63 @@ export class RemoteAdapter implements TargetAdapter {
     }
     return data.runtime;
   }
+
+  async getStats(since: string): Promise<StatsResponse> {
+    const searchParams = new URLSearchParams({ since });
+    const { status, data } = await this.fetchJson(`/stats?${searchParams.toString()}`);
+    if (status !== 200) {
+      throw new Error(`Remote stats fetch failed (${status}): ${typeof data === "object" ? data?.message || data?.error || JSON.stringify(data) : data}`);
+    }
+    return data as StatsResponse;
+  }
+
+  async auditPrune(opts?: AuditPruneOptions): Promise<AuditPruneResult> {
+    const { status, data } = await this.fetchJson("/admin/v1/audit/prune", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        ...(opts?.older_than ? { older_than: opts.older_than } : {}),
+        ...(opts?.dry_run !== undefined ? { dry_run: opts.dry_run } : {}),
+        ...(opts?.confirm !== undefined ? { confirm: opts.confirm } : {}),
+      }),
+    });
+    if (status !== 200) {
+      const message = typeof data === "object" ? data?.message || data?.error || JSON.stringify(data) : data;
+      throw new Error(`Remote audit prune failed (${status}): ${message}`);
+    }
+    return data as AuditPruneResult;
+  }
+
+  async auditCount(older_than?: string): Promise<AuditPruneResult> {
+    return this.auditPrune({ older_than, dry_run: true });
+  }
+
+  async evalRun(): Promise<EvalReport> {
+    const { status, data } = await this.fetchJson("/admin/v1/eval", {
+      method: "POST",
+    });
+    if (status !== 200) {
+      const message = typeof data === "object" ? data?.message || data?.error || JSON.stringify(data) : data;
+      throw new Error(`Remote eval failed (${status}): ${message}`);
+    }
+    return data as EvalReport;
+  }
+
+  async evalPromote(since: string): Promise<EvalCase[]> {
+    const { status, data } = await this.fetchJson("/admin/v1/eval/promote", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ since }),
+    });
+    if (status !== 200) {
+      const message = typeof data === "object" ? data?.message || data?.error || JSON.stringify(data) : data;
+      throw new Error(`Remote eval promote failed (${status}): ${message}`);
+    }
+    return data.candidates as EvalCase[];
+  }
 }
 
-export function createTargetAdapter(target: ResolvedTarget, opts?: TargetAdapterOptions): TargetAdapter {
+export function createTargetAdapter(target: ResolvedContext, opts?: TargetAdapterOptions): TargetAdapter {
   if (target.type === "local") {
     return new LocalAdapter(opts);
   } else {