@pellux/goodvibes-tui 1.16.0 → 1.17.0

package/src/daemon/lifecycle.ts

@@ -0,0 +1,41 @@
+/**
+ * lifecycle.ts — resolve THIS binary's update-artifact identity for the SDK
+ * DaemonServer facade's auto-update lifecycle.
+ *
+ * The SDK facade now runs the entire self-update loop itself when handed a
+ * DaemonUpdateArtifact ({version, execPath}): it compares the HOST binary's
+ * version against the release tags (no longer the version-blind sdk-package
+ * comparison that used to restart-loop), swaps only at an idle moment, keeps
+ * the outgoing file at `<path>.previous`, and leaves a receipt in the store it
+ * serves on /status. When the artifact is ABSENT, updates are host-managed —
+ * the facade runs no loop (the safe embedded default).
+ *
+ * The one guard the facade does NOT apply is install-kind: it must never swap a
+ * dev `bun run daemon` interpreter or a bun-global package install. This helper
+ * is that guard — it hands the facade an artifact ONLY for a compiled binary
+ * install, so a dev run resolves to `undefined` (host-managed, no loop) and
+ * only a real self-contained binary self-updates.
+ */
+import type { DaemonUpdateArtifact } from '@pellux/goodvibes-sdk/platform/daemon';
+import { VERSION } from '../version.ts';
+import { detectInstallKind } from '../runtime/update-check.ts';
+
+export interface ResolveDaemonUpdateArtifactOptions {
+  /** The executable to identify; defaults to process.execPath. */
+  readonly execPath?: string;
+  /** Injectable so tests pin a fixture version — never the live build VERSION. */
+  readonly version?: string;
+}
+
+/**
+ * The update-artifact identity to hand the DaemonServer facade, or `undefined`
+ * for a non-binary install (dev/source or bun-global package) — in which case
+ * the facade keeps updates host-managed and runs no swap loop.
+ */
+export function resolveDaemonUpdateArtifact(
+  options: ResolveDaemonUpdateArtifactOptions = {},
+): DaemonUpdateArtifact | undefined {
+  const execPath = options.execPath ?? process.execPath;
+  if (detectInstallKind(execPath) !== 'binary') return undefined;
+  return { version: options.version ?? VERSION, execPath };
+}

package/src/daemon/service-commands.ts

@@ -290,7 +290,7 @@ export async function runDaemonServiceCli(input: DaemonServiceCliInput): Promise
           ok: false,
           exitCode: 1,
           lines: [
-            `service install refused: a service is already installed under the legacy name ${LEGACY_SERVICE_UNIT_NAME}.service.`,
+            `service install refused: a service is already installed as ${LEGACY_SERVICE_UNIT_NAME}.service (the unit name the goodvibes install script manages).`,
             legacyUnitNote(legacy, resolvedName),
             `Installing this tool's ${resolvedName}.service alongside it risks two daemons competing for the same port.`,
           ],
@@ -313,10 +313,10 @@ export async function runDaemonServiceCli(input: DaemonServiceCliInput): Promise
       if (uninstalled.actionError) return failed('uninstall', uninstalled);
       const extra: string[] = [];
       if (stopped.actionError) extra.push(`(it may not have been running: ${stopped.actionError})`);
-      // W3 Finding 4: this command only ever touches the TRACKED unit
-      // (whatever name/path actually resolved — not necessarily the
-      // SERVICE_NAME constant) above — say so explicitly when a legacy unit
-      // also exists, so its continued presence is never a silent surprise.
+      // This command only ever touches the TRACKED unit (whatever name/path
+      // actually resolved — not necessarily the SERVICE_NAME constant) above —
+      // say so explicitly when an install-script unit also exists, so its
+      // continued presence is never a silent surprise.
       if (legacy.present) extra.push(legacyUnitNote(legacy, resolveManagedUnitName(uninstalled)));
       return ok('uninstall', uninstalled, extra);
     }

package/src/export/cost-utils.ts

@@ -15,18 +15,30 @@
 //      honest "unpriced" state instead of a silent $0.
 // ---------------------------------------------------------------------------
 
