@klhapp/skillmux 1.12.0 → 1.13.0

package/docs/sdd/cli-remote-target-parity/schema-bucket-b.yaml

@@ -0,0 +1,297 @@
+openapi: 3.1.0
+info:
+  title: Skillmux Admin API — Bucket B additions
+  version: "1.0.0"
+  description: >
+    New endpoints only. Covers docs/sdd/cli-remote-target-parity/spec-bucket-b.md
+    AC3, AC6, AC7, AC10. `report` (AC1-2) and `doctor` (AC9) reuse existing
+    endpoints (GET /stats, GET /admin/v1/capabilities, GET /admin/v1/config) —
+    no new schema needed for those. Error shape matches the existing
+    /admin/v1/config convention ({error: CODE, message: human text}), not a
+    new one.
+
+servers:
+  - url: /admin/v1
+
+security:
+  - bearerAuth: []
+
+paths:
+  /audit/prune:
+    post:
+      operationId: adminAuditPrune
+      summary: Prune audit/fetch/admin_audit rows older than a cutoff (AC3-5)
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AuditPruneRequest"
+      responses:
+        "200":
+          description: Prune executed or dry-run counted (AC3, AC4)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AuditPruneResult"
+        "400":
+          description: >
+            Non-dry-run prune requested without confirm: true (AC5). No rows
+            are deleted.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AdminError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+  /eval:
+    post:
+      operationId: adminEvalRun
+      summary: Run vault ranking evaluation against the server's own runtime (AC6)
+      requestBody:
+        required: false
+      responses:
+        "200":
+          description: Evaluation report, same shape as local `skillmux eval`
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvalReport"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+  /eval/promote:
+    post:
+      operationId: adminEvalPromote
+      summary: >
+        Return candidate promoted eval cases from the server's own audit db.
+        Read-only — writes no file server-side (AC7). The CLI applies dedup
+        and writes the local eval-case fixture file itself (AC8).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/EvalPromoteRequest"
+      responses:
+        "200":
+          description: >
+            Raw, undeduplicated candidates. Contains verbatim user query text
+            — same privacy note as local `eval promote`'s
+            "promoted eval cases contain raw user queries" warning.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvalPromoteResult"
+        "400":
+          description: Missing or invalid `since`
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AdminError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      description: Same shared admin token as /admin/v1/config (AC10).
+
+  responses:
+    Unauthorized:
+      description: Missing or empty bearer token
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/AdminError"
+    Forbidden:
+      description: Invalid bearer token
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/AdminError"
+
+  schemas:
+    AdminError:
+      type: object
+      additionalProperties: false
+      required: [error, message]
+      properties:
+        error:
+          type: string
+          description: Stable machine-readable code, e.g. "CONFIRMATION_REQUIRED".
+        message:
+          type: string
+          description: Human-readable explanation.
+
+    AuditPruneRequest:
+      type: object
+      additionalProperties: false
+      properties:
+        older_than:
+          type: string
+          description: >
+            Relative window (e.g. "30d") or absolute ISO-8601 date. Mirrors
+            CLI's --older-than. Omit to use the server's configured
+            audit.retention_days.
+        dry_run:
+          type: boolean
+          default: false
+          description: Mirrors CLI's --dry-run. When true, counts only, no deletion.
+        confirm:
+          type: boolean
+          default: false
+          description: >
+            Mirrors CLI's --yes. Required (true) for a non-dry-run prune to
+            execute (AC5) — an HTTP call has no interactive confirm, so the
+            server enforces this explicitly rather than trusting the caller.
+
+    AuditPruneResult:
+      type: object
+      additionalProperties: false
+      required: [audit_deleted, fetch_deleted, admin_audit_deleted, dry_run, cutoff]
+      properties:
+        audit_deleted:
+          type: integer
+          minimum: 0
+        fetch_deleted:
+          type: integer
+          minimum: 0
+        admin_audit_deleted:
+          type: integer
+          minimum: 0
+        dry_run:
+          type: boolean
+        cutoff:
+          type: ["string", "null"]
+          format: date-time
+
+    EvalMetrics:
+      type: object
+      additionalProperties: false
+      required: [recall_at_5, recall_at_10, mrr, ndcg_at_10]
+      properties:
+        recall_at_5:
+          type: number
+        recall_at_10:
+          type: number
+        mrr:
+          type: number
+        ndcg_at_10:
+          type: number
+
+    CandidateEvalDetail:
+      type: object
+      additionalProperties: false
+      required: [skill_id, lexical_rank, fused_rank]
+      properties:
+        skill_id:
+          type: string
+        lexical_rank:
+          type: ["integer", "null"]
+        fused_rank:
+          type: ["integer", "null"]
+        reranked_rank:
+          type: ["integer", "null"]
+
+    EvalCaseResult:
+      type: object
+      additionalProperties: false
+      required: [query, relevant_skill_ids, retrieval, latency_ms, recall_settings, candidates]
+      properties:
+        query:
+          type: string
+        relevant_skill_ids:
+          type: array
+          items:
+            type: string
+        retrieval:
+          type: string
+        degraded_from:
+          type: ["string", "null"]
+        degradation_reason:
+          type: ["string", "null"]
+        latency_ms:
+          type: number
+        recall_settings:
+          type: object
+          additionalProperties: false
+          required: [k_lexical, k_vector, k_rerank]
+          properties:
+            k_lexical:
+              type: integer
+            k_vector:
+              type: integer
+            k_rerank:
+              type: integer
+        candidates:
+          type: array
+          items:
+            $ref: "#/components/schemas/CandidateEvalDetail"
+
+    EvalReport:
+      type: object
+      additionalProperties: false
+      required: [queries, judged_queries, unjudged_queries, lexical, hybrid]
+      properties:
+        queries:
+          type: integer
+          minimum: 0
+        judged_queries:
+          type: integer
+          minimum: 0
+        unjudged_queries:
+          type: integer
+          minimum: 0
+        lexical:
+          $ref: "#/components/schemas/EvalMetrics"
+        hybrid:
+          $ref: "#/components/schemas/EvalMetrics"
+        cases:
+          type: array
+          items:
+            $ref: "#/components/schemas/EvalCaseResult"
+
+    EvalPromoteRequest:
+      type: object
+      additionalProperties: false
+      required: [since]
+      properties:
+        since:
+          type: string
+          description: Relative window (e.g. "7d") or absolute ISO-8601 date. Mirrors CLI's required --since.
+
+    EvalCase:
+      type: object
+      additionalProperties: false
+      required: [query, relevant_skill_ids]
+      properties:
+        query:
+          type: string
+        split:
+          type: string
+          description: Always "observed" for server-promoted candidates.
+        relevant_skill_ids:
+          type: array
+          items:
+            type: string
+
+    EvalPromoteResult:
+      type: object
+      additionalProperties: false
+      required: [candidates]
+      properties:
+        candidates:
+          type: array
+          items:
+            $ref: "#/components/schemas/EvalCase"
+          description: Raw, undeduplicated candidates. CLI dedups against its local file (AC8).

