@klhapp/skillmux 1.11.2 → 1.13.0

package/docs/sdd/skill-provenance-update/schema.json

@@ -0,0 +1,193 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://klh.app/schemas/skillmux/skill-provenance-update.json",
+  "title": "Skillmux — skill provenance + update contract",
+  "description": "Contract delta for docs/sdd/skill-provenance-update/spec.md. Each $def is either a NEW type or a full replacement for a def of the same name in docs/schema.json. At implementation time these merge into docs/schema.json $defs; nothing here is a second source of truth. Merge targets are noted per def in $comment.",
+  "$defs": {
+    "GitCommitSha": {
+      "$comment": "NEW. AC1, AC3, AC5, AC9. The resolved commit SHA at HEAD of a shallow clone (git rev-parse) or of git ls-remote output. Git's default object format, SHA-1: 40 lowercase hex chars.",
+      "type": "string",
+      "description": "Git commit SHA (SHA-1, 40 lowercase hex chars) identifying a resolved repository state.",
+      "pattern": "^[0-9a-f]{40}$"
+    },
+
+    "SkillContentHash": {
+      "$comment": "NEW. AC1, AC7, AC9. Distinct def from router-core.json#/$defs/Sha256Hex: that hashes exact SKILL.md bytes only, this hashes the whole installed skill directory (SKILL.md + supporting files) per src/provenance.ts hashSkillContent(dir), for drift detection.",
+      "type": "string",
+      "description": "Lowercase hex SHA-256 over the installed skill's full content (SKILL.md plus every file returned by listSupportingFiles), used to detect local drift and remote content changes.",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+
+    "RelativeSkillPath": {
+      "$comment": "NEW. AC1, AC6. Subpath within the source repo that resolveSkillDir used to locate the skill, e.g. 'skills/my-skill'. Absent when the skill lived at the repo root.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "pattern": "^(?!/)(?!.*\\.\\.).+$"
+    },
+
+    "SkillOrigin": {
+      "$comment": "NEW. AC1, AC2. On-disk shape of the .skillmux-origin sidecar, written by install.ts/runInstall (fresh install and --force reinstall) and rewritten by update.ts on successful update. Mirrors the .skillmux marker's schema_version convention in sync.ts but is a distinct file and type, never confused with SkillmuxMarker (AC2).",
+      "type": "object",
+      "properties": {
+        "schema_version": { "const": 1 },
+        "source_url": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Git URL the skill was fetched from (resolveRepoSource output), e.g. https://github.com/owner/repo.git."
+        },
+        "skill_path": { "$ref": "#/$defs/RelativeSkillPath" },
+        "commit": { "$ref": "#/$defs/GitCommitSha" },
+        "installed_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "AC1: ISO-8601 timestamp of the install or update that produced this sidecar."
+        },
+        "content_hash": { "$ref": "#/$defs/SkillContentHash" }
+      },
+      "required": ["schema_version", "source_url", "commit", "installed_at", "content_hash"],
+      "additionalProperties": false
+    },
+
+    "ScanFinding": {
+      "$comment": "NEW to docs/schema.json. Transcribes ValidationResult.findings at src/install.ts:52-78 (RuleMatch at src/scan.ts:7-11, extended with skill_id and file). Reused by update.ts's skipped_scan_fail results (AC8).",
+      "type": "object",
+      "properties": {
+        "skill_id": { "$ref": "https://klh.app/schemas/skillmux/router-core.json#/$defs/SkillId" },
+        "file": { "type": "string", "minLength": 1, "description": "File the finding was reported against, relative to the skill directory (e.g. 'SKILL.md')." },
+        "rule_id": { "type": "string", "minLength": 1 },
+        "severity": { "enum": ["low", "medium", "high"] },
+        "message": { "type": "string", "minLength": 1 },
+        "line": { "type": "integer", "minimum": 1 }
+      },
+      "required": ["skill_id", "file", "rule_id", "severity", "message"],
+      "additionalProperties": false
+    },
+
+    "OutdatedCheckStatus": {
+      "$comment": "NEW. AC3, AC4.",
+      "type": "string",
+      "enum": ["up_to_date", "outdated", "check_failed"]
+    },
+
+    "OutdatedCheckResult": {
+      "$comment": "NEW. AC3, AC4. One row of `skillmux outdated` output, for every vault skill carrying a .skillmux-origin sidecar. Skills with no sidecar never produce a row (AC3).",
+      "type": "object",
+      "properties": {
+        "skill_id": { "$ref": "https://klh.app/schemas/skillmux/router-core.json#/$defs/SkillId" },
+        "source_url": { "type": "string", "minLength": 1 },
+        "recorded_commit": { "$ref": "#/$defs/GitCommitSha" },
+        "remote_commit": {
+          "oneOf": [{ "$ref": "#/$defs/GitCommitSha" }, { "type": "null" }],
+          "description": "Null only when status is check_failed."
+        },
+        "status": { "$ref": "#/$defs/OutdatedCheckStatus" },
+        "reason": {
+          "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }],
+          "description": "AC4: human-readable failure reason (unreachable repo, deleted branch/ref). Null unless status is check_failed."
+        }
+      },
+      "required": ["skill_id", "source_url", "recorded_commit", "remote_commit", "status", "reason"],
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "$comment": "AC4 invariant: remote_commit is present iff the check did not fail; reason is present iff it did.",
+          "if": { "properties": { "status": { "const": "check_failed" } }, "required": ["status"] },
+          "then": {
+            "properties": {
+              "remote_commit": { "type": "null" },
+              "reason": { "type": "string", "minLength": 1 }
+            }
+          },
+          "else": {
+            "properties": {
+              "remote_commit": { "$ref": "#/$defs/GitCommitSha" },
+              "reason": { "type": "null" }
+            }
+          }
+        }
+      ]
+    },
+
+    "OutdatedOutput": {
+      "$comment": "NEW. AC3, AC4. JSON output of `skillmux outdated --json`. checks_failed drives the process exit code alongside any CLI-level error.",
+      "type": "object",
+      "description": "JSON output of `skillmux outdated --json`.",
+      "properties": {
+        "skills": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/OutdatedCheckResult" }
+        },
+        "checks_failed": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "AC4: count of skills.status === 'check_failed'."
+        }
+      },
+      "required": ["skills", "checks_failed"],
+      "additionalProperties": false
+    },
+
+    "UpdateSkillStatus": {
+      "$comment": "NEW. AC7, AC8, AC9, AC10, AC11. would_update/would_skip_* appear only under --dry-run; updated/skipped_* appear only on a real run. up_to_date appears in both, for an explicitly named skill-id whose remote HEAD already matches its recorded commit.",
+      "type": "string",
+      "enum": [
+        "updated",
+        "would_update",
+        "up_to_date",
+        "skipped_drift",
+        "would_skip_drift",
+        "skipped_scan_failed",
+        "would_skip_scan_failed"
+      ]
+    },
+
+    "UpdateSkillResult": {
+      "$comment": "NEW. AC6, AC7, AC8, AC9, AC10, AC11. One row of `skillmux update` output, per candidate skill (the named skill-id, or every outdated sidecar-carrying skill in batch mode).",
+      "type": "object",
+      "properties": {
+        "skill_id": { "$ref": "https://klh.app/schemas/skillmux/router-core.json#/$defs/SkillId" },
+        "old_commit": { "$ref": "#/$defs/GitCommitSha" },
+        "new_commit": { "$ref": "#/$defs/GitCommitSha" },
+        "content_changed": {
+          "type": "boolean",
+          "description": "AC9: whether the newly fetched skill's content_hash differs from the currently installed one, independent of whether old_commit === new_commit."
+        },
+        "status": { "$ref": "#/$defs/UpdateSkillStatus" },
+        "findings": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/ScanFinding" },
+          "description": "AC8: present (possibly empty) only when status is skipped_scan_failed or would_skip_scan_failed."
+        }
+      },
+      "required": ["skill_id", "old_commit", "new_commit", "content_changed", "status"],
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "$comment": "findings is only meaningful, and only required, on a scan-gate outcome (AC8).",
+          "if": {
+            "properties": { "status": { "enum": ["skipped_scan_failed", "would_skip_scan_failed"] } },
+            "required": ["status"]
+          },
+          "then": { "required": ["findings"] },
+          "else": { "properties": { "findings": false } }
+        }
+      ]
+    },
+
+    "UpdateOutput": {
+      "$comment": "NEW. AC9, AC10, AC11. JSON output of `skillmux update [skill-id] --json`, for both dry-run and real invocations, and for both single-skill and batch runs. An empty skills array is the AC11 no-op case ('nothing matched') and is a success, not an error.",
+      "type": "object",
+      "description": "JSON output of `skillmux update`.",
+      "properties": {
+        "dry_run": { "type": "boolean" },
+        "skills": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/UpdateSkillResult" }
+        }
+      },
+      "required": ["dry_run", "skills"],
+      "additionalProperties": false
+    }
+  }
+}