-import type { CatalogModel } from '@pellux/goodvibes-sdk/platform/providers';
+import { computeUsageCostUsd, type CatalogModel, type ResolvedModelPricing } from '@pellux/goodvibes-sdk/platform/providers';
 
 export interface ModelPricing {
   input: number;
   output: number;
 }
 
+/**
+ * Where a resolved price came from, for the render-side source distinction:
+ * 'user' = the manual pricing.modelPrices entry ("your price"), 'provider' =
+ * served by the provider API, 'catalog' = the live model catalog (dated),
+ * 'fallback' = this module's small built-in safety net.
+ */
+export type PricingSourceKind = 'user' | 'provider' | 'catalog' | 'fallback';
+
 /** Result of a pricing lookup: the resolved (possibly zero) price, and whether it's real. */
 export interface PricingResult {
   pricing: ModelPricing;
-  /** False when no source (catalog or static fallback) recognized the model — the zero pricing is a placeholder, not a real price. */
+  /** False when no source recognized the model — the zero pricing is a placeholder, not a real price. */
   priced: boolean;
+  /** Which source priced the model (present only when priced). */
+  source?: PricingSourceKind;
+  /** ISO date (YYYY-MM-DD) of the catalog/provider snapshot the price came from, when known. */
+  asOf?: string;
 }
 
 // Hand-maintained safety net, used only when the live catalog has no source
@@ -61,7 +73,7 @@ const STATIC_FALLBACK_PRICING: Record<string, ModelPricing> = {
 
 // Module-level injection point. Kept as a bare singleton (not threaded through
 // call sites) because the 9 existing consumers are pure functions with no
-// ProviderRegistry in scope; see WO-315 brief for the tradeoff. Tests that
+// ProviderRegistry in scope; see brief for the tradeoff. Tests that
 // never call setPricingSource() fall through to the static-fallback path,
 // which keeps them isolated from catalog state by default.
 let pricingSource: (() => readonly CatalogModel[]) | null = null;
@@ -71,6 +83,34 @@ export function setPricingSource(source: (() => readonly CatalogModel[]) | null)
   pricingSource = source;
 }
 