package/docs/sdd/cli-remote-target-parity/spec-bucket-b.md

@@ -0,0 +1,95 @@
+<!-- source: docs/sdd/cli-remote-target-parity/think.md -->
+<!-- plane_project: SMX -->
+<!-- plane_module: cli-remote-target-parity-bucket-b -->
+
+# Spec: CLI Remote Target Parity — Bucket B (Remote Admin Parity)
+
+Slice 3 of the feature. Slice 1 (Track 1, terminology fixes) shipped as
+PR #163. Slice 2 (Track 2 / Bucket A, reject-cleanly for native/vault-local
+commands) shipped as PR #165. This slice covers Track 2 / Bucket B: `report`,
+`audit prune`, `eval`/`eval promote`, and `doctor` genuinely reach a remote
+server's own admin state instead of `report` hand-rolling its own fetch and
+the rest silently running local-only.
+
+## Goal
+`report`, `audit prune`, `eval`/`eval promote`, and `doctor` genuinely reach
+a remote server's own admin state instead of `report` hand-rolling its own
+fetch and the rest silently running local-only.
+
+## Acceptance Criteria
+
+1. `report --context <remote>`/`--server <url>` fetches via
+   `TargetAdapter`/`RemoteAdapter`'s existing shared `fetchJson()` (reusing
+   the already-shipped `GET /stats` endpoint) instead of its own hand-rolled
+   `fetch()`/loopback-check/auth logic (`cli.ts` ~1613-1640). Output shape
+   (`StatsResponse`, text/JSON rendering) is unchanged — client-side refactor
+   only.
+2. If the resolved remote context's admin token env var is unset or empty,
+   `report` fails fast with a clear error before any network request —
+   replacing today's silent unauthenticated fetch.
+3. A new `POST /admin/v1/audit/prune` endpoint (admin-token authenticated)
+   backs new `TargetAdapter.auditPrune()`/`auditCount()` methods, returning
+   the same `{audit_deleted, fetch_deleted, admin_audit_deleted, dry_run,
+   cutoff}` shape as local `audit prune`.
+4. Remote `audit prune --dry-run` returns counts without mutating anything
+   server-side.
+5. Remote `audit prune` (non-dry-run) requires `--yes`; omitting it prunes
+   nothing and returns a clear error — mirroring the existing local
+   non-interactive requirement, since an interactive y/n confirm has no
+   meaning over a stateless HTTP call.
+6. A new `POST /admin/v1/eval` endpoint (admin-token authenticated) backs
+   `TargetAdapter.evalRun()`; the server runs `evalVault()` against its own
+   in-process runtime and returns the same `EvalReport` shape (lexical/hybrid
+   metrics) as local `eval`.
+7. A new `POST /admin/v1/eval/promote` endpoint (admin-token authenticated)
+   backs `TargetAdapter.evalPromote()`; the server computes candidate
+   promoted cases from its *own* audit db and returns them as JSON — it does
+   not write any file server-side.
+8. `eval promote --context <remote>` applies the existing local dedup
+   (`excludeExistingCases`) against the CLI's local `eval-observed.json`
+   before writing, exactly as local `eval promote` does today — the server
+   only supplies raw, undeduplicated candidates; the CLI remains the sole
+   writer of the local eval-case fixture file.
+9. `doctor --context <remote>` shows a remote view built from the existing
+   `getCapabilities()`/`configStatus()` — no new endpoint. Local `doctor`
+   (default, no `--context`/`--server`) is completely unchanged.
+10. All three new endpoints (`/admin/v1/audit/prune`, `/admin/v1/eval`,
+    `/admin/v1/eval/promote`) require the same admin bearer token as
+    `/admin/v1/config`; an unauthenticated or invalid-token request is
+    rejected (401/403) and performs no computation or mutation.
+11. Bucket A's already-shipped reject-cleanly behavior (14 local-only
+    commands) and `config`/`context`'s existing correct remote handling are
+    unaffected — regression only, no behavior change.
+12. `docs/cli.md` and `docs/concepts.md`'s HTTP-surfaces table document the
+    three new endpoints and the new remote behavior for `report`/
+    `audit prune`/`eval`/`eval promote`/`doctor`.
+
+## Scope
+- `report`'s remote path refactored onto `RemoteAdapter`'s shared fetch/auth
+  machinery (existing endpoint, no new route).
+- New `TargetAdapter` methods: `auditPrune()`, `auditCount()`, `evalRun()`,
+  `evalPromote()`.
+- New server endpoints: `POST /admin/v1/audit/prune`, `POST /admin/v1/eval`,
+  `POST /admin/v1/eval/promote`, all admin-token authenticated, all
+  synchronous (client blocks for the full result — no job/polling model).
+- `doctor`'s optional remote view.
+- Docs for all of the above.
+
+## Out of Scope
+- RBAC/SSO/access-control granularity beyond the single shared admin token —
+  reconfirmed per the 2026-08-29 decision.
+- Any async/job-polling execution model for `eval` — stays synchronous,
+  matching local behavior.
+- Any change to Bucket A's reject-cleanly commands or to `config`/`context`.
+- Version negotiation for older servers lacking these endpoints — no such
+  infra exists elsewhere in this codebase; not introduced here.
+- The `skillmux route "<query>" --context prod` MCP-preview command — still
+  no demand.
+
+## Tasks
+1. `report` refactor onto `RemoteAdapter`'s shared fetch (AC1-2).
+2. `audit prune` remote: new endpoint + adapter methods + `--yes` requirement
+   (AC3-5).
+3. `eval`/`eval promote` remote: new endpoints + adapter methods +
+   client-side dedup for promote (AC6-8).
+4. `doctor` remote view + docs (AC9-10, 12).

