@klhapp/skillmux 0.2.1 → 0.4.3

package/CHANGELOG.md

@@ -5,6 +5,82 @@ 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).
 
+## [0.4.3](https://github.com/klhq/skillmux/compare/v0.4.2...v0.4.3) (2026-07-23)
+
+
+### Fixed
+
+* **release:** prevent slim from overwriting latest ([#53](https://github.com/klhq/skillmux/issues/53)) ([8b5da28](https://github.com/klhq/skillmux/commit/8b5da285b5cb2c9b3231e94ed1ec29331cf8cb9a))
+* **release:** safe backfill and isolate publishing ([#51](https://github.com/klhq/skillmux/issues/51)) ([872333a](https://github.com/klhq/skillmux/commit/872333a70f32bf5be68cc3599c43bd4943a91051))
+
+## [0.4.2](https://github.com/klhq/skillmux/compare/v0.4.1...v0.4.2) (2026-07-23)
+
+
+### Fixed
+
+* **release:** validate explicit release tag ([#46](https://github.com/klhq/skillmux/issues/46)) ([ec11057](https://github.com/klhq/skillmux/commit/ec11057d18162ace7944b1ee07bd0fb1f282efcc))
+
+## [0.4.1](https://github.com/klhq/skillmux/compare/v0.4.0...v0.4.1) (2026-07-22)
+
+
+### Fixed
+
+* **release:** publish immediately from release please ([#44](https://github.com/klhq/skillmux/issues/44)) ([4569cf3](https://github.com/klhq/skillmux/commit/4569cf3eed7ded5d4cb032f622a6a92e3eb28b21))
+
+## [0.4.0](https://github.com/klhq/skillmux/compare/v0.3.0...v0.4.0) (2026-07-22)
+
+
+### Added
+
+* **cli:** add 'skillmux local-vault init <path>' to write the local_vault marker ([7648145](https://github.com/klhq/skillmux/commit/76481452994f98d6ef01fb1302344fc76a547492))
+* **cli:** add 'skillmux which <skill_id>' to show which root resolves a skill ([0dfd0ed](https://github.com/klhq/skillmux/commit/0dfd0ed9e067f12dfce6cd9a3bc5fe61eeedf4d8))
+* **cli:** add skill visibility command ([a00d248](https://github.com/klhq/skillmux/commit/a00d24811b3b91e947a529fe87f742acf6cb4ce7))
+* **cli:** filter [project.*] groups by each target's project_groups ([e039920](https://github.com/klhq/skillmux/commit/e039920349769e65d01555a5681a4b1724fddf88))
+* **completions:** list 'which' in bash and zsh command completions ([fc8151f](https://github.com/klhq/skillmux/commit/fc8151fc83a0e57b2eb57decdf78d716cdf7a8fa))
+* **config:** add local_vault_paths alongside the unchanged vault_path ([4d8c95e](https://github.com/klhq/skillmux/commit/4d8c95e600a6607e8e83b9fb5a6344677003d3c3))
+* **doctor:** report local_vault_paths marker presence and vault_path drift ([eb8e8a3](https://github.com/klhq/skillmux/commit/eb8e8a304847c366f2ba057e1d9b9741516e75c2))
+* **doctor:** report shadowed skills across vault_path and local_vault_paths ([eac168d](https://github.com/klhq/skillmux/commit/eac168d3c729d7a610632c73fa573ad4947964d9))
+* **manifest:** add pin/unpin --core to skillmux manifest CLI ([59a4ceb](https://github.com/klhq/skillmux/commit/59a4ceb8a25867c4bc73932294aae6a8a1f9edd8))
+* **manifest:** add pin/unpin --project <group> --repo to skillmux manifest CLI ([3bf98e9](https://github.com/klhq/skillmux/commit/3bf98e983bd05b35d15b25f4effd1fb33cf03b8f))
+* **manifest:** add pin/unpin and local-vault markers ([f1329ae](https://github.com/klhq/skillmux/commit/f1329ae48b1c7603201f039b80ac2b8489101cf8))
+* **manifest:** add the AC6 portability guard to validateManifest ([fb83299](https://github.com/klhq/skillmux/commit/fb8329969228029d7d9561884a1f0f0df3aa7a77))
+* **manifest:** project_groups + local_vault_paths overlay support ([#40](https://github.com/klhq/skillmux/issues/40)) ([411ecfb](https://github.com/klhq/skillmux/commit/411ecfb243695465aea44dc4a9192190ecde6086))
+* **manifest:** replace targets.*.project boolean with project_groups ([ccd246e](https://github.com/klhq/skillmux/commit/ccd246e8238c00eebac6abfde4d4250f87d770db))
+* **sync:** add role field to SkillmuxMarker with read-compat for absent role ([79af610](https://github.com/klhq/skillmux/commit/79af610c4fd598e458a947eb01f7c01358f38402))
+* **vault:** add findShadowedSkills to surface cross-root skill_id collisions ([7d1a328](https://github.com/klhq/skillmux/commit/7d1a3287ea47044e39371d38a360c3acc3d2f2c0))
+* **vault:** resolve skills through local_vault_paths before vault_path ([0c1f603](https://github.com/klhq/skillmux/commit/0c1f60328b30681dd739224a5a53cdb178413a18))
+
+
+### Fixed
+
+* **manifest:** reject invalid [project.*] group names in pinProject before writing ([153d0ac](https://github.com/klhq/skillmux/commit/153d0ac39a548ca47aafb0ddd309cbb4da63fda8))
+* **router-core:** tolerate broken content when a root wins on existence alone ([6cb4d0d](https://github.com/klhq/skillmux/commit/6cb4d0d64bd0dd98d7fd44ac382ea2e9e3f2e125))
+
+## [0.3.0](https://github.com/klhq/skillmux/compare/v0.2.1...v0.3.0) (2026-07-21)
+
+
+### Added
+
+* **adapters:** add unified local and remote target adapters (AC3, AC7, AC10) ([552b7d8](https://github.com/klhq/skillmux/commit/552b7d8f26ece4ab4a98f14326e508e35aeb57d5))
+* **admin:** add authenticated /admin/v1 HTTP control plane (AC7, AC8, AC9, AC10) ([7b7958f](https://github.com/klhq/skillmux/commit/7b7958fb0e248e2c33a0ca1e566286617a8a0d84))
+* **calibrate:** Automated calibration-tuning pipeline, evidence store, and live reload ([#35](https://github.com/klhq/skillmux/issues/35)) ([7ccd79f](https://github.com/klhq/skillmux/commit/7ccd79f9d25d901aa3d7aec43953b79896ebfa24))
+* **cli:** add output formatting, exit code mapping, and shell completions (AC11, AC12) ([0099395](https://github.com/klhq/skillmux/commit/009939501192f81dc8fbe2e15c33bce22beb1456))
+* **cli:** CLI polish, target resolution, config/calibrate parity, and admin control plane ([a4fb67d](https://github.com/klhq/skillmux/commit/a4fb67d3e8a09ae6ef8151ad4892ec3d94d261e0))
+* **cli:** connect CLI dispatcher with context, config, calibrate, and completions (cli-polish) ([bd3fd14](https://github.com/klhq/skillmux/commit/bd3fd140443e4523fcaf163b2fe5e57d5c51ac9c))
+* **config:** add source-aware config service and status tracking (AC4, AC5, AC6) ([325342a](https://github.com/klhq/skillmux/commit/325342a55b5bac4a7b3aee7d7740e2fc22f7aee7))
+* **context:** add context management and target resolution service (AC1, AC2) ([34435c9](https://github.com/klhq/skillmux/commit/34435c934aaa5ad69af90b7b42e761c674d6ac85))
+
+
+### Fixed
+
+* **clients:** handle trailing /v1 in embedding base_url ([26d8158](https://github.com/klhq/skillmux/commit/26d8158138b390ffb3e5c3f54777273673db0a73))
+* **types:** resolve TypeScript compilation errors in CLI, adapters, and server ([e4ad7d2](https://github.com/klhq/skillmux/commit/e4ad7d2c059157e52a9f584f15eeaed6a8091fec))
+
+
+### Changed
+
+* **config:** remove deprecated environment variable shims ([#34](https://github.com/klhq/skillmux/issues/34)) ([e046f45](https://github.com/klhq/skillmux/commit/e046f45c3133b2e91b4920513975107b025b19f5))
+
 ## [0.2.1](https://github.com/klhq/skillmux/compare/skillmux-v0.2.0...skillmux-v0.2.1) (2026-07-21)
 
 ## [0.2.0](https://github.com/klhq/skillmux/compare/skillmux-v0.1.1...skillmux-v0.2.0) (2026-07-21)

package/README.md

@@ -13,11 +13,18 @@ Built for agents that lack native skill triggering (Goose recipe workers, openco
 - [Pinning skills across surfaces](#pinning-skills-across-surfaces) — optional: statically load a curated set across multiple agents
 - [Docker Usage](#docker-usage)
 - [Configuration](#configuration) — inference modes, security scanning, installing skills, env vars
+- [CLI & Automation](docs/cli.md) — context management, remote target resolution, policy calibration, JSON envelopes
+- [Benchmarks & Evaluation](#benchmarks--evaluation)
+- [FAQ & Troubleshooting](#faq--troubleshooting)
 - [Guarantees](#guarantees)
 - [Development](#development)
 
 ## How it works
 
+<p align="center">
+  <img src="docs/assets/architecture.svg" alt="skillmux Architecture &amp; Hybrid Routing Flow" width="100%">
+</p>
+
 ```
 resolve_skill("convert this spreadsheet to markdown")
         │
@@ -195,7 +202,15 @@ This writes `skillmux.toml` at the vault root and marks `~/.claude/skills` as sk
 
 ### 2. Pick which skills are pinned
 
-`init` always starts `[core]` empty — there's no heuristic yet for which skills belong there. Edit `skillmux.toml` by hand:
+`init` always starts `[core]` empty — there's no heuristic yet for which skills belong there. Pin with the CLI instead of hand-editing `skillmux.toml`:
+
+```sh
+skillmux manifest pin csv-formatter --core
+```
+
+Unpin the same way: `skillmux manifest unpin csv-formatter --core`. `--project <group>` pins into a `[project.<group>]` tier instead (add `--repo <path>` the first time, to create the group). Every pin is validated before writing — the skill must actually resolve from the vault, and `[core]` stays under its 25-skill cap.
+
+Hand-editing `skillmux.toml` still works if you prefer it:
 
 ```toml
 [core]
@@ -203,10 +218,10 @@ skills = ["csv-formatter"]
 
 [targets.claude]
 dir = "/Users/you/.claude/skills"
-project = false
+project_groups = []
 ```
 
-Cap: 25 skills in `[core]`. Full manifest schema, including `[project.<group>]` pins scoped to one repo, is in [`docs/configuration.md`](docs/configuration.md#tiers-and-the-manifest).
+Full manifest schema, including `[project.<group>]` pins scoped to one repo and machine-local overlay vaults via `local_vault_paths`, is in [`docs/configuration.md`](docs/configuration.md#tiers-and-the-manifest).
 
 ### 3. Materialize
 
@@ -387,6 +402,10 @@ All core settings can be overridden via environment variables (handy for Docker)
 
 Remote API keys are read from the environment variables named by `inference.embedding.api_key_env` and `inference.reranker.api_key_env`; no secret ever lives in the config file.
 
+## Benchmarks & Evaluation
+
+Skillmux includes a built-in evaluation framework to benchmark retrieval accuracy (lexical vs. hybrid vector search) against labeled intent datasets.
+
 Evaluate lexical and local hybrid retrieval against the checked-in labeled queries:
 
 ```sh
@@ -396,6 +415,56 @@ bun run src/cli.ts eval
 # hybrid recall@5:  1.000
 ```
 
+Custom policy calibration can also be performed against domain-specific query logs using `skillmux calibrate` (see [`docs/cli.md`](docs/cli.md#policy-calibration-skillmux-calibrate)).
+
+## FAQ & Troubleshooting
+
+<details>
+<summary><b>Why did my query return <code>ambiguous</code> instead of <code>matched</code>?</b></summary>
+
+<br>
+
+The router returns `"outcome": "ambiguous"` when multiple candidate skills meet retrieval confidence thresholds, or when no single candidate dominates by a sufficient score margin. In this state, up to 10 candidate skill summaries (`skill_id`, `title`, `description`) are returned so the calling LLM can choose the exact skill and invoke `fetch_skill`.
+
+</details>
+
+<details>
+<summary><b>Does skillmux require an active internet connection?</b></summary>
+
+<br>
+
+No. In default local inference mode (`inference.mode = "local"`), skillmux operates 100% offline. The default GTE-small embedding model is quantized to q8 and bundled within the binary/Docker image.
+
+</details>
+
+<details>
+<summary><b>What happens when remote embedding or reranking endpoints fail?</b></summary>
+
+<br>
+
+Skillmux features automatic fallback degradation. If remote embedding APIs or rerankers become unreachable, the router gracefully falls back to SQLite FTS5 lexical search rather than throwing an error to the calling agent.
+
+</details>
+
+<details>
+<summary><b>When should I use routed skills vs. pinned skills?</b></summary>
+
+<br>
+
+- **Routed (Default)**: Best for expanding vaults with dozens or hundreds of skills. Skills are loaded dynamically on demand via `resolve_skill`, keeping the agent's initial context window clean.
+- **Pinned (`skillmux sync`)**: Best when running multiple agent surfaces (e.g. Claude Code, opencode) that all require the same core set of 2–5 skills loaded statically at agent startup.
+
+</details>
+
+<details>
+<summary><b>How do I verify server readiness and routing health?</b></summary>
+
+<br>
+
+Run `skillmux doctor` locally or hit the HTTP readiness endpoint (`GET /health/ready`). `doctor` checks vault accessibility, state directory permissions, ONNX runtime binding status, and active retrieval lane status.
+
+</details>
+
 ## Guarantees
 
 - **Read-only vault** — no code path writes under the vault; all state is confined to `state_dir`. Covered by tests.

package/config.example.toml

@@ -3,3 +3,8 @@
 # vault_path is a neutral path, never a harness's static-loading scan
 # surface (e.g. ~/.agents/skills) — see docs/sdd/skr-cli/think.md.
 vault_path = "~/skills"
+
+# Optional, default []: machine-local override-only vaults, checked before
+# vault_path for a given skill_id. Never holds skillmux.toml or the sync git
+# hook — those always stay in vault_path. See docs/configuration.md#local-vault-overlays.
+# local_vault_paths = ["~/skills-local"]

package/docs/configuration.md

@@ -2,6 +2,8 @@
 
 Skillmux defaults to FTS5 plus local GTE-small semantic retrieval. Most users need no config file.
 
+For detailed CLI command reference, target resolution, policy calibration, and automation envelopes, see [`docs/cli.md`](cli.md).
+
 ## Local mode
 
 ```toml
@@ -88,13 +90,65 @@ skills = ["pdf-extractor"]           # must not overlap [core]
 
 [targets.claude]
 dir = "/Users/you/.claude/skills"
-project = false                      # true = also apply [project.*] groups scoped to this target
+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 `<repo>/<relative path from $HOME to the target dir>`, for each `repos` entry, and only for targets with `project = true`. `repos` 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.
-- `[targets.<name>]` — one entry per adopted surface. `skillmux init --target <name> --yes` writes these; hand-editing is fine as long as `sync` is still allowed to own the directory (see below).
+- `[project.<group>].skills` — symlinked only into `<repo>/<relative path from $HOME to the target dir>`, for each `repos` entry, and only for targets whose `project_groups` names that group. `repos` 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.
+- `[targets.<name>]` — one entry per adopted surface. `skillmux init --target <name> --yes` writes these; hand-editing is fine as long as `sync` is still allowed to own the directory (see below). `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 manifest pin`/`unpin` mutate `[core]`/`[project.*]` for you, validating with the same rules `sync`/`doctor` enforce (skill must resolve from `vault_path`, no duplicate pins, `[core]` stays under the 25-skill cap) before writing anything:
+
+```sh
+skillmux manifest pin csv-formatter --core                                   # add to [core]
+skillmux manifest pin pdf-extractor --project repo1                          # add to an existing group
+skillmux manifest pin pdf-extractor --project repo2 --repo ~/code/repo2      # create a new group
+skillmux manifest unpin csv-formatter --core                                 # remove from [core]
+skillmux manifest unpin pdf-extractor --project repo1                        # remove from a group (group stays, even if empty)
+```
+
+`--repo` is only accepted when `--project <group>` names a group that doesn't exist yet — passing it for an existing group is rejected, since changing an existing group's `repos` isn't this command's job. 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:** `[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 = []`.
+
+Every `[core]`/`[project.*]` skill_id must resolve from the canonical `vault_path` — pinning a skill that only exists in a `local_vault_paths` entry (see below) fails `sync`/`doctor` with a distinct error, since the manifest is meant to be portable across machines and a machine-local override wouldn't exist elsewhere.
 
 ### Ownership marker
 
-Every directory `sync` manages gets a `.skillmux` marker file (`{"managed_by": "skillmux", "target": "<name>", "created_at": ...}`). `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). This is also why `sync --restore-monolith` (which deletes the marker and replaces the whole directory with one symlink straight to the vault) requires re-running `init` before that target can be `sync`'d again.
+Every directory `sync` manages gets a `.skillmux` marker file (`{"managed_by": "skillmux", "role": "target", "target": "<name>", "created_at": ...}`). `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). This is also why `sync --restore-monolith` (which deletes the marker and replaces the whole directory with one symlink straight to the vault) requires re-running `init` before that target can be `sync`'d again.
+
+The same `.skillmux` marker filename and JSON shape is also used for `local_vault_paths` entries (see below), distinguished by `role: "local_vault"` with a `vault_path` field instead of `target`. Markers written before this `role` field existed have no `role` key at all — they're read back as `role: "target"`, so nothing already on disk needs migrating.
+
+### 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:
+
+```toml
+vault_path = "~/skills"                 # unchanged: canonical, 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.
+- **`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.
+- **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:
+
+- `skillmux which <skill_id>` — prints which root actually serves that skill, and names every root it shadows:
+  ```
+  $ skillmux 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.
+
+**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`).

package/docs/releasing.md

@@ -1,39 +1,78 @@
 # Releasing
 
-Releases are created from version tags after `main` is green.
+Release Please creates releases after `main` is green. When its release PR is
+merged, the same workflow creates the matching version tag and runs the
+publishing jobs directly. The pipeline does not rely on a second workflow being
+triggered by a tag created with `GITHUB_TOKEN`, and production environment
+secrets do not cross a reusable-workflow boundary.
 
 ## Prepare
 
-1. Update `version` in `package.json`.
-2. Move relevant entries from `Unreleased` into a dated version section in `CHANGELOG.md`.
-3. Merge those changes through a pull request and confirm CI passes.
+1. Merge changes to `main` using Conventional Commit titles.
+2. Review the Release Please PR, including its version and changelog.
+3. Confirm CI passes, then merge the Release Please PR.
 
-## Publish
+## Publish automatically
 
-Create and push the matching tag:
+After the Release Please PR merges, the same workflow run creates the tag and
+GitHub Release, then publishes with the exact tag and commit SHA returned by
+Release Please. The package version, tag, and commit must all match before
+publishing begins.
 
-```bash
-git switch main
-git pull --ff-only
-git tag v0.1.1
-git push origin v0.1.1
-```
+There is intentionally no tag-push entry point. GitHub does not start a second
+workflow for a tag created with the default `GITHUB_TOKEN`; publishing in the
+Release Please workflow avoids that event-suppression edge case without adding
+a PAT or GitHub App token.
+
+## Exceptional recovery
 
-The tag must exactly match `v` plus the `package.json` version. A mismatch stops the release.
+Use the manual `workflow_dispatch` entry point only to backfill an existing
+Release Please tag. The workflow verifies that the tag is clean SemVer,
+resolves to the checked-out commit, is reachable from `main`, and still matches
+`package.json`. It also requires a matching existing GitHub Release. Manual
+backfills never publish npm, so a container or binary recovery cannot
+accidentally republish an existing npm version.
 
 The release workflow publishes:
 
 - `skillmux-linux-amd64`
 - `skillmux-linux-arm64`
 - GitHub build provenance attestations when the repository is public
-- Full image: `:<version>`, `:<major>.<minor>`, `:<major>`, and `:latest`
-- Slim image: `:<version>-slim`, `:<major>.<minor>-slim`, `:<major>-slim`, and `:latest-slim`
-- Multi-architecture `linux/amd64` and `linux/arm64` images with SBOM and provenance
-
-Each Docker tag is a multi-architecture manifest. Users run the same tag on AMD64 and ARM64; Docker automatically pulls the matching image.
-
-Container images are published to GitHub Container Registry only; the release workflow does not require external registry credentials.
-Private repositories still publish BuildKit SBOM/provenance with container images, but GitHub artifact attestations are skipped because GitHub does not support them for user-owned private repositories.
+- Full image to GHCR and Docker Hub: `:<version>`, `:<major>.<minor>`,
+  and `:latest`
+- Slim image to GHCR and Docker Hub: `:<version>-slim`,
+  `:<major>.<minor>-slim`, and `:latest-slim`
+- Multi-architecture `linux/amd64` and `linux/arm64` images with SBOM and
+  provenance
+
+GHCR is the canonical container build. After both GHCR variants are published,
+Docker Hub copies those exact multi-architecture images under its matching
+tags. A Docker Hub authentication or availability failure therefore cannot
+prevent GHCR from publishing.
+
+Each Docker tag is a multi-architecture manifest. Users run the same tag on
+AMD64 and ARM64; Docker automatically pulls the matching image.
+
+The two variants are separate multi-architecture manifests rather than
+architecture-suffixed public tags. Docker selects the correct AMD64 or ARM64
+image for the host automatically. Pin `:<version>` or `:<version>-slim` for
+reproducible deployments; use the floating `latest` tags only when automatic
+upgrades are intentional.
+
+Container images are published to:
+
+- `ghcr.io/klhq/skillmux`
+- `${DOCKERHUB_USERNAME}/skillmux` on Docker Hub
+
+The `production-release` GitHub environment provides the
+`DOCKERHUB_USERNAME` variable and `DOCKERHUB_TOKEN` secret. The npm job also
+uses this environment as its Trusted Publisher identity; configure npm with
+workflow `release-please.yml` and environment `production-release`. No
+long-lived npm token is required. GitHub Packages uses the workflow's scoped
+`GITHUB_TOKEN`.
+Private repositories still publish BuildKit SBOM/provenance with container
+images, but GitHub artifact attestations are skipped because GitHub does not
+support them for user-owned private repositories.
 
 Verify downloaded binaries with build provenance attestation:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klhapp/skillmux",
-  "version": "0.2.1",
+  "version": "0.4.3",
   "description": "Local read-only MCP server routing natural-language task queries to skills in a SKILL.md vault, with zero-loss delivery",
   "type": "module",
   "private": false,