+// The ONE model pricing resolver (manual pricing.modelPrices -> registration
+// -> provider-served -> catalog -> honest unknown), wired from
+// bootstrap-core.ts as ProviderRegistry.resolveModelPricing once the runtime
+// exists. When set, it is consulted FIRST so a manual price the user sets is
+// visible to every cost surface immediately; the legacy catalog/static chain
+// below remains the fallback for resolver-unknown models and for surfaces
+// (tests, headless) that never wire a registry.
+let modelPricingResolver: ((modelId: string) => ResolvedModelPricing) | null = null;
+
+/** Wire (or clear, with null) the registry's resolveModelPricing as the primary pricing source. */
+export function setModelPricingResolver(resolver: ((modelId: string) => ResolvedModelPricing) | null): void {
+  modelPricingResolver = resolver;
+}
+
+/**
+ * One-call bootstrap wiring: the live catalog as the legacy source AND the
+ * registry's ONE pricing resolver (manual pricing.modelPrices -> registration
+ * -> provider-served -> catalog -> honest unknown) as the primary, so every
+ * cost surface sees a manually-set price immediately and can name its source.
+ */
+export function wireCostPricing(registry: {
+  getRawCatalogModels(): readonly CatalogModel[];
+  resolveModelPricing(modelRef: string): ResolvedModelPricing;
+}): void {
+  setPricingSource(() => registry.getRawCatalogModels());
+  setModelPricingResolver((modelId) => registry.resolveModelPricing(modelId));
+}
+
 function findInCatalog(modelId: string, models: readonly CatalogModel[]): ModelPricing | null {
   const exact = models.find((m) => m.id === modelId);
   if (exact) return exact.tier === 'free' ? { input: 0, output: 0 } : exact.pricing;
@@ -97,20 +137,60 @@ function findInStaticFallback(modelId: string): ModelPricing | null {
  * header for the full resolution order.
  */
 export function resolvePricing(modelId: string): PricingResult {
-  if (modelId.endsWith(':free')) return { pricing: { input: 0, output: 0 }, priced: true };
+  if (modelId.endsWith(':free')) return { pricing: { input: 0, output: 0 }, priced: true, source: 'catalog' };
+
+  // The ONE resolver first: manual price -> registration -> provider-served
+  // -> catalog. A 'priced' answer carries its source (and snapshot date when
+  // known) so render surfaces can say "your price" vs "catalog price, as of
+  // <date>". Unknown/subscription answers fall through to the legacy chain
+  // so nothing regresses while the catalog is still loading.
+  if (modelPricingResolver) {
+    const resolved = modelPricingResolver(modelId);
+    if (resolved.status === 'priced') {
+      return {
+        pricing: { input: resolved.rates.inputPerMTok, output: resolved.rates.outputPerMTok },
+        priced: true,
+        source: resolved.source,
+        ...(resolved.asOf ? { asOf: resolved.asOf } : {}),
+      };
+    }
+  }
 
   const models = pricingSource?.() ?? [];
   const catalogHit = findInCatalog(modelId, models);
-  if (catalogHit) return { pricing: catalogHit, priced: true };
+  if (catalogHit) return { pricing: catalogHit, priced: true, source: 'catalog' };
 
   const fallbackHit = findInStaticFallback(modelId);
-  if (fallbackHit) return { pricing: fallbackHit, priced: true };
+  if (fallbackHit) return { pricing: fallbackHit, priced: true, source: 'fallback' };
 
   // Genuinely unknown — no source recognizes this model. Report honestly
   // rather than collapsing into the same zero a free model would return.
   return { pricing: { input: 0, output: 0 }, priced: false };
 }
 
+/**
+ * The render-side source distinction for a priced model: "your price" for a
+ * manual pricing.modelPrices entry, "catalog price, as of <date>" (or
+ * provider-served/built-in equivalents) otherwise. Null when the model is
+ * unpriced — callers render the explicit "price unknown" marker instead.
+ */
+export function describePricingSource(modelId: string): string | null {
+  const result = resolvePricing(modelId);
+  if (!result.priced) return null;
+  switch (result.source) {
+    case 'user':
+      return 'your price';
+    case 'provider':
+      return result.asOf ? `provider price, as of ${result.asOf}` : 'provider price';
+    case 'catalog':
+      return result.asOf ? `catalog price, as of ${result.asOf}` : 'catalog price';
+    case 'fallback':
+      return 'built-in price';
+    default:
+      return 'catalog price';
+  }
+}
+
 /**
  * getPricing — resolve USD-per-1M-token pricing for a model ID.
  * Back-compat wrapper over resolvePricing(); returns zero for both genuinely
@@ -146,6 +226,20 @@ export function calcSessionCost(
   cacheWrite: number,
   modelId: string,
 ): number {
+  // Through the ONE resolver when wired: computeUsageCostUsd applies the
+  // source's explicit cache rates (or the published per-provider ratio)
+  // instead of billing cache traffic at the full input rate.
+  if (modelPricingResolver) {
+    const resolved = modelPricingResolver(modelId);
+    if (resolved.status === 'priced') {
+      return computeUsageCostUsd(resolved, {
+        inputTokens,
+        outputTokens,
+        cacheReadTokens: cacheRead,
+        cacheWriteTokens: cacheWrite,
+      }) ?? 0;
+    }
+  }
   const pricing = getPricing(modelId);
   // Cache reads/writes count toward billable input side (same convention as panel)
   const billableInput = inputTokens + cacheRead + cacheWrite;
@@ -195,3 +289,31 @@ export function readBudgetAlertUsd(configGet: (key: string) => unknown): number
   const parsed = typeof raw === 'number' ? raw : Number(raw);
   return Number.isFinite(parsed) && parsed >= 0 ? parsed : BUDGET_ALERT_USD_DEFAULT;
 }
+
+/**
+ * The SDK settings key holding the user's manual per-model prices — the
+ * highest-precedence source in the ONE pricing resolver. Object map of
+ * `provider:model` -> { input, output, cacheRead?, cacheWrite? } in USD per
+ * 1M tokens.
+ */
+export const MODEL_PRICES_CONFIG_KEY = 'pricing.modelPrices';
+
+/**
+ * Persist a manual price for one `provider:model` key into
+ * pricing.modelPrices, preserving every other entry. The registry's resolver
+ * reads the key live per call, so the new price is visible to every cost
+ * surface on the next render — no restart.
+ */
+export function writeManualModelPrice(
+  config: BudgetAlertConfigAccess,
+  modelKey: string,
+  price: { input: number; output: number },
+): void {
+  const current = config.get(MODEL_PRICES_CONFIG_KEY);
+  const map: Record<string, unknown> =
+    current && typeof current === 'object' && !Array.isArray(current)
+      ? { ...(current as Record<string, unknown>) }
+      : {};
+  map[modelKey] = { input: price.input, output: price.output };
+  config.set(MODEL_PRICES_CONFIG_KEY, map);
+}

package/src/input/autocomplete.ts

@@ -19,7 +19,7 @@ export interface AutocompleteState {
   results: AutocompleteResult[];
   selectedIndex: number;
   /**
-   * UX-C (item 4): how many leading entries of `results` belong to the
+   * (item 4): how many leading entries of `results` belong to the
    * curated "common" tier — only meaningful when `query === ''` (0
    * otherwise, since a typed filter searches everything and the common/rest
    * split no longer applies). The renderer uses this to draw a separator
@@ -56,7 +56,7 @@ export class AutocompleteEngine {
     this.state.query = query;
     this.state.results = this.registry.fuzzyMatch(query);
     this.state.active = true;
-    // UX-C: fuzzyMatch('') sorts the curated common tier first (score 2),
+    // fuzzyMatch('') sorts the curated common tier first (score 2),
     // then the alphabetical rest (score 1) — both tiers alphabetical within
     // themselves. Count the leading common run to tell the renderer where to
     // draw the separator. A non-empty query means every command was scored on

package/src/input/command-registry.ts

@@ -56,7 +56,7 @@ export interface CommandRuntimeState {
    * Cumulative count of direct terminal writes the output guard intercepted
    * this session — surfaced by /debug. Optional so the SDK's MutableRuntimeState
    * (which has no such field) stays assignable; the guard sets it lazily on the
-   * shared runtime object. (UX-B item 1a.)
+   * shared runtime object. (item 1a.)
    */
   terminalWritesIntercepted?: number;
 }
@@ -81,6 +81,8 @@ export interface CommandUiActions {
     marker?: string;
   };
   executeCommand?: (name: string, args: string[]) => Promise<boolean>;
+  /** Arm the one-key jump to a spawned CI fix-session (the surface attaches on the jump key; the user never retypes an id). */
+  armFixSessionAttach?: (fixSessionId: string) => void;
   cancelGeneration?: () => void;
   /** True while an LLM turn is actively streaming. Used to give Escape
    *  cancel-turn precedence over a focused panel's own escape handling. */
@@ -139,7 +141,7 @@ export interface CommandShellUiOpeners {
   ) => void;
   openSettingsModal?: (target?: string) => void;
   /**
-   * Open a MIGRATE-TO-MODAL surface by name (W6.1 purge skeleton — WO-A/B
+   * Open a MIGRATE-TO-MODAL surface by name (purge skeleton — B
    * command runtimes call this instead of openCommandPanel once their panel
    * is converted to a ModalFactory config). Threaded from ui-openers.ts the
    * same way openSettingsModal is.
@@ -157,12 +159,21 @@ export interface CommandShellUiOpeners {
    */
   openCommandPalette?: () => void;
   /**
-   * Open (and optionally focus) a panel. UX-C focus rule: the command path is
+   * Command name -> reference-category label, from the same single source of
+   * truth as the generated command reference (categorizeBuiltinCommands),
+   * memoized by the shell. Lets registry-driven surfaces built inside command
+   * handlers (/help) group by category without importing the aggregation
+   * module — a static import there would cycle (commands.ts registers those
+   * very handlers).
+   */
+  getCommandCategories?: () => ReadonlyMap<string, string>;
+  /**
+   * Open (and optionally focus) a panel. focus rule: the command path is
    * "the user is mid-command-flow" — opening a panel this way leaves keyboard
    * focus in the composer by default. Pass `{ focus: true }` for a caller that
    * genuinely wants to grab focus (chords use panelManager.focusPanels()
    * directly instead of this method, so no current call site needs it — but
-   * the intent is explicit rather than implicit here). `target` (DEBT-5) is a
+   * the intent is explicit rather than implicit here). `target` is a
    * fleet deep-link jump target forwarded to PanelManager.open.
    */
   showPanel?: (panelId: string, pane?: 'top' | 'bottom', target?: PanelDeepLinkTarget, opts?: { focus?: boolean }) => void;
@@ -207,7 +218,7 @@ export interface CommandSessionServices {
    * conversation's current message history. Call after a session resume
    * replays historical messages, before the next render, so the footer's
    * token counter reflects the resumed session's real usage instead of a
-   * fresh Orchestrator's zeroed default (W0.9).
+   * fresh Orchestrator's zeroed default.
    */
   readonly hydrateSessionUsage?: () => void;
   /** The orchestration engine's command-facing facade — see runtime/workstream-services.ts. */
@@ -221,7 +232,7 @@ export interface CommandSessionServices {
   /**
    * The MAIN interactive session's per-turn passive-injection
    * honesty ring — `Orchestrator.getTurnInjections()`, the main-session
-   * counterpart to `AgentRecord.turnInjections` (wo801). `/recall injections`
+   * counterpart to `AgentRecord.turnInjections`. `/recall injections`
    * with no agent id reads this. Optional so command contexts built without an
    * orchestrator (headless, tests) fall back to the honest empty state.
    */
@@ -262,7 +273,7 @@ export interface CommandWorkspaceServices
 export interface CommandPlatformConfigServices {
   readonly config: DeepReadonly<GoodVibesConfig>;
   readonly configManager: ConfigManager;
-  /** Feature-flag runtime — backs the `/flags` command's listing and runtime toggling. */
+  /** Capability gate runtime — feature states derive from domain settings keys; surfaces read live/pending state here. */
   readonly featureFlagManager?: FeatureFlagManager;
   readonly voiceProviderRegistry?: VoiceProviderRegistry;
   readonly voiceService?: VoiceService;
@@ -325,11 +336,18 @@ export interface CommandContext
     readonly mcpApi?: McpApi;
     readonly opsApi?: OpsApi;
     readonly transport?: DirectTransport;
+    /**
+     * Durable user-origin permission rules (the persistent form of remembered
+     * approvals). The same in-process store the permission evaluator reads, so
+     * /permissions rules lists and revokes rules that take effect live. Served
+     * by the daemon's permissions.rules.list/.delete verbs to other surfaces.
+     */
+    readonly userPermissionRuleStore?: import('@pellux/goodvibes-sdk/platform/permissions').UserPermissionRuleStore;
   };
 }
 
 /**
- * UX-C palette curation (item 4): the "common" first tier the slash-command
+ * palette curation (item 4): the "common" first tier the slash-command
  * autocomplete dropdown shows before the alphabetical rest when it opens with
  * no filter typed yet (bare '/') — the "132-command palette unranked"
  * evaluator finding. Typed filtering (any non-empty query) is completely
@@ -379,6 +397,13 @@ export class CommandRegistry {
    * statically by the alias lint test).
    */
   register(command: SlashCommand): void {
+    // Every registered command is rendered with its description in /help, the
+    // command palette, and the generated reference (docs/commands-reference.md).
+    // A blank description would ship an unexplained row in all three, so it
+    // fails fast here — the release gate red-tests this invariant.
+    if (!command.description || command.description.trim().length === 0) {
+      throw new Error(`Command registration for "${command.name}" has no description — every command must describe itself.`);
+    }
     const existingByName = this.commands.get(command.name) ?? this.aliasIndex.get(command.name);
     if (existingByName) {
       throw new Error(
@@ -447,7 +472,7 @@ export class CommandRegistry {
       }
 
       if (bestScore > 0 || q === '') {
-        // UX-C: with no query yet, rank the curated common tier (score 2)
+        // with no query yet, rank the curated common tier (score 2)
         // ahead of everything else (score 1) — the tie-break below then sorts
         // each tier alphabetically, so the result is "common tier, then the
         // alphabetical rest" rather than one flat alphabetical list.

package/src/input/commands/ci-runtime.ts

@@ -155,8 +155,12 @@ export function registerCiRuntimeCommands(registry: CommandRegistry): void {
             const result = await rpc.sdk.operator.invoke('ci.watches.run', { watchId: runId });
             const lines = [renderReport(result.report)];
             lines.push(`notified: ${result.notified ? 'yes' : 'no'}${result.notificationId ? ` (${result.notificationId})` : ''}`);
-            lines.push(`fix-session triggered: ${result.fixSessionTriggered ? 'yes' : 'no'}${result.fixSessionId ? ` (${result.fixSessionId})` : ''}`);
+            lines.push(`fix-session triggered: ${result.fixSessionTriggered ? 'yes' : 'no'}`);
             ctx.print(lines.join('\n'));
+            // Route the spawned session through the shared one-key jump affordance
+            // instead of printing the id for the user to retype — same attach flow
+            // as the accepted fix-this card.
+            if (result.fixSessionId) ctx.armFixSessionAttach?.(result.fixSessionId);
           } catch (error) {
             ctx.print(`[ci watches run] ${describeOperatorRpcError(error)}`);
           }

package/src/input/commands/codebase-runtime.ts

@@ -3,7 +3,7 @@
 //
 // Explicit-query + transparency surface over the repo source-tree code index
 // (CodeIndexStore, @pellux/goodvibes-sdk/platform/state, landed on SDK main
-// as wo802/W5.3 Stage A) via the TUI's own wiring in
+// with explicit-query build/status/search) via the TUI's own wiring in
 // src/runtime/code-index-services.ts, threaded through
 // CommandContext.session.codeIndexStore exactly like wrfcController/
 // workstreamEngine already are (bootstrap-command-context.ts).
@@ -14,8 +14,8 @@
 // node while it runs), status (counts, skips, degradation state, last
 // build), search <query> (explicit retrieval, results labeled
 // 'lexical'|'semantic' honestly — never implied as more precise than they
-// are). Stage B (now landed) adds passive auto-injection into coding turns and
-// tool-site incremental reindex; `status` surfaces both honestly (the
+// are). Passive auto-injection into coding turns and tool-site incremental
+// reindex followed later; `status` surfaces both honestly (the
 // auto-injection flag+setting gate, and the last reindex activity).
 // ---------------------------------------------------------------------------
 
@@ -35,7 +35,7 @@ function formatBytes(bytes: number): string {
 }
 
 /**
- * Honest one-line auto-injection state (Stage B): both the (default-off)
+ * Honest one-line auto-injection state: both the (default-off)
  * `agent-passive-code-injection` feature flag AND storage.codeIndexEnabled must
  * be on for passive code injection to run — state which is off, and why.
  */
@@ -49,7 +49,7 @@ function renderAutoInjectionState(flagEnabled: boolean, settingEnabled: boolean)
   return `  auto-injection: off (${reasons.join('; ')})`;
 }
 
-/** Honest last-reindex activity line (Stage B tool-site incremental reindex). */
+/** Honest last-reindex activity line (tool-site incremental reindex). */
 function renderReindexActivity(activity: CodeIndexReindexActivity | null, now: number): string {
   if (!activity) return '  last reindex: none this session (writes/edits reindex touched files once the index is built)';
   const agoSec = Math.max(0, Math.round((now - activity.at) / 1000));
@@ -82,7 +82,7 @@ function renderCodeIndexStatus(stats: CodeIndexStats, configManager: Pick<Config
   lines.push(
     `  auto-build on startup: ${autoStart ? 'on' : 'off'} (storage.codeIndexEnabled, default off — /config to change)`,
   );
-  // Stage B surfacing: passive code auto-injection state (flag + setting) and the last tool-site reindex.
+  // Passive code auto-injection state (flag + setting) and the last tool-site reindex.
   lines.push(renderAutoInjectionState(extras.flagEnabled, autoStart));
   lines.push(renderReindexActivity(extras.reindexActivity, extras.now ?? Date.now()));
   lines.push(

package/src/input/commands/cost-runtime.ts

@@ -11,7 +11,7 @@ import {
 } from './cost-attribution-format.ts';
 
 /**
- * /cost budget <usd> — makes the CostTrackerPanel's budget alert real (WO-139).
+ * /cost budget <usd> — makes the CostTrackerPanel's budget alert real.
  * Opens the cost panel (creating it via the registered factory if not already
  * open) and sets its budget threshold directly, so the meter+alert already
  * built into CostTrackerPanel.render() (:266-290) actually fires. 0 disables

package/src/input/commands/health-runtime.ts

@@ -48,7 +48,7 @@ export function registerHealthRuntimeCommands(registry: CommandRegistry): void {
       const readModels = requireReadModels(ctx);
 
       if (sub === 'open' || sub === 'panel' || sub === 'provider') {
-        ctx.openModal?.('providers-modal'); // W6.1: provider-health panel -> config modal
+        ctx.openModal?.('providers-modal'); // provider-health panel -> config modal
         return;
       }
 
@@ -477,7 +477,7 @@ export function registerHealthRuntimeCommands(registry: CommandRegistry): void {
 
       ctx.print([
         'Health Review',
-        // DEBT-5 item 3: /health stays a cross-domain transcript report (it
+        // item 3: /health stays a cross-domain transcript report (it
         // genuinely spans settings/accounts/auth/sandbox/etc — no single
         // modal owns this data), but the providers domain DOES have one, so
         // point at it honestly. "/provider" (no domain) is a DIFFERENT

package/src/input/commands/intelligence-runtime.ts

@@ -55,7 +55,7 @@ export function registerIntelligenceRuntimeCommands(registry: CommandRegistry):
     async handler(args, ctx) {
       const sub = (args[0] ?? 'review').toLowerCase();
       if (sub === 'panel' || sub === 'open') {
-        // W6.1 (the purge): 'intelligence'/IntelligencePanel was
+        // (the purge): 'intelligence'/IntelligencePanel was
         // DELETE-disposition (no surviving human surface — its read model
         // stays and still backs every subcommand below). There is no alias
         // to resolve through, so this prints an honest notice and opens

package/src/input/commands/local-auth-runtime.ts

@@ -10,7 +10,7 @@ export function handleLocalAuthCommand(args: string[], ctx: CommandContext): voi
   const sub = (args[0] ?? 'review').toLowerCase();
   const auth = requireLocalUserAuthManager(ctx);
   if (sub === 'panel' || sub === 'open') {
-    // W6.1: browse view moved to local-auth-modal. The LocalAuthPanel itself is
+    // browse view moved to local-auth-modal. The LocalAuthPanel itself is
     // kept (masked password-entry host) but is no longer the /local-auth panel
     // destination — masked entry is reached via add-user/rotate-password below.
     ctx.openModal?.('local-auth-modal');

package/src/input/commands/local-provider-runtime.ts

@@ -4,29 +4,35 @@ import { writeFile, unlink } from 'node:fs/promises';
 import type { CommandRegistry } from '../command-registry.ts';
 import { fetchModelContextWindows } from '@pellux/goodvibes-sdk/platform/discovery';
 import type { CustomProviderConfig } from '@pellux/goodvibes-sdk/platform/providers';
-import { requireProviderApi, requireShellPaths } from './runtime-services.ts';
+import { requireProviderApi, requireSecretsManager, requireShellPaths } from './runtime-services.ts';
+import { ensureProviderKeyThenSelect } from '../provider-key-intake.ts';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 
 function isValidProviderName(name: string): boolean {
   return /^[a-zA-Z0-9_-]+$/.test(name);
 }
 
+/** Conventional secrets-store key a custom provider reads its API key from. */
+function customProviderKeyName(providerName: string): string {
+  return `${providerName.replace(/[^A-Za-z0-9]/g, '_').toUpperCase()}_API_KEY`;
+}
+
 export function registerLocalProviderRuntimeCommands(registry: CommandRegistry): void {
   registry.register({
     name: 'provider',
     aliases: ['p'],
     description: 'Switch provider or manage custom providers (add/remove)',
-    usage: '[add <name> <baseURL> [apiKey] | remove <name> | <provider-name>]',
+    usage: '[add <name> <baseURL> | remove <name> | <provider-name>]',
     argsHint: '[add|remove|name]',
     async handler(args, ctx) {
       const shellPaths = requireShellPaths(ctx);
       if (args[0] === 'add') {
         const addArgs = args.slice(1);
         if (addArgs.length < 2) {
-          ctx.print('Usage: /provider add <name> <baseURL> [apiKey]\nExample: /provider add my-server http://192.168.0.85:8001/v1');
+          ctx.print('Usage: /provider add <name> <baseURL>\nExample: /provider add my-server http://192.168.0.85:8001/v1\nAfter the provider is created you can enter its API key with the keystrokes masked (or skip it for keyless endpoints).');
           return;
         }
-        const [name, baseURL, apiKey] = addArgs;
+        const [name, baseURL] = addArgs;
         if (!isValidProviderName(name)) {
           ctx.print('Error: Provider name must contain only letters, numbers, hyphens, and underscores.');
           return;
@@ -51,7 +57,6 @@ export function registerLocalProviderRuntimeCommands(registry: CommandRegistry):
           const controller = new AbortController();
           const timeoutId = setTimeout(() => controller.abort(), 5000);
           const headers: Record<string, string> = { 'Content-Type': 'application/json' };
-          if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`;
           const res = await fetch(`${baseURL}/models`, { signal: controller.signal, headers });
           clearTimeout(timeoutId);
           if (res.ok) {
@@ -91,12 +96,16 @@ export function registerLocalProviderRuntimeCommands(registry: CommandRegistry):
               contextWindow: contextWindows[id] ?? 8192,
               capabilities: { toolCalling: true, codeEditing: true, reasoning: false, multimodal: false },
             }));
+        // The key is never embedded in the provider JSON. The config references
+        // it by name (apiKeyEnv) and the actual value lands in the secrets
+        // manager below, resolved live at request time.
+        const keyName = customProviderKeyName(name);
         const config: CustomProviderConfig = {
           name,
           displayName: name,
           type: 'openai-compat',
           baseURL,
-          ...(apiKey ? { apiKey } : {}),
+          apiKeyEnv: keyName,
           models,
         };
         try {
@@ -107,6 +116,32 @@ export function registerLocalProviderRuntimeCommands(registry: CommandRegistry):
           return;
         }
         ctx.print(`Provider '${name}' added with ${models.length} model(s):\n${discoveredModelIds.length > 0 ? discoveredModelIds.map((id) => `  • ${id} (${(contextWindows[id] ?? 8192).toLocaleString()} ctx)`).join('\n') : `  • ${defaultModel} (starter entry)`}\nThe file watcher will auto-register it shortly.`);
+        // Capture the key with the keystrokes masked, straight into the secrets
+        // manager — never a cleartext argument, never written into the JSON.
+        if (ctx.beginConcealedInput) {
+          const secretsManager = requireSecretsManager(ctx);
+          ctx.print(`Enter the API key for provider '${name}' (input is masked; press Enter to store, Esc to skip if the endpoint needs no key).`);
+          ctx.beginConcealedInput({
+            label: name,
+            onSubmit: (value) => {
+              if (value.length === 0) {
+                ctx.print(`No key stored for '${name}' (endpoint used without a key).`);
+                return;
+              }
+              void (async () => {
+                try {
+                  await secretsManager.set(keyName, value, { scope: 'user', medium: 'secure' });
+                  ctx.print(`Stored the API key for '${name}' (value hidden). It resolves live for this provider — no restart needed.`);
+                } catch (error) {
+                  ctx.print(`Could not store the key for '${name}': ${summarizeError(error)}`);
+                }
+              })();
+            },
+            onCancel: () => {
+              ctx.print(`No key stored for '${name}' (endpoint used without a key).`);
+            },
+          });
+        }
         return;
       }
 
@@ -157,10 +192,14 @@ export function registerLocalProviderRuntimeCommands(registry: CommandRegistry):
       }
       try {
         const selected = await providerApi.selectModel(match.registryKey);
-        ctx.session.runtime.model = selected.registryKey;
-        ctx.session.runtime.provider = selected.providerId;
-        ctx.platform.configManager.set('provider.model', selected.registryKey);
-        ctx.print(`Switched to provider: ${selected.providerId} (model: ${selected.modelId})`);
+        // Unconfigured provider selected → capture its key inline, then finish
+        // the switch so it lands ready to chat.
+        ensureProviderKeyThenSelect(ctx, selected.providerId, () => {
+          ctx.session.runtime.model = selected.registryKey;
+          ctx.session.runtime.provider = selected.providerId;
+          ctx.platform.configManager.set('provider.model', selected.registryKey);
+          ctx.print(`Switched to provider: ${selected.providerId} (model: ${selected.modelId})`);
+        });
       } catch (e) {
         ctx.print(`Error: ${summarizeError(e)}`);
       }