package/docs/sdd/cli-remote-target-parity/spec.md

@@ -0,0 +1,111 @@
+<!-- source: docs/sdd/cli-remote-target-parity/think.md -->
+<!-- plane_project: SMX -->
+<!-- plane_module: cli-remote-target-parity -->
+
+# Spec: CLI Remote Target Parity — Bucket A (Reject Cleanly)
+
+Slice 2 of the feature. Slice 1 (Track 1 — terminology fixes) shipped as
+PR #163, merged to main at `e942075`. This slice covers Track 2 / Bucket A
+only: native/vault-local commands reject a remote context cleanly. Bucket B
+(new remote admin capability for `report`/`audit prune`/`eval`) is a further
+slice.
+
+## Goal
+Every native/vault-local CLI command rejects a remote `--context`/`--server`
+with one clear, consistent error instead of silently running against local
+state.
+
+## Why this rejects (not routes)
+
+`--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, and the recurring confusion (including mid-design-session
+confusion this feature itself grew out of) comes from the name implying a
+broader "local mode vs. remote mode" switch than it actually is:
+
+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 (already documented, `concepts.md:101-104`).
+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`, and (in the next slice) `audit prune`/`eval`. This is the only
+   thing `--context`/`--server` actually selects.
+
+The commands in this slice 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`. Today the CLI accepts the flag and
+silently discards it, so a user can believe `skillmux install foo --context
+prod` acted on `prod` when it only mutated their own machine. This slice
+replaces that silent, misleading no-op with an explicit, correct refusal.
+
+## Acceptance Criteria
+
+1. When the resolved context is remote (`resolvedContext.type === "remote"`),
+   each of these commands is rejected before its handler runs, with a
+   non-zero exit: `install`, `update`, `outdated`, `sync`, `core`, `project`,
+   `target`, `local-vault`, `index`, `models`, `scan`, `init`, `serve`,
+   `skill which`.
+2. The rejection is produced by one shared, centralized guard — not
+   per-command duplicated logic — reusing the existing Docker-host-management
+   rejection's shape (`docs/cli.md`): exit code 2, JSON error code
+   `REMOTE_CONTEXT_UNSUPPORTED`, includes `rejected_command`.
+3. Human-mode error text follows one template naming the actual command:
+   `` `<command>` operates on the local vault only; --context/--server isn't
+   supported here ``.
+4. In `--json` mode, the rejection is a structured error envelope
+   (`formatJsonEnvelope`-style) with `code: "REMOTE_CONTEXT_UNSUPPORTED"` and
+   `rejected_command`, not free text only.
+5. When the resolved context is local (the default, no `--context`/
+   `--server`, or an explicit `--context local`), all Bucket A commands
+   behave exactly as before — zero regression, verified per-command.
+6. `context`, `config`, `report`, `audit`, `eval`, `eval promote`, `doctor`
+   are explicitly untouched by this slice — `context`/`config` already
+   handle remote correctly, the rest are deferred to the next slice (Bucket
+   B) and must continue behaving exactly as they do today, including their
+   current silent-local behavior for `audit`/`eval`/`doctor`.
+7. `docs/cli.md` documents the new rejection behavior for Bucket A commands
+   (same style as the existing Docker-host-management rejection section) and
+   states the three-axes distinction above, so the reason these commands
+   reject — rather than route — is written down, not just inferable from
+   code.
+
+## Scope
+- A single centralized guard (at CLI dispatch time, not scattered
+  per-handler) that rejects Bucket A commands when the resolved context is
+  remote.
+- The shared JSON error contract (code + `rejected_command`) and
+  human-readable message template.
+- Regression test coverage across all 14 Bucket A commands for both local
+  (unchanged) and remote (rejected) contexts.
+- Docs update, including the three-axes rationale.
+
+## Out of Scope
+- Bucket B (`report` refactor onto `TargetAdapter`, new `audit prune`/
+  `eval`/`eval promote` remote capability, new `/admin/v1` endpoints,
+  `doctor`'s optional remote view) — next slice.
+- RBAC/SSO/team accounts/multi-tenancy — deferred per the 2026-08-29
+  decision.
+- Full remote vault mutation — rejected architecturally in the think.md, not
+  revisited.
+- The `skillmux route "<query>" --context ...` MCP-preview command — no
+  demand, not bundled.
+- Renaming `skill which` — already addressed via clarification only, in
+  Track 1 (PR #163); this slice only adds it to the reject-cleanly list
+  under its current name.
+- Any change to how agents discover/load skills natively.
+
+## Tasks
+1. Add a single dispatch-level guard in `main()` (a `LOCAL_ONLY_COMMANDS` set
+   checked once, before the command switch invokes a handler).
+2. Wire the JSON error envelope (`code: "REMOTE_CONTEXT_UNSUPPORTED"`,
+   `rejected_command`) and human message template, mirroring the existing
+   Docker-rejection contract.
+3. Regression tests: each Bucket A command × {local context: unchanged,
+   remote context: rejected}.
+4. Update `docs/cli.md` with the rejection behavior and the three-axes
+   rationale.

package/docs/sdd/cli-remote-target-parity/think.md

@@ -0,0 +1,183 @@
+# CLI Remote Target Parity — Design Doc
+
+## Job to Be Done
+
+When an operator or agent points the Skillmux CLI at a target — a local
+install (stdio-colocated runtime) or a remote shared server (HTTP deployment)
+— every command should either honor that target correctly or fail with a
+clear, explicit reason. Today many commands silently ignore `--context`/
+`--server` and run against local state instead, so a user can believe they
+just acted on a remote server when they didn't.
+
+## Current State
+
+- `resolveTarget()`/`ResolvedTarget` (`{type:"local"}|{type:"remote"}`) and
+  `TargetAdapter` (`LocalAdapter`/`RemoteAdapter`) already exist
+  (`context.ts`, `adapters.ts`), decided and documented 2026-07-21.
+- Only `context`, `config`, and `report` actually consume the resolved
+  target. `report` reimplements its own ad hoc `fetch()`/auth-header/
+  loopback-check logic (`cli.ts` ~1557-1607) instead of going through
+  `RemoteAdapter` — a second, diverging implementation of the same pattern
+  `config` already built.
+- Every other command (`install`, `update`, `outdated`, `sync`, `index`,
+  `scan`, `eval`, `eval promote`, `doctor`, `skill which`, `audit prune`,
+  `core`, `project`, `target`, `local-vault`, `models`) ignores
+  `--context`/`--server` entirely — the flag parses successfully and is
+  silently discarded. There is no comment anywhere flagging this as a known
+  gap; a reader has to trace every call site to discover which commands
+  honor the resolved target.
+- The distinction that actually matters is not "local vs. remote
+  embeddings" or any inference-specific detail — it's whether the CLI
+  process has the runtime (vault, index, audit db, embeddings/reranker
+  clients) loaded in-process (stdio-colocated = `local` target) or is a thin
+  network client to a separate process that owns that runtime (HTTP =
+  `remote` target). This distinction is stated nowhere in code —
+  `ResolvedTarget` and `TargetAdapter` carry zero doc comments — and is
+  stated inconsistently across docs.
+- A read-only audit this session found a live, demonstrated defect from
+  that inconsistency: `docs/cli.md:13-15` correctly says a local *target*
+  doesn't imply local *inference*; `docs/cli.md:27-28` contradicts that,
+  twelve lines later, by calling `eval` "local embeddings" only;
+  `docs/concepts.md:167-170` gets it right again ("inference location and
+  deployment location use separate settings"). `src/cli.ts:677`'s error
+  message ("eval requires local embeddings") matches the wrong version.
+  This produced incorrect reasoning mid-design-session before it was
+  caught — not a hypothetical risk.
+- `skill which` (`cli.ts:719-736`) owns the CLI's most routing-suggestive
+  name but is pure local vault-checkout shadow resolution ("which root
+  wins for this skill id"). It has nothing to do with `resolve_skill`/
+  `fetch_skill` semantic routing. No CLI command currently exercises those
+  MCP tools — they're reachable only by agents over the MCP transport.
+- Native/vault-mutating commands (`install`, `update`, `sync`, `core`/
+  `project` pin, `target`) are already documented
+  (`concepts.md:101-104`) as host-only: "the server ... never
+  manage[s] host agent directories." Agents only read skill files from
+  local, product-specific directories (`~/.claude/skills`,
+  `~/.agents/skills`, etc.), so no remote server could make a pin take
+  effect there regardless of what the server-side implementation did.
+
+## Proposed Solution
+
+Two tracks. Track 1 is a prerequisite: the terminology defects found this
+session actively misled reasoning about this very design, so they get fixed
+before (or alongside) the capability work, not after.
+
+### Track 1 — Fix the terminology/contract defects
+
+- Reconcile the three-way doc contradiction: `docs/cli.md:27-28` should
+  match `docs/concepts.md:167-170` — inference location and deployment
+  location are independent settings.
+- Fix `src/cli.ts:677`'s error message to state the real requirement: "eval
+  requires an embeddings client (local model or a configured remote
+  endpoint)."
+- Add a doc comment to `ResolvedTarget` (`context.ts`) and `TargetAdapter`
+  (`adapters.ts`) stating the real distinction: `local` = the CLI has the
+  runtime in-process; `remote` = the CLI is a thin network client to a
+  separate process that owns the runtime.
+- Rename `ResolvedTarget`/`resolveTarget()` (`context.ts`) to
+  `ResolvedContext`/`resolveContext()`. The CLI-facing vocabulary for "which
+  server/instance am I talking to" is already settled as *context*
+  (`--context` flag, `SKILLMUX_CONTEXT` env var, `contexts.toml`, the
+  `skillmux context` subcommand — mirroring the kubectl/docker context
+  model). The internal type is the only place still using a different word,
+  and that word collides with the unrelated `skillmux target` subcommand
+  (which manages local agent skill directories, not server selection).
+  Renaming the internal type to match the CLI surface removes the collision
+  permanently: *context* always means "which server," *target* always means
+  "which local directory." Internal-only rename, no CLI-facing or
+  compatibility impact — safe to do outright, not gated on an open
+  question the way the `skill which` rename is.
+- Add a one-line comment at the flag-parsing site in `cli.ts`'s `main()`
+  noting which command handlers don't yet consume `resolvedTarget`, so the
+  gap is documented rather than discoverable only by tracing every call
+  site.
+- Rename or clarify `skill which` vs. semantic routing (e.g. `skill
+  locate`, or at minimum a `--help`/docs clarification) so the name stops
+  misleading readers — including future agents working in this repo.
+
+### Track 2 — Close the remote-target gap, by bucket
+
+- **Bucket A — Native/vault-local (reject remote cleanly).** `install`,
+  `update`, `outdated`, `sync`, `core`, `project`, `target`,
+  `local-vault`, `index`, `models`, `scan`, `init`, `serve`, `skill
+  which`/`locate`. When `resolvedTarget.type === "remote"`, these throw one
+  consistent, clear error ("`<command>` operates on the local vault only;
+  `--context`/`--server` isn't supported here") instead of silently running
+  locally. No new server capability needed.
+- **Bucket B — Server-instance admin state (extend to full remote
+  parity).** `config` (done, unchanged). `report` (refactor onto
+  `TargetAdapter` instead of its hand-rolled fetch; add `getStats(since)`
+  to the interface). `audit prune` (new: `auditPrune()`/`auditCount()` on
+  `TargetAdapter` + a new authenticated `/admin/v1/audit` endpoint).
+  `eval`/`eval promote` (new: `evalRun()`/`evalPromote()` on
+  `TargetAdapter` with server-side execution — `evalVault()` must run
+  wherever the runtime, including whatever backs its embeddings, actually
+  lives). `doctor` gains an optional remote view that delegates to the
+  existing `getCapabilities()`/`configStatus()` rather than inventing new
+  endpoints.
+- **Bucket C — `context`.** Stays as the mechanism, unchanged.
+
+## Scope
+
+- Fixing the terminology/doc/comment defects found in this session's audit
+  (Track 1).
+- Making every CLI command either properly honor `--context`/`--server` or
+  explicitly and clearly refuse it (Track 2, Bucket A).
+- Extending `TargetAdapter`/`RemoteAdapter` with new methods for stats,
+  audit prune, and eval so those genuinely reach a remote server's own
+  admin state (Track 2, Bucket B).
+- Unifying `report` onto the same adapter pattern as `config` instead of
+  its own hand-rolled fetch.
+
+## Out of Scope
+
+- RBAC, SSO, team accounts, multi-tenancy (deferred per the 2026-08-29
+  decision) — this stays a single shared admin-token model.
+- Full remote vault mutation (`install`/`update`/`sync` executing on a
+  remote server). Rejected on architectural grounds, not just risk: agents
+  only read skill files from local, product-specific directories, so a
+  remote server "installing" something accomplishes nothing for the agent
+  that needs it. Not revisited unless that architectural fact changes.
+- A new CLI command that acts as a genuine MCP client to preview
+  `resolve_skill`/`fetch_skill` routing (e.g. a hypothetical `skillmux
+  route "<query>" --context prod`). Floated during discussion; no existing
+  command needs it. Worth a separate future spec if there's real demand,
+  not bundled here.
+- Any change to how agents discover/load skills natively (the existing
+  core/project/sync mechanism is untouched).
+
+## Alternatives Considered
+
+- **Full remote parity ("Approach A").** New `/admin/v1` endpoints so
+  `install`/`update`/`sync` execute server-side. Rejected: contradicts the
+  already-documented "server never manages host agent directories"
+  promise, and wouldn't accomplish anything for the agent, which only
+  reads local files — an architectural dead end, not just a risk tradeoff.
+- **Leave everything as-is except `report`.** Rejected: leaves the
+  dangerous silent-ignore bug live on every other command, and leaves the
+  terminology defects that actively misled this session's own design
+  discussion.
+
+## Open Questions
+
+- Exact wording/UX for Bucket A's "operates locally only" refusal — one
+  shared helper vs. a per-command message; needs concrete examples during
+  `/sdd-spec`.
+- Whether the new `eval`/`audit` remote endpoints need any access-control
+  granularity beyond the existing single admin token (e.g. read-only vs.
+  mutate). Probably not, given RBAC stays deferred, but worth a sentence in
+  the spec confirming.
+- Whether `skill which` gets renamed (a breaking change for scripts) or
+  just clarified in place (alias the old name, deprecate over a release) —
+  a compatibility call for `/sdd-spec`.
+- Slicing: this doc covers Track 1 and Track 2 conceptually together, but
+  following this repo's own precedent (security-hardening-phase sliced
+  into 3 PRs), `/sdd-spec` should decide whether Track 1 (terminology
+  fixes) ships as its own fast slice before Track 2 (new capability), or
+  bundled with Bucket A's reject-cleanly behavior.
+
+## Next Step
+
+Run `/sdd-spec` to turn this into acceptance criteria — likely sliced per
+the last open question above (terminology-fix slice first, or bundled with
+Bucket A, then Bucket B's new remote admin endpoints as a further slice).