package/docs/sdd/skill-provenance-update/spec.md

@@ -0,0 +1,134 @@
+# Skill provenance + update
+
+<!-- plane_project: SMX -->
+<!-- plane_module: skill-provenance-update -->
+
+## Goal
+
+Give skills installed via `skillmux install <repo>` a recorded origin, and let
+users check whether that origin has moved on and pull the update — closing
+the gap where an installed skill's provenance is forgotten the moment
+`install` finishes.
+
+## Acceptance Criteria
+
+1. `skillmux install <repo>[/path]` writes a provenance sidecar inside the
+   installed skill's directory: schema version, source repo URL, subpath (if
+   any), the resolved commit SHA from the temp clone, install timestamp
+   (ISO-8601), and a content hash of the installed skill (SKILL.md +
+   supporting files) for drift detection. `--force` reinstall overwrites the
+   sidecar the same way a fresh install does.
+2. The sidecar uses its own filename (`.skillmux-origin`), distinct from the
+   `.skillmux` sync marker — it is never mistaken for a `SkillmuxMarker`, is
+   excluded from `scan.ts` content scanning and from `listSupportingFiles`,
+   and is skipped by `sync.ts`'s managed-entries bookkeeping.
+3. `skillmux outdated [--json]` lists every installed skill carrying a
+   provenance sidecar, checks the source repo's current default-branch HEAD
+   via `git ls-remote` (no full clone), and reports each as up-to-date or
+   outdated by comparing recorded vs. remote commit SHA. Skills with no
+   sidecar are omitted entirely — not listed, not flagged as errors.
+4. A per-skill remote check failure (unreachable repo, deleted branch/ref)
+   does not abort the whole command: `outdated` reports that skill's check as
+   failed with a reason, keeps checking the rest, and reflects any failures in
+   the exit code and JSON output (`checks_failed` count) while still
+   returning results for skills that succeeded.
+5. `skillmux update [skill-id] [--yes] [--dry-run] [--force] [--fail-on
+   low|medium|high] [--json]`:
+   - With a `skill-id`, updates that one skill.
+   - Without one, updates every skill carrying a provenance sidecar whose
+     remote HEAD differs from its recorded commit (i.e., every skill
+     `outdated` would report as outdated).
+6. For each candidate skill, `update` re-fetches from the sidecar's recorded
+   repo URL + subpath into a temp clone, exactly as `install` does
+   (`resolveRepoSource` inputs are already known from the sidecar, so no repo
+   argument is needed).
+7. Before touching any skill's files, `update` hashes that skill's current
+   on-disk content and compares it to the hash recorded at last
+   install/update. A mismatch (local drift — the user hand-edited the
+   installed copy) causes that skill to be refused and reported as skipped,
+   unless `--force` is also passed.
+8. `update` runs `validateSkillCandidate` (the same scan `install` runs)
+   against each newly fetched skill and applies `--fail-on` gating per skill,
+   before any write for that skill. A skill that fails the scan gate is
+   skipped and reported, and does not block other skills in a batch.
+9. `update --dry-run` reports, per candidate skill, the old SHA, the new SHA,
+   and whether content actually differs — without writing anything. This
+   works for both single-skill and batch invocations.
+10. A real (non-dry-run) update requires `--yes` in non-interactive/`--json`
+    mode (`confirmIfNeeded`, matching `audit prune`), or an interactive prompt
+    otherwise. The prompt/confirmation covers the full resolved set of skills
+    that will actually be written (after drift and scan filtering) shown up
+    front, matching `init`'s "show every write before confirmation" pattern.
+    On confirmation, each skill's directory content is overwritten and its
+    sidecar rewritten with the new commit SHA, new content hash, and new
+    timestamp.
+11. Running `update <skill-id>` against a skill with no provenance sidecar
+    fails clearly (e.g. "no origin recorded — was this skill installed via
+    `skillmux install`?"). Running bare `update` with no matching skills
+    (nothing outdated, or nothing with provenance) succeeds as a no-op and
+    says so.
+12. Neither `outdated` nor `update` touches `skillmux.toml`-pinned
+    core/project skills or native sync targets (the `.skillmux` /
+    `SkillmuxMarker` machinery in `sync.ts`) — scope is limited to
+    vault-local, install-from-git skill directories.
+13. `docs/cli.md` documents `outdated` and `update`; `docs/schema.json`
+    documents the `.skillmux-origin` sidecar shape, following how the
+    `.skillmux` marker is already documented there.
+
+## Scope
+
+- **`src/provenance.ts`** (new): `.skillmux-origin` filename constant, a
+  `SkillOrigin` interface (`schema_version`, `source_url`, `skill_path?`,
+  `commit`, `installed_at`, `content_hash`), read/write/validate helpers
+  mirroring `sync.ts`'s marker pattern, and `hashSkillContent(dir)` reusing
+  `listSupportingFiles`.
+- **`src/install.ts`**: add `remoteHeadCommit(url, ref?)` via `git
+  ls-remote`; capture the resolved commit SHA from the existing temp clone in
+  the `cloneToTemp`/`resolveSkillDir` flow.
+- **`src/cli.ts` `runInstall`**: write the provenance sidecar right after
+  `installIntoVault` succeeds (both fresh install and `--force` reinstall).
+- **`src/commands/outdated.ts`** (new): scans the vault for skills with
+  sidecars, checks each against its remote, following `commands/audit.ts`'s
+  shape (arg parsing loop, `emitSuccess`, `--json`).
+- **`src/commands/update.ts`** (new): `runUpdate`, reusing
+  `resolveRepoSource`/`cloneToTemp`/`resolveSkillDir`/`validateSkillCandidate`/`installIntoVault`/`confirmIfNeeded`/`emitSuccess`,
+  handling both single-skill and batch resolution.
+- Wire `outdated` and `update` into `src/cli.ts`'s command dispatcher and
+  usage/help strings.
+- `docs/cli.md` and `docs/schema.json` updates.
+- Tests under `tests/`: provenance read/write/hash round-trip, `outdated`
+  remote-check logic (mockable git call) including partial-failure handling,
+  `update` drift/force/dry-run/fail-on/yes-gating for both single and batch
+  paths.
+
+## Out of Scope
+
+- Skill versioning/semver, changelogs, or any lifecycle concept beyond a git
+  commit SHA.
+- Dependency graphs between skills.
+- Any registry, marketplace, or skill-discovery UI/index.
+- Automatic or scheduled updates — `update` is always a manually invoked,
+  consent-gated command; no cron, no update-on-server-start.
+- Deprecation warnings authored by skill maintainers, or any metadata
+  contract for upstream skills to signal their own lifecycle state.
+- `skillmux.toml`-pinned core/project skills and the `sync.ts`
+  target/local_vault marker machinery.
+- Line-level diffing of SKILL.md content — `update --dry-run` reports
+  SHA/hash-level change status, not a textual diff.
+- Resolving non-default branches/tags for update — `update` re-resolves the
+  repo's default branch HEAD the same way `install` does today; pinning a
+  skill to a specific ref is future work.
+
+## Tasks
+
+1. Provenance module: sidecar type, read/write/validate, `hashSkillContent`,
+   `remoteHeadCommit`.
+2. Wire sidecar write into `install`/`--force` reinstall path.
+3. Exempt `.skillmux-origin` from `scan.ts` and `listSupportingFiles`.
+4. `skillmux outdated`: resolve sidecars, batch remote checks, partial-failure
+   handling, `--json`.
+5. `skillmux update`: single + batch resolution, drift check, scan gate,
+   dry-run reporting, consent gate, sidecar rewrite on success.
+6. CLI wiring (dispatcher, usage strings, help text).
+7. Docs pass: `docs/cli.md`, `docs/schema.json`.
+8. Tests for all of the above.

package/docs/sdd/supply-chain-hardening/review.md

@@ -0,0 +1,50 @@
+# Review: Supply-Chain Hardening
+
+**Method:** goose's `sdd-review` fan-out hit its 24h token rate limit (not transient — `token limit exceeded (279006/250000, resets every 24h)`), so this review ran manually per the skill's fallback path: five focus passes over `git diff main...HEAD` (327 lines, 9 files), plus the real test suite.
+
+**Diff:** `feat/supply-chain-hardening` vs `main`, 4 commits (efd5e76, d35033b, b64981c, 2ec41b2).
+
+## Compliance
+
+| Criterion | Status | Notes |
+|---|---|---|
+| AC1: `allowed_hosts` unset leaves install/update unrestricted | ✅ Done | `tests/install.test.ts` + two CLI-level tests |
+| AC2: install rejects disallowed host before fetch | ✅ Done | `tests/cli.test.ts` "AC2" |
+| AC3: install succeeds for allowed host | ✅ Done | Pure-function test proves the check passes; CLI-level test proves it isn't blocked and proceeds to the actual fetch attempt (a real successful clone isn't testable in this sandbox — no outbound network) |
+| AC4: update applies same check against recorded origin | ✅ Done | `tests/cli.test.ts` "AC4" |
+| AC5: host matching is exact-hostname, case-insensitive | ✅ Done | `tests/install.test.ts` "AC5" |
+
+5/5 met.
+
+## Security
+
+- Reviewed for common egress-check bypass classes: subdomain-suffix (`github.com.evil.com`), userinfo tricks (`GITHUB.COM@evil.com`), scp-regex misfire against a real `https://user@host:port/...` URL. None found — exact-match comparison plus WHATWG `URL.hostname` parsing (which correctly separates userinfo from host) close these off. `assertHostAllowed` runs after upstream validation (`isGitUrl`/`readSkillOrigin`'s `validateOrigin`), so the malformed-URL `new URL()`-throws case can't be reached with attacker-controlled input.
+- **Finding (ASK, medium confidence):** `skillmux update` (batch mode, no explicit skill-id) and `skillmux outdated` both call `checkOutdated` → `remoteHeadCommit` (`git ls-remote`) against every installed skill's recorded origin host, unconditionally — before `buildPlan`'s `assertHostAllowed` ever runs. So a disallowed host still receives one real network probe (`ls-remote`, not a content fetch) in batch mode, even though the actual content re-fetch (`cloneToTemp`) is correctly blocked. This matches the spec as written — `spec.md`'s Scope names only `resolveRepoSource`/`cloneToTemp` enforcement, and "before re-fetching" was read as "before the content fetch," not "before any network call." Whether to also gate `remoteHeadCommit` is a scope call, not a bug in what was built. Left as-is per spec; flagging for a decision now rather than silently shipping a narrower guarantee than "egress allowlist" might imply. `skillmux install` has no equivalent gap — its only network call is the fetch itself, already gated.
+
+## Correctness
+
+No issues found. `extractHost`'s scp-like regex only matches genuine `user@host:path` shapes (verified it doesn't misfire on `https://user@host:port/path`). Reusing the single early `loadConfig()` call in `runInstall` for `vaultPath` later is safe — nothing between the two original call sites depended on a fresh reload.
+
+**Nitpick:** `extractHost` doesn't special-case IPv6 literal hosts (`https://[::1]/x.git`). Not a security issue (worst case is a slightly odd host string in the allowlist comparison), and out of scope for this slice's "no glob support" minimal design. Not worth fixing now.
+
+## Performance
+
+No concerns. `assertHostAllowed` is an O(allowed_hosts.length) array scan over a config-sized list, called once per install/update candidate.
+
+## Tests (static + runtime)
+
+Coverage is solid: pure-function tests for `assertHostAllowed` (unset, blocked, allowed, case-insensitive, scp-like, file:// exemption) plus CLI-level integration tests proving the wiring into both `install` and `update`.
+
+**Nitpick:** no test exercises the *batch* `skillmux update` path (no explicit skill-id) reaching `assertHostAllowed` — only the explicit single-skill-id path is covered. Since `buildPlan` is the same function for both, divergence risk is low; not blocking.
+
+**Test execution:** `bun test` — 774 pass, 0 fail, 1981 assertions.
+
+**Build check:** SKIPPED — no build_command supplied.
+
+## Needs Decision
+
+1. ~~Should `checkOutdated`/`remoteHeadCommit`... also be gated?~~ **Resolved:** closed. `checkOutdated` now calls `assertHostAllowed` before `remoteHeadCommit`, threaded through both `runOutdated` and batch `runUpdate` (`resolveCandidateOrigins`). A disallowed host now reports `check_failed` with the allowlist error as `reason` instead of attempting `git ls-remote`. Covered by a new `outdated`-command-level test; batch `update`'s own path isn't independently tested since `checkOutdated` already filters `check_failed` out of its output before batch `update` ever sees it — a test at that layer can't distinguish "blocked by the allowlist" from "the host was simply unreachable," so it would pass without the fix (confirmed, then removed as a TDD false-positive). Coverage rests on the shared `checkOutdated` function's test plus the mechanical, low-risk parameter thread-through.
+
+## Security escalation
+
+Not recommended as a separate `/security-review` pass — the diff is a narrow, additive host-allowlist check with no auth/session/secrets/deserialization/process-execution surface, and the fan-out's security pass (run manually above) already covered the relevant bypass classes for this shape of change.

package/docs/sdd/supply-chain-hardening/spec.md

@@ -0,0 +1,42 @@
+<!-- source: docs/sdd/security-hardening-phase/think.md -->
+<!-- plane_project: SMX -->
+<!-- plane_module: supply-chain-hardening -->
+
+# Spec: Supply-Chain Hardening
+
+Slice 1 of 3 from the security-hardening-phase (see `docs/sdd/security-hardening-phase/think.md`).
+
+**Correction (discovered during `/sdd-tdd`, before any test was written):** the original AC5-AC8 below (hash-pinned scan verdicts / quarantine) were dropped after finding they're already fully shipped and tested — `src/provenance.ts` (`hashSkillContent`, `content_hash` on the `.skillmux-origin` sidecar) plus `src/commands/update.ts`'s `buildPlan` (local-drift check before fetch, unconditional scan on every fetched update before write). See `tests/cli.test.ts`'s `skillmux update CLI` suite. `think.md`'s landscape table marked this item "Not started" — that was wrong; it shipped as part of the earlier skill-provenance-update feature. Remaining scope is egress only.
+
+## Goal
+
+Enforce an install/update-time egress allowlist so `skillmux install`/`update` only fetch skill content from git hosts the operator has explicitly trusted.
+
+## Acceptance Criteria
+
+1. With `[egress] allowed_hosts` unset (default), `skillmux install`/`update` behavior is unchanged — no host is blocked.
+2. With `allowed_hosts` set, `install <source>` from a host not in the list is rejected before any network fetch, with an error naming the disallowed host.
+3. With `allowed_hosts` set, `install <source>` from a listed host succeeds unchanged.
+4. `skillmux update` applies the same host check against the skill's recorded origin before re-fetching.
+5. Host matching is exact-hostname, case-insensitive — no globbing in this slice.
+
+## Scope
+
+- `[egress] allowed_hosts: string[]` config (new `egress` section, unset = unrestricted).
+- Enforcement in `resolveRepoSource` (`src/install.ts`, shared by install and update call sites).
+- **Extended post-review:** also enforced in `checkOutdated`'s `git ls-remote` probe (`src/commands/outdated.ts`), used by both `skillmux outdated` and batch `skillmux update`. `/sdd-review` found the original scope left this network call unguarded even though the actual content fetch was correctly blocked — closed per user decision.
+
+## Out of Scope
+
+- Remote-inference egress (embedding/reranker calls) — that's `runtime-resource-hardening` (slice 2).
+- Hash-pinned scan verdicts / quarantine — already shipped, see Correction above.
+- Any staging/approval workflow, or new CLI subcommands/flags beyond the existing install/update/`--yes` flow.
+- Signer verification, SBOM/provenance, security posture visibility command, privacy reporting/purge — deferred phase-wide per `think.md`.
+- Glob/wildcard host patterns in `allowed_hosts` — exact-match list only for this slice.
+
+## Tasks
+
+1. Config schema: add `[egress] allowed_hosts` to `config.ts`.
+2. Enforcement: host-check in `resolveRepoSource`, wired into `install.ts` and `update.ts` call sites.
+3. Docs: document the `[egress]` config key. (Landed in `docs/skill-management.md` and `docs/configuration.md` — that's where install/update and the `[server]`-style config reference actually live, not `cli.md`/`deployment.md` as originally guessed.)
+4. Tests: config validation, allow/block enforcement, backward compatibility (unset = unrestricted).

package/docs/sdd/target-marker-rehome/spec.md

@@ -0,0 +1,33 @@
+## Goal
+
+Safely rehome every managed directory for one active target after its vault
+checkout moves, without changing skill links or unrelated targets.
+
+## Acceptance Criteria
+
+- [ ] `skillmux target rehome <name> --yes` updates the matching target
+  markers' `vault_path` to the configured vault path.
+- [ ] The command updates both the global target directory and every existing
+  project pin directory materialized for that target on the current host.
+- [ ] The command rejects a marker whose `role`, `target`, or managed symlink
+  destinations do not prove it belongs to the configured vault, and leaves all
+  markers unchanged on failure.
+- [ ] `--dry-run` reports the marker paths that would change and writes
+  nothing.
+- [ ] Other targets and their markers are unchanged.
+
+## Scope
+
+Add a `target rehome` CLI subcommand, its guarded marker migration logic,
+tests, CLI help, and user documentation.
+
+## Out of Scope
+
+Changing `skillmux.toml`, recreating target directories, adding/removing skill
+links, migrating full-vault surfaces, or modifying a non-matching target.
+
+## Tasks
+
+1. Add a failing CLI test for global and project target marker migration.
+2. Implement preflight validation and atomic marker rewrites.
+3. Add dry-run, rejection, and preservation coverage plus documentation.

package/docs/skill-management.md

@@ -171,7 +171,7 @@ skillmux core unpin csv-formatter --yes
 
 One command can change several skill IDs. Skillmux validates the complete
 change before writing, so a conflict prevents the whole operation. Core stays
-capped at 25 skills.
+capped at 25 skills by default, which `[core].limit` overrides.
 
 Run `skillmux sync` after a direct pin or unpin command.
 

package/docs/troubleshooting.md

@@ -29,7 +29,7 @@ downloads, contexts, evaluation, project/target/local-vault
 management, or `config init`/`config set`, install and use the host CLI:
 
 ```sh
-bun add -g @klhapp/skillmux
+npm install -g @klhapp/skillmux
 skillmux <the-command Docker rejected>
 ```
 
@@ -50,10 +50,25 @@ uname -m
 sha256sum skillmux-linux-amd64
 ```
 
-Download the file again with the [standalone installation procedure](getting-started.md#install-the-cli).
+Download the file again with the [standalone installation procedure](getting-started.md#standalone-executable).
 For GitHub build-provenance verification instead of the published SHA-256
 digest, use the [GitHub CLI attestation procedure](getting-started.md#install-with-github-cli-attestation).
 
+### `no native executable for <platform>-<arch>`
+
+The launcher could not find the platform package that carries the executable.
+This usually means the install skipped optional dependencies, which is what
+`npm install --no-optional` and `npm ci --omit=optional` do. Reinstall without
+that flag:
+
+```sh
+npm install -g @klhapp/skillmux
+```
+
+If the platform genuinely has no published build, install the
+[standalone executable](getting-started.md#standalone-executable) for it, or
+point `SKILLMUX_BINARY` at an executable you already have.
+
 ### `skillmux: command not found` after installation
 
 The standalone installer defaults to `~/.local/bin`. Add it to the shell's
@@ -167,6 +182,7 @@ step depends on the installation:
 | Installation | Expected action |
 | --- | --- |
 | Skillmux CLI with local inference | Download the local model and rebuild the index |
+| Skillmux CLI on Intel macOS | Expected: no ONNX Runtime exists for that platform. Configure remote embeddings |
 | Skillmux server (full image) | Inspect `doctor`, `/health/ready`, or `skill_router_deployment_info` for `image_variant=full`; do not infer it from the tag |
 | Skillmux server (slim image) | Configure remote embeddings or keep lexical fallback |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klhapp/skillmux",
-  "version": "1.11.2",
+  "version": "1.13.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,
@@ -15,13 +15,13 @@
   },
   "homepage": "https://github.com/klhq/skillmux#readme",
   "bin": {
-    "skillmux": "./src/cli.ts"
+    "skillmux": "./bin/skillmux.js"
   },
   "publishConfig": {
     "access": "public"
   },
   "files": [
-    "src",
+    "bin",
     "docs",
     "README.md",
     "LICENSE",
@@ -36,18 +36,25 @@
     "eval": "bun run src/cli.ts eval",
     "doctor": "bun run src/cli.ts doctor",
     "models:download": "bun run src/cli.ts models download",
-    "build": "bun build --compile src/cli.ts --outfile dist/skillmux"
+    "build": "bun run scripts/build-binaries.ts host",
+    "build:binaries": "bun run scripts/build-binaries.ts",
+    "build:npm-packages": "bun run scripts/package-npm-binaries.ts"
   },
   "devDependencies": {
-    "bun-types": "^1.3.14"
-  },
-  "dependencies": {
     "@huggingface/transformers": "^4.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "bun-types": "^1.3.14",
     "zod": "^4.4.3"
   },
   "trustedDependencies": [
     "onnxruntime-node",
     "protobufjs"
-  ]
+  ],
+  "optionalDependencies": {
+    "@klhapp/skillmux-darwin-arm64": "1.13.0",
+    "@klhapp/skillmux-darwin-x64": "1.13.0",
+    "@klhapp/skillmux-linux-arm64": "1.13.0",
+    "@klhapp/skillmux-linux-x64": "1.13.0",
+    "@klhapp/skillmux-win32-x64": "1.13.0"
+  }
 }