@klhapp/skillmux 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.5.0](https://github.com/klhq/skillmux/compare/v1.4.1...v1.5.0) (2026-08-17)
+
+
+### Added
+
+* **config:** add configuration authority, bounded reranking, and degradation resilience ([2626709](https://github.com/klhq/skillmux/commit/262670983b2a7d3674dd02fa5ef90a4a3ebe26c6))
+* **config:** add degradation-aware reranking controls ([1a87ee9](https://github.com/klhq/skillmux/commit/1a87ee90601dc632c127298ebb39be5e8bd12e66))
+* **config:** add output.ambiguous_candidate_limit and evaluation report case details ([7194b28](https://github.com/klhq/skillmux/commit/7194b2874faeebfd89d047063369499ace06785d))
+
+
+### Fixed
+
+* **config:** satisfy effective config type checks ([b12693c](https://github.com/klhq/skillmux/commit/b12693ca1ba30d51351d8e5439822ff2f23350df))
+* **routing:** align evaluation with runtime ranking ([ca6e6ca](https://github.com/klhq/skillmux/commit/ca6e6ca847a0604be190e63ac0a177e6e593e817))
+
+## [1.4.1](https://github.com/klhq/skillmux/compare/v1.4.0...v1.4.1) (2026-08-04)
+
+
+### Fixed
+
+* **ci:** publish npm package to GitHub Packages ([#110](https://github.com/klhq/skillmux/issues/110)) ([5de37f2](https://github.com/klhq/skillmux/commit/5de37f22a658187cd270743b24237844513c1e54))
+
 ## [1.4.0](https://github.com/klhq/skillmux/compare/v1.3.4...v1.4.0) (2026-08-04)
 
 

package/config.example.toml

@@ -5,6 +5,12 @@
 # which core and project skills appear in those directories.
 vault_path = "~/skills"
 
+# Optional: configuration authority policy. Defaults to true.
+# When set to false, behavioral environment variables are ignored and TOML remains
+# authoritative (CLI flags and secret names like api_key_env still resolve).
+# [config]
+# environment_overrides = true
+
 # 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.

package/config.remote.example.toml

@@ -4,6 +4,13 @@
 # Keep the canonical vault separate from client skill directories.
 vault_path = "~/skills"
 
+# Optional: bounded recall and candidate reranking budgets.
+# k_rerank bounds the maximum number of candidates passed to the reranker adapter.
+# [recall]
+# k_lexical = 20
+# k_vector = 20
+# k_rerank = 10
+
 [inference]
 mode = "remote"
 timeout_ms = 5000

package/docs/configuration.md

@@ -124,35 +124,59 @@ Reranker adapter and model form the calibration identity. Moving an unchanged
 deployment to another endpoint does not invalidate calibration; changing the
 adapter or model does.
 
+## Configuration authority
+
+By default, Skillmux allows namespaced environment variables (`SKILLMUX_*`) to override values from `config.toml`. When deploying in strict environments where the TOML configuration must be authoritative against runtime container environment drift:
+
+```toml
+[config]
+environment_overrides = false
+```
+
+When `config.environment_overrides = false`:
+- Behavioral environment overrides (e.g. `SKILLMUX_VAULT_PATH`, `SKILLMUX_RECALL_K_RERANK`, `EMBED_MODEL`) are ignored and logged as masked by TOML policy.
+- `SKILLMUX_CONFIG` (config path pointer), CLI flags (`--vault`, `--config`), and named secret variables referenced via `api_key_env` / `token_env` remain fully authoritative.
+- Generic un-namespaced variables (`EMBED_*`, `RERANK_*`, `HTTP_*`, `VAULT_PATH`) are deprecated in 1.x and trigger warnings encouraging the preferred `SKILLMUX_*` namespace.
+
+Inspect provenance and active policy with `skillmux config show --sources` or `skillmux doctor`.
+
 ## Advanced retrieval
 
-Candidate-generation depth and agent-context delivery are separate controls:
+Candidate-generation depth, reranking candidate budgets, and agent-context delivery are separate controls:
 
 ```toml
 [recall]
 k_lexical = 20
 k_vector = 20
+k_rerank = 10
 
-[thresholds]
-candidate_limit = 5
+[output]
+ambiguous_candidate_limit = 5
 ```
 
-`recall.k_lexical` and `recall.k_vector` control retrieval depth and cost. The
-reranker receives the fused union from both retrieval lanes. Increasing these
-values can improve retrieval recall, but costs more work.
-
-`thresholds.candidate_limit` controls agent context: it caps the ambiguous
-candidate list returned to the calling LLM after retrieval, reranking, and
-threshold filtering. It does not change retrieval depth or the matched,
-ambiguous, or no-match classification.
-
-Reranker thresholds have no universal default because score distributions are
-model-specific. Without `inference.thresholds`, Skillmux still uses the
-reranker to order candidates but keeps outcomes ambiguous rather than
-auto-matching. Use `skillmux calibrate run` to select
-`match_score`, `match_margin`, and `candidate_floor`, then explicitly apply the
-certified run. The [calibration guide](calibration.md) also publishes a
-clearly-scoped BGE reference profile for smoke tests.
+- `recall.k_lexical` and `recall.k_vector` control initial candidate generation depth.
+- `recall.k_rerank` bounds the candidate shortlist sent to the reranker adapter (defaults to `10`, cannot exceed `k_lexical + k_vector`).
+- `output.ambiguous_candidate_limit` controls agent context: it caps the ambiguous candidate list returned to the calling LLM after retrieval, reranking, and threshold filtering (`thresholds.candidate_limit` is deprecated in 1.x).
+
+### Failure visibility and degraded retrieval
+
+When remote embedding or reranking fails or times out, Skillmux gracefully falls back to the strongest surviving retrieval lane (`hybrid` or `lexical`). The response carries structured degradation metadata:
+
+```json
+{
+  "outcome": "ambiguous",
+  "retrieval": "hybrid",
+  "degraded_from": "reranked",
+  "degradation_reason": "reranker_timeout",
+  "candidates": [...]
+}
+```
+
+Stable degradation reason codes:
+- `embedding_timeout`, `embedding_unavailable`, `embedding_protocol_error`
+- `reranker_timeout`, `reranker_unavailable`, `reranker_protocol_error`
+
+These safe reason codes are exposed via MCP and recorded in the audit database without logging credentials or raw upstream response bodies. Degraded retrieval count metrics are tracked under `skill_router_degraded_retrieval_total{stage,reason}`.
 
 ## HTTP server
 

package/docs/releasing.md

@@ -35,6 +35,8 @@ accidentally republish an existing npm version.
 
 The release workflow publishes:
 
+- `@klhapp/skillmux` to the public npm registry
+- `@klhq/skillmux` to GitHub Packages, linked to this repository
 - `skillmux-linux-amd64`
 - `skillmux-linux-arm64`
 - SHA-256 digests for the Linux binaries in the GitHub Release asset metadata
@@ -67,11 +69,16 @@ Container images are published to:
 - `${DOCKERHUB_USERNAME}/skillmux` on Docker Hub
 
 The `production-release` GitHub environment provides the
-`DOCKERHUB_USERNAME` variable and `DOCKERHUB_TOKEN` secret. The npm job also
+`DOCKERHUB_USERNAME` variable and `DOCKERHUB_TOKEN` secret. The npmjs 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`.
+long-lived npm token is required. The GitHub Packages job uses the workflow's
+scoped `GITHUB_TOKEN` and changes only its runner-local package name to
+`@klhq/skillmux`; the source package remains `@klhapp/skillmux` for npmjs.
+
+GitHub initially creates npm packages with private visibility. After the first
+release, open the `@klhq/skillmux` package settings and make it public if it
+should be visible outside the organization.
 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.

package/docs/schema.json

@@ -21,6 +21,18 @@
       "minLength": 1,
       "maxLength": 512
     },
+    "DegradationReason": {
+      "type": "string",
+      "description": "Safe stable reason code describing why a higher-capability retrieval lane fell back.",
+      "enum": [
+        "embedding_timeout",
+        "embedding_unavailable",
+        "embedding_protocol_error",
+        "reranker_timeout",
+        "reranker_unavailable",
+        "reranker_protocol_error"
+      ]
+    },
     "Candidate": {
       "type": "object",
       "description": "One shortlist entry in an ambiguous result.",
@@ -50,6 +62,8 @@
       "properties": {
         "outcome": { "const": "matched" },
         "retrieval": { "enum": ["exact", "reranked"] },
+        "degraded_from": { "enum": ["reranked", "hybrid"] },
+        "degradation_reason": { "$ref": "#/$defs/DegradationReason" },
         "skill_id": { "$ref": "#/$defs/SkillId" },
         "title": { "type": "string", "minLength": 1, "maxLength": 512 },
         "content_sha256": { "$ref": "#/$defs/Sha256Hex" },
@@ -83,6 +97,8 @@
       "properties": {
         "outcome": { "const": "ambiguous" },
         "retrieval": { "enum": ["exact", "reranked", "hybrid", "lexical"] },
+        "degraded_from": { "enum": ["reranked", "hybrid"] },
+        "degradation_reason": { "$ref": "#/$defs/DegradationReason" },
         "candidates": {
           "type": "array",
           "items": { "$ref": "#/$defs/Candidate" },
@@ -99,6 +115,8 @@
       "properties": {
         "outcome": { "const": "no_match" },
         "retrieval": { "enum": ["exact", "reranked", "hybrid", "lexical"] },
+        "degraded_from": { "enum": ["reranked", "hybrid"] },
+        "degradation_reason": { "$ref": "#/$defs/DegradationReason" },
         "message": {
           "type": "string",
           "description": "Fixed guidance string telling the caller to proceed normally.",
@@ -151,10 +169,26 @@
       "type": "object",
       "description": "config.toml, validated at startup. Local ONNX is the default; remote inference is explicit.",
       "properties": {
+        "config": {
+          "type": "object",
+          "properties": {
+            "environment_overrides": {
+              "type": "boolean",
+              "default": true,
+              "description": "Whether environment variables override TOML values at runtime."
+            }
+          },
+          "additionalProperties": false
+        },
         "vault_path": {
           "type": "string",
-          "description": "Skill vault root. Default: ~/.agents/skills",
-          "default": "~/.agents/skills"
+          "description": "Skill vault root. Default: ~/skills",
+          "default": "~/skills"
+        },
+        "local_vault_paths": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": []
         },
         "state_dir": {
           "type": "string",
@@ -165,30 +199,43 @@
           "type": "object",
           "properties": {
             "k_lexical": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 },
-            "k_vector": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }
+            "k_vector": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 },
+            "k_rerank": { "type": "integer", "minimum": 1, "maximum": 200, "default": 10 }
           },
           "required": ["k_lexical", "k_vector"],
           "additionalProperties": false
         },
+        "output": {
+          "type": "object",
+          "properties": {
+            "ambiguous_candidate_limit": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 50,
+              "default": 5,
+              "description": "Maximum number of candidates returned on ambiguous outcomes."
+            }
+          },
+          "additionalProperties": false
+        },
         "thresholds": {
           "type": "object",
-          "description": "Caller-facing shortlist policy. Reranker thresholds live under inference.thresholds.",
+          "description": "Caller-facing shortlist policy (deprecated in favor of output.ambiguous_candidate_limit). Reranker thresholds live under inference.thresholds.",
           "properties": {
             "candidate_limit": {
               "type": "integer",
               "minimum": 1,
               "maximum": 50,
               "default": 5,
-              "description": "Maximum number of candidates returned on ambiguous outcomes (top-k limit)."
+              "description": "Deprecated: use output.ambiguous_candidate_limit instead."
             }
           },
-          "required": ["candidate_limit"],
           "additionalProperties": false
         },
         "inference": { "$ref": "#/$defs/InferenceConfig" },
         "server": { "$ref": "#/$defs/ServerConfig" }
       },
-      "required": ["vault_path", "state_dir", "recall", "thresholds", "inference"],
+      "required": ["vault_path", "state_dir", "recall", "inference"],
       "additionalProperties": false
     },
     "InferenceConfig": {
@@ -295,6 +342,12 @@
         "query": { "type": "string" },
         "outcome": { "type": "string", "enum": ["matched", "ambiguous", "no_match"] },
         "retrieval": { "enum": ["exact", "reranked", "hybrid", "lexical"] },
+        "degraded_from": {
+          "oneOf": [{ "enum": ["reranked", "hybrid"] }, { "type": "null" }]
+        },
+        "degradation_reason": {
+          "oneOf": [{ "$ref": "#/$defs/DegradationReason" }, { "type": "null" }]
+        },
         "candidates": {
           "type": "array",
           "description": "skill_id + score of every reranked (or FTS5-ranked) candidate considered, best first.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klhapp/skillmux",
-  "version": "1.4.0",
+  "version": "1.5.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

@@ -138,6 +138,8 @@ export class LocalAdapter implements TargetAdapter {
     minAutoMatchCount?: number;
   }): Promise<{ run_id?: string; result?: CalibrationResult }> {
     const config = await loadConfig(this.configPath);
+    const candidateLimit =
+      config.output?.ambiguous_candidate_limit ?? config.thresholds.candidate_limit ?? 5;
     const datasetFile = opts?.datasetPath ?? join(expandHome(config.state_dir), "queries.json");
     const indexDb = openIndex(expandHome(config.state_dir));
     let indexedSkills: Array<{ skill_id: string; content_sha256: string }>;
@@ -171,7 +173,7 @@ export class LocalAdapter implements TargetAdapter {
         }));
       },
       reranker: clients.rerank,
-      candidateLimit: config.thresholds.candidate_limit,
+      candidateLimit,
       minAutoMatchPrecision: opts?.minAutoMatchPrecision,
       minRetrievalRecallAtK: opts?.minRetrievalRecallAtK,
       minDeliveredShortlistRecallAtK: opts?.minDeliveredShortlistRecallAtK,
@@ -194,7 +196,12 @@ export class LocalAdapter implements TargetAdapter {
         corpus_fingerprint: corpusFingerprint,
         dataset_hash: createHash("sha256").update(datasetText).digest("hex"),
         dataset_provenance: summarizeDatasetProvenance(cases),
-        candidate_limit: config.thresholds.candidate_limit,
+        recall_settings: {
+          k_lexical: config.recall.k_lexical,
+          k_vector: config.recall.k_vector,
+          k_rerank: config.recall.k_rerank ?? Math.min(10, config.recall.k_lexical + config.recall.k_vector),
+        },
+        candidate_limit: candidateLimit,
         min_auto_match_precision: opts?.minAutoMatchPrecision ?? 0.99,
         min_auto_match_count: opts?.minAutoMatchCount ?? 30,
         min_delivered_shortlist_recall_at_k:

package/src/audit.ts

@@ -2,7 +2,7 @@ import type { AuditRow } from "./types";
 
 /** Shape an audit row to exactly the schema's AuditRow fields — nothing extra survives. */
 export function buildAuditRow(row: AuditRow): AuditRow {
-  return {
+  const built: AuditRow = {
     id: row.id,
     ts: row.ts,
     query: row.query,
@@ -12,4 +12,11 @@ export function buildAuditRow(row: AuditRow): AuditRow {
     selected_skill_id: row.selected_skill_id,
     latency_ms: row.latency_ms,
   };
+  if (row.degraded_from !== undefined && row.degraded_from !== null) {
+    built.degraded_from = row.degraded_from;
+  }
+  if (row.degradation_reason !== undefined && row.degradation_reason !== null) {
+    built.degradation_reason = row.degradation_reason;
+  }
+  return built;
 }

package/src/calibrate.ts

@@ -867,6 +867,11 @@ export interface CalibrationRunRecord {
   embedding_fingerprint: string;
   corpus_fingerprint: string;
   dataset_hash: string;
+  recall_settings?: {
+    k_lexical: number;
+    k_vector: number;
+    k_rerank: number;
+  };
   dataset_provenance?: DatasetProvenanceSummary;
   candidate_limit: number;
   attempt_count?: number;
@@ -963,6 +968,9 @@ export function openCalibrateDb(stateDir: string): Database {
   if (!columns.some((column) => column.name === "imported_labelled_case_count")) {
     db.run("ALTER TABLE calibration_runs ADD COLUMN imported_labelled_case_count INTEGER NOT NULL DEFAULT 0");
   }
+  if (!columns.some((column) => column.name === "recall_settings")) {
+    db.run("ALTER TABLE calibration_runs ADD COLUMN recall_settings TEXT NOT NULL DEFAULT '{}'");
+  }
   return db;
 }
 
@@ -980,8 +988,9 @@ export function insertCalibrationRun(db: Database, run: CalibrationRunRecord): v
       attempt_count, min_auto_match_precision, min_auto_match_count,
       min_delivered_shortlist_recall_at_k, min_shortlist_recall_at_5, failed_reason,
       selected_thresholds, tune_metrics, test_metrics, observations,
-      dataset_provenance, human_labelled_case_count, imported_labelled_case_count
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      dataset_provenance, human_labelled_case_count, imported_labelled_case_count,
+      recall_settings
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
     [
       run.run_id,
       run.created_at,
@@ -1004,6 +1013,7 @@ export function insertCalibrationRun(db: Database, run: CalibrationRunRecord): v
       JSON.stringify(run.dataset_provenance ?? {}),
       run.dataset_provenance?.human_labelled_case_count ?? 0,
       run.dataset_provenance?.imported_labelled_case_count ?? 0,
+      JSON.stringify(run.recall_settings ?? {}),
     ],
   );
 }
@@ -1030,6 +1040,7 @@ interface RawCalibrationRow {
   dataset_provenance: string;
   human_labelled_case_count: number;
   imported_labelled_case_count: number;
+  recall_settings: string;
 }
 
 function parseMetrics(json: string): CalibrationMetrics {
@@ -1064,6 +1075,10 @@ function rowToRecord(row: RawCalibrationRow): CalibrationRunRecord {
     embedding_fingerprint: row.embedding_fingerprint,
     corpus_fingerprint: row.corpus_fingerprint,
     dataset_hash: row.dataset_hash,
+    recall_settings:
+      Object.keys(JSON.parse(row.recall_settings) as object).length > 0
+        ? JSON.parse(row.recall_settings) as CalibrationRunRecord["recall_settings"]
+        : undefined,
     dataset_provenance:
       Object.keys(JSON.parse(row.dataset_provenance) as object).length > 0
         ? JSON.parse(row.dataset_provenance) as DatasetProvenanceSummary

package/src/cli.ts

@@ -15,6 +15,7 @@ import {
 } from "./config";
 import { openIndex } from "./db";
 import { diagnose } from "./doctor";
+import { getEffectiveConfig } from "./config-service";
 import { evalVault } from "./eval";
 import {
   assessClientReadiness,
@@ -745,7 +746,8 @@ async function runEval(options: { isJson: boolean }): Promise<void> {
 }
 
 async function runDoctor(options: { isJson: boolean }): Promise<void> {
-  const report = await diagnose(await loadConfig());
+  const effective = await getEffectiveConfig(resolveConfigPath());
+  const report = await diagnose(effective.effective, process.env, effective.sources);
   emitSuccess({ isJson: options.isJson }, report, () => {
     console.log(`version: ${report.version}`);
     console.log(`runtime: ${report.runtime}`);

package/src/clients.ts

@@ -212,6 +212,17 @@ async function fetchRerankerScores(
     });
   } catch (error) {
     if (error instanceof RemoteInferenceError) throw error;
+    const isTimeout =
+      (error as { name?: string })?.name === "TimeoutError" ||
+      (error as { name?: string })?.name === "AbortError" ||
+      String(error).toLowerCase().includes("timeout") ||
+      String(error).toLowerCase().includes("aborted");
+    if (isTimeout) {
+      throw new RemoteInferenceError(
+        "availability",
+        `reranker adapter "${reranker.adapter}" request timed out`,
+      );
+    }
     throw new RemoteInferenceError(
       "availability",
       `reranker adapter "${reranker.adapter}" request failed`,
@@ -302,6 +313,14 @@ export function createClients(config: Config): Clients {
         });
       } catch (error) {
         if (error instanceof RemoteInferenceError) throw error;
+        const isTimeout =
+          (error as { name?: string })?.name === "TimeoutError" ||
+          (error as { name?: string })?.name === "AbortError" ||
+          String(error).toLowerCase().includes("timeout") ||
+          String(error).toLowerCase().includes("aborted");
+        if (isTimeout) {
+          throw new RemoteInferenceError("availability", "embedding endpoint request timed out");
+        }
         throw new RemoteInferenceError("availability", "embedding endpoint request failed");
       }
       if (!response.ok) throw httpFailure("embedding endpoint", response.status);

package/src/commands/config.ts

@@ -124,9 +124,22 @@ export async function handleConfigCommand(
   }
 
   if (sub === "show") {
+    const withSources = args.includes("--sources");
     const data = await adapter.getConfigShow();
     emitSuccess({ isJson: ctx.isJson, target: ctx.target }, data, () => {
       renderTargetBanner(ctx.target);
+      if (withSources) {
+        const policy =
+          data.effective.config?.environment_overrides === false
+            ? "strict (TOML authoritative)"
+            : "permissive (environment overrides enabled)";
+        console.log(`Policy: ${policy}`);
+        console.log("\nSources:");
+        for (const [k, src] of Object.entries(data.sources)) {
+          console.log(`  ${k}: ${src}`);
+        }
+        console.log("\nEffective Configuration:");
+      }
       console.log(JSON.stringify(data.effective, null, 2));
     });
     return;

package/src/config-service.ts

@@ -55,9 +55,12 @@ export const RESTART_REQUIRED_KEYS = [
 ];
 
 export const RELOADABLE_KEYS = [
+  "config.environment_overrides",
   "vault_path",
   "recall.k_lexical",
   "recall.k_vector",
+  "recall.k_rerank",
+  "output.ambiguous_candidate_limit",
   "thresholds.candidate_limit",
   "thresholds.match_score",
   "thresholds.match_margin",
@@ -138,12 +141,16 @@ export async function getEffectiveConfig(configPath?: string): Promise<{
   }
 
   const sources: ConfigSourceMap = {};
+  const allowEnvOverrides = effective.config?.environment_overrides !== false;
 
   const allKeys = [
+    "config.environment_overrides",
     "vault_path",
     "state_dir",
     "recall.k_lexical",
     "recall.k_vector",
+    "recall.k_rerank",
+    "output.ambiguous_candidate_limit",
     "thresholds.candidate_limit",
     "thresholds.match_score",
     "thresholds.match_margin",
@@ -164,6 +171,7 @@ export async function getEffectiveConfig(configPath?: string): Promise<{
     "inference.timeout_ms",
     "server.auth_enabled",
     "server.auth_token_env",
+    "server.allowed_origins",
     "server.admin.enabled",
     "server.admin.token_env",
     "server.hostname",
@@ -173,7 +181,7 @@ export async function getEffectiveConfig(configPath?: string): Promise<{
   ];
 
   for (const key of allKeys) {
-    if (isEnvMasked(key)) {
+    if (isEnvMasked(key, allowEnvOverrides)) {
       sources[key] = "environment";
     } else if (getNestedValue(rawToml, key) !== undefined) {
       sources[key] = "toml";
@@ -185,21 +193,35 @@ export async function getEffectiveConfig(configPath?: string): Promise<{
   return { effective, sources, rawToml };
 }
 
-export function isEnvMasked(key: string): boolean {
-  if (key === "vault_path" && process.env.VAULT_PATH) return true;
-  if (key === "state_dir" && process.env.STATE_DIR) return true;
+export function isEnvMasked(key: string, allowEnvOverrides: boolean = true): boolean {
+  if (!allowEnvOverrides) return false;
+  if (key === "vault_path" && (process.env.SKILLMUX_VAULT_PATH || process.env.SKILL_ROUTER_VAULT_PATH || process.env.VAULT_PATH)) return true;
+  if (key === "state_dir" && (process.env.SKILLMUX_STATE_DIR || process.env.SKILL_ROUTER_STATE_DIR || process.env.STATE_DIR)) return true;
+  if (key === "recall.k_lexical" && (process.env.SKILLMUX_RECALL_K_LEXICAL || process.env.RECALL_K_LEXICAL)) return true;
+  if (key === "recall.k_vector" && (process.env.SKILLMUX_RECALL_K_VECTOR || process.env.RECALL_K_VECTOR)) return true;
+  if (key === "recall.k_rerank" && (process.env.SKILLMUX_RECALL_K_RERANK || process.env.RECALL_K_RERANK)) return true;
+  if (
+    (key === "output.ambiguous_candidate_limit" || key === "thresholds.candidate_limit") &&
+    (process.env.SKILLMUX_OUTPUT_AMBIGUOUS_CANDIDATE_LIMIT ||
+      process.env.AMBIGUOUS_CANDIDATE_LIMIT ||
+      process.env.SKILLMUX_CANDIDATE_LIMIT ||
+      process.env.CANDIDATE_LIMIT)
+  ) {
+    return true;
+  }
   if (key === "inference.models_dir" && (process.env.SKILLMUX_MODELS_DIR || process.env.SKILL_ROUTER_MODELS_DIR)) return true;
-  if (key === "inference.embedding.device" && process.env.EMBED_DEVICE) return true;
-  if (key === "inference.embedding.dtype" && process.env.EMBED_DTYPE) return true;
-  if (key === "inference.embedding.endpoint" && (process.env.SKILLMUX_EMBED_ENDPOINT || process.env.EMBED_ENDPOINT)) return true;
-  if (key === "inference.embedding.model" && (process.env.SKILLMUX_EMBED_MODEL || process.env.EMBED_MODEL)) return true;
-  if (key === "inference.embedding.dimension" && (process.env.SKILLMUX_EMBED_DIMENSION || process.env.EMBED_DIMENSION)) return true;
-  if (key === "inference.reranker.adapter" && (process.env.SKILLMUX_RERANK_ADAPTER || process.env.RERANK_ADAPTER)) return true;
-  if (key === "inference.reranker.endpoint" && (process.env.SKILLMUX_RERANK_ENDPOINT || process.env.RERANK_ENDPOINT)) return true;
-  if (key === "inference.reranker.model" && (process.env.SKILLMUX_RERANK_MODEL || process.env.RERANK_MODEL)) return true;
-  if (key === "server.auth_enabled" && process.env.HTTP_AUTH_ENABLED) return true;
-  if (key === "server.auth_token_env" && process.env.HTTP_AUTH_TOKEN_ENV) return true;
-  if (key === "server.hostname" && process.env.HTTP_HOSTNAME) return true;
+  if (key === "inference.embedding.device" && (process.env.SKILLMUX_EMBED_DEVICE || process.env.EMBED_DEVICE)) return true;
+  if (key === "inference.embedding.dtype" && (process.env.SKILLMUX_EMBED_DTYPE || process.env.EMBED_DTYPE)) return true;
+  if (key === "inference.embedding.endpoint" && (process.env.SKILLMUX_EMBED_ENDPOINT || process.env.SKILL_ROUTER_EMBED_ENDPOINT || process.env.EMBED_ENDPOINT)) return true;
+  if (key === "inference.embedding.model" && (process.env.SKILLMUX_EMBED_MODEL || process.env.SKILL_ROUTER_EMBED_MODEL || process.env.EMBED_MODEL)) return true;
+  if (key === "inference.embedding.dimension" && (process.env.SKILLMUX_EMBED_DIMENSION || process.env.SKILL_ROUTER_EMBED_DIMENSION || process.env.EMBED_DIMENSION)) return true;
+  if (key === "inference.reranker.adapter" && (process.env.SKILLMUX_RERANK_ADAPTER || process.env.SKILL_ROUTER_RERANK_ADAPTER || process.env.RERANK_ADAPTER)) return true;
+  if (key === "inference.reranker.endpoint" && (process.env.SKILLMUX_RERANK_ENDPOINT || process.env.SKILL_ROUTER_RERANK_ENDPOINT || process.env.RERANK_ENDPOINT)) return true;
+  if (key === "inference.reranker.model" && (process.env.SKILLMUX_RERANK_MODEL || process.env.SKILL_ROUTER_RERANK_MODEL || process.env.RERANK_MODEL)) return true;
+  if (key === "server.auth_enabled" && (process.env.SKILLMUX_HTTP_AUTH_ENABLED || process.env.HTTP_AUTH_ENABLED)) return true;
+  if (key === "server.auth_token_env" && (process.env.SKILLMUX_HTTP_AUTH_TOKEN_ENV || process.env.HTTP_AUTH_TOKEN_ENV)) return true;
+  if (key === "server.allowed_origins" && (process.env.SKILLMUX_HTTP_ALLOWED_ORIGINS || process.env.HTTP_ALLOWED_ORIGINS)) return true;
+  if (key === "server.hostname" && (process.env.SKILLMUX_HTTP_HOSTNAME || process.env.HTTP_HOSTNAME)) return true;
   if (key === "server.rate_limit.enabled" && (process.env.SKILLMUX_HTTP_RATE_LIMIT_ENABLED || process.env.HTTP_RATE_LIMIT_ENABLED)) return true;
   if (key === "server.rate_limit.requests_per_minute" && (process.env.SKILLMUX_HTTP_RATE_LIMIT_RPM || process.env.HTTP_RATE_LIMIT_RPM)) return true;
   if (key === "server.rate_limit.trust_proxy" && (process.env.SKILLMUX_HTTP_RATE_LIMIT_TRUST_PROXY || process.env.HTTP_RATE_LIMIT_TRUST_PROXY)) return true;
@@ -208,10 +230,13 @@ export function isEnvMasked(key: string): boolean {
 
 export function validateDottedKey(key: string): void {
   const allowed = new Set([
+    "config.environment_overrides",
     "vault_path",
     "state_dir",
     "recall.k_lexical",
     "recall.k_vector",
+    "recall.k_rerank",
+    "output.ambiguous_candidate_limit",
     "thresholds.candidate_limit",
     "thresholds.match_score",
     "thresholds.match_margin",
@@ -253,6 +278,8 @@ export function parseDottedValue(key: string, valueStr: string): unknown {
   const numberKeys = new Set([
     "recall.k_lexical",
     "recall.k_vector",
+    "recall.k_rerank",
+    "output.ambiguous_candidate_limit",
     "thresholds.candidate_limit",
     "thresholds.match_score",
     "thresholds.match_margin",
@@ -271,6 +298,7 @@ export function parseDottedValue(key: string, valueStr: string): unknown {
   }
 
   const booleanKeys = new Set([
+    "config.environment_overrides",
     "server.auth_enabled",
     "server.admin.enabled",
     "server.rate_limit.enabled",

package/src/config-watcher.ts

@@ -11,12 +11,15 @@ import type { Config } from "./types";
 // ---------------------------------------------------------------------------
 
 export const LIVE_RELOAD_KEYS = new Set([
+  "config.environment_overrides",
   "inference.thresholds.match_score",
   "inference.thresholds.match_margin",
   "inference.thresholds.candidate_floor",
   "inference.calibration.run_id",
   "recall.k_lexical",
   "recall.k_vector",
+  "recall.k_rerank",
+  "output.ambiguous_candidate_limit",
   "thresholds.candidate_limit",
   "inference.embedding.endpoint",
   "inference.embedding.api_key_env",