riskmodels 2.0.0 → 2.0.2

package/README.md

@@ -8,10 +8,12 @@ Command-line interface for [RiskModels](https://riskmodels.app): call the REST A
 npm install -g riskmodels
 ```
 
-Agent-first installer preview:
+Agent-first installer (pin `@latest` so `npx` does not resolve a stale cached package):
 
 ```bash
-RISKMODELS_API_KEY=rm_agent_live_... npx riskmodels install
+# Prerequisites: Node.js LTS (includes npx). macOS/Homebrew: brew install node; others: https://nodejs.org
+RISKMODELS_API_KEY=rm_agent_live_... npx -y riskmodels@latest install --dry-run   # optional: inspect plan first
+RISKMODELS_API_KEY=rm_agent_live_... npx -y riskmodels@latest install
 ```
 
 Local development can run the same flow with:
@@ -101,4 +103,4 @@ Publishing (`npm publish`, version bumps, npm login / tokens) is **not** documen
 
 **Rule of thumb:** run publish commands only from **`cli/`**; the repo root package is the Next.js portal, not this CLI.
 
-The legacy `riskmodels-cli` npm package remains a backward-compatible published artifact. New releases from this directory target the unscoped `riskmodels` package for `npx riskmodels install`.
+The legacy `riskmodels-cli` npm package remains a backward-compatible published artifact. New releases from this directory target the unscoped `riskmodels` package; use `npx -y riskmodels@latest install` for a deterministic one-shot MCP setup.

package/dist/commands/decompose.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function decomposeCommand(): Command;

package/dist/commands/decompose.js

@@ -0,0 +1,31 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { loadConfig } from "../lib/config.js";
+import { requireResolvedAuth } from "../lib/credentials.js";
+import { apiFetchJson } from "../lib/api-client.js";
+import { printResults } from "../lib/display.js";
+export function decomposeCommand() {
+    return new Command("decompose")
+        .description("Four-layer decomposition + hedge map for one ticker (POST /decompose)")
+        .argument("<ticker>", "Ticker symbol, e.g. NVDA")
+        .action(async (ticker, _opts, cmd) => {
+        const json = cmd.optsWithGlobals().json ?? false;
+        const cfg = await loadConfig();
+        const auth = requireResolvedAuth(cfg, chalk.yellow);
+        if (!auth)
+            return;
+        const t = ticker.trim();
+        try {
+            const { body, costUsd } = await apiFetchJson(auth, "POST", "/decompose", {
+                jsonBody: { ticker: t },
+            });
+            printResults(body, json);
+            if (!json && costUsd)
+                console.log(chalk.dim(`Cost: $${costUsd}`));
+        }
+        catch (e) {
+            console.error(chalk.red(e instanceof Error ? e.message : String(e)));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/commands/doctor.js

@@ -3,14 +3,17 @@ import { Command } from "commander";
 import { configPath, loadConfig, maskSecret } from "../lib/config.js";
 import { detectClients } from "../lib/mcp-config-paths.js";
 import { printResults } from "../lib/display.js";
+import { printDoctorHuman } from "../lib/cli-human-diagnostics.js";
+import { warnIfGlobalJsonBeforeSubcommand } from "../lib/global-json-hint.js";
+import { abbreviatePath } from "../lib/path-display.js";
 function commandOk(command, args = ["--version"]) {
     const result = spawnSync(command, args, { stdio: "ignore" });
     return result.status === 0 || result.status === 1;
 }
 export function doctorCommand() {
     return new Command("doctor")
-        .description("Run local diagnostics for RiskModels CLI and MCP install readiness")
-        .option("--json", "JSON output")
+        .description("Run local diagnostics for RiskModels CLI and MCP install readiness (default: readable summary; use --json for scripts)")
+        .option("--json", "Structured JSON instead of readable summary")
         .action(async (opts, cmd) => {
         const json = opts.json || cmd.optsWithGlobals().json || false;
         const cfg = await loadConfig();
@@ -24,28 +27,35 @@ export function doctorCommand() {
             {
                 id: "npx",
                 ok: commandOk("npx"),
-                detail: "Required to launch @riskmodels/mcp from MCP client configs.",
+                detail: "Required so MCP configs can run `npx -y @riskmodels/mcp` (stdio server from `riskmodels install`).",
             },
             {
                 id: "api_credentials",
                 ok: !!cfg?.apiKey || !!process.env.RISKMODELS_API_KEY || (!!cfg?.clientId && !!cfg?.clientSecret),
                 detail: cfg?.apiKey
-                    ? `Config API key ${maskSecret(cfg.apiKey)} in ${configPath()}`
+                    ? `Config API key ${maskSecret(cfg.apiKey)} in ${abbreviatePath(configPath())}`
                     : process.env.RISKMODELS_API_KEY
                         ? "RISKMODELS_API_KEY is set in the environment."
-                        : "No API key found. Get one at https://riskmodels.app/get-api-key",
+                        : "No API key found. Get one at https://riskmodels.app/get-key",
             },
             {
                 id: "mcp_package_target",
                 ok: true,
-                detail: "Installer targets npx -y @riskmodels/mcp once the package is published.",
+                detail: "`riskmodels install` merges `npx -y @riskmodels/mcp` into detected client configs (stdio MCP).",
             },
         ];
-        printResults({
+        const payload = {
             ok: checks.every((check) => check.ok),
             checks,
             clients,
             note: "Run `riskmodels install --dry-run` to inspect config writes, or `riskmodels install` to write configs with backups and run a connection test.",
-        }, json);
+        };
+        if (json) {
+            warnIfGlobalJsonBeforeSubcommand("doctor");
+            printResults(payload, json);
+        }
+        else {
+            printDoctorHuman(payload);
+        }
     });
 }

package/dist/commands/install.js

@@ -1,14 +1,16 @@
 import { Command } from "commander";
 import inquirer from "inquirer";
 import chalk from "chalk";
-import { configPath, DEFAULT_API_BASE, loadConfig } from "../lib/config.js";
+import { configPath, DEFAULT_API_BASE, loadConfig, sharedRiskmodelsConfigExists, } from "../lib/config.js";
 import { detectClients, selectedClients } from "../lib/mcp-config-paths.js";
 import { buildInstallPlans, firstPrompt } from "../lib/mcp-install-plan.js";
 import { printResults } from "../lib/display.js";
+import { API_KEY_EMAIL_HINT, printInstallDryRunHuman, printInstallMissingKeyHuman, printInstallSuccessHuman, } from "../lib/mcp-cli-human-output.js";
 import { redactSecret } from "../lib/redact.js";
 import { installMcpConfig, writeSharedApiKey } from "../lib/mcp-config-writer.js";
 import { apiRootFromUserBase } from "../lib/api-url.js";
 import { apiFetchOptionalAuth } from "../lib/api-client.js";
+import { warnIfGlobalJsonBeforeSubcommand } from "../lib/global-json-hint.js";
 function envApiKey() {
     return process.env.RISKMODELS_API_KEY?.trim() || undefined;
 }
@@ -41,7 +43,8 @@ async function resolveApiKey(opts) {
     if (opts.yes)
         return { source: "missing" };
     console.error(chalk.yellow("No RiskModels API key found."));
-    console.error(chalk.dim("Get a key: https://riskmodels.app/get-api-key"));
+    console.error(chalk.dim("Get a key: https://riskmodels.app/get-key"));
+    console.error(chalk.dim(API_KEY_EMAIL_HINT));
     const answer = await inquirer.prompt([
         {
             type: "password",
@@ -55,14 +58,14 @@ async function resolveApiKey(opts) {
 }
 export function installCommand() {
     return new Command("install")
-        .description("Detect AI clients and install/register the RiskModels MCP server")
+        .description("Detect AI clients and install/register the RiskModels MCP server (default: friendly summary; pass --json for machine-readable)")
         .option("--client <name>", "claude | cursor | codex | vscode")
         .option("--all", "Target all detected clients")
         .option("--api-key <key>", "RiskModels API key for one-shot setup")
         .option("--dry-run", "Show planned config changes without writing")
         .option("--yes", "Non-interactive mode")
         .option("--embed-key", "Explicitly embed the API key in MCP config env (not recommended)")
-        .option("--json", "JSON output")
+        .option("--json", "Structured JSON instead of formatted text (matches historical output shape)")
         .action(async (opts, cmd) => {
         const json = opts.json || cmd.optsWithGlobals().json || false;
         let clients;
@@ -96,20 +99,34 @@ export function installCommand() {
                 : "Install complete. Restart your MCP client, then try the first prompt.",
         };
         if (dryRun) {
-            printResults(output, json);
-            if (!json) {
-                console.error(chalk.green(`First prompt to try: "${firstPrompt()}"`));
+            if (json) {
+                warnIfGlobalJsonBeforeSubcommand("install");
+                printResults(output, json);
+            }
+            else {
+                printInstallDryRunHuman({
+                    plans,
+                    willStoreSharedKey: !!apiKey && source !== configPath(),
+                    firstPrompt: firstPrompt(),
+                });
             }
             return;
         }
         if (!apiKey) {
-            printResults({
-                ...output,
-                error: "No RiskModels API key found. Get one at https://riskmodels.app/get-api-key or pass --api-key.",
-            }, json);
+            if (json) {
+                warnIfGlobalJsonBeforeSubcommand("install");
+                printResults({
+                    ...output,
+                    error: "No RiskModels API key found. Get one at https://riskmodels.app/get-key or pass --api-key.",
+                }, json);
+            }
+            else {
+                printInstallMissingKeyHuman();
+            }
             process.exitCode = 1;
             return;
         }
+        const sharedBefore = await sharedRiskmodelsConfigExists();
         const sharedConfigWrite = await writeSharedApiKey(apiKey, existingConfig?.apiBaseUrl ?? DEFAULT_API_BASE);
         const writes = await Promise.all(detections.map((detection) => installMcpConfig(detection, {
             apiKey,
@@ -123,14 +140,24 @@ export function installCommand() {
             writes,
             connectionTest: test,
         };
-        printResults(result, json);
+        if (json) {
+            warnIfGlobalJsonBeforeSubcommand("install");
+            printResults(result, json);
+        }
+        else {
+            printInstallSuccessHuman({
+                isFirstInstall: !sharedBefore,
+                writes,
+                sharedConfigWrite,
+                connectionTest: test,
+                firstPrompt: firstPrompt(),
+                hadErrors: writes.some((w) => w.action === "error") || !test.ok,
+                showClaudeCodeMcpTip: detections.some((d) => d.client === "claude" && d.commandAvailable),
+            });
+        }
         if (writes.some((write) => write.action === "error") || !test.ok) {
             process.exitCode = 1;
             return;
         }
-        if (!json) {
-            console.error(chalk.green("RiskModels MCP install completed with backups."));
-            console.error(chalk.green(`First prompt to try: "${firstPrompt()}"`));
-        }
     });
 }

package/dist/commands/status.js

@@ -2,24 +2,33 @@ import { Command } from "commander";
 import { configPath, loadConfig, maskSecret } from "../lib/config.js";
 import { detectClients, selectedClients } from "../lib/mcp-config-paths.js";
 import { printResults } from "../lib/display.js";
+import { printStatusHuman } from "../lib/cli-human-diagnostics.js";
+import { warnIfGlobalJsonBeforeSubcommand } from "../lib/global-json-hint.js";
 export function statusCommand() {
     return new Command("status")
-        .description("Show RiskModels CLI and MCP client configuration status")
+        .description("Show RiskModels CLI and MCP client configuration status (default: readable summary; use --json for scripts)")
         .option("--client <name>", "claude | cursor | codex | vscode")
         .option("--all", "Check all supported clients")
-        .option("--json", "JSON output")
+        .option("--json", "Structured JSON instead of readable summary")
         .action(async (opts, cmd) => {
         const json = opts.json || cmd.optsWithGlobals().json || false;
         const cfg = await loadConfig();
         const clients = selectedClients({ client: opts.client, all: opts.all });
         const detections = await detectClients(clients);
-        printResults({
+        const payload = {
             configPath: configPath(),
             configFound: !!cfg,
             apiBaseUrl: cfg?.apiBaseUrl ?? "https://riskmodels.app",
             apiKey: maskSecret(cfg?.apiKey),
             oauthConfigured: !!cfg?.clientId && !!cfg?.clientSecret,
             mcpClients: detections,
-        }, json);
+        };
+        if (json) {
+            warnIfGlobalJsonBeforeSubcommand("status");
+            printResults(payload, json);
+        }
+        else {
+            printStatusHuman(payload);
+        }
     });
 }

package/dist/commands/uninstall.js

@@ -1,15 +1,16 @@
 import { Command } from "commander";
-import chalk from "chalk";
 import { detectClients, selectedClients } from "../lib/mcp-config-paths.js";
 import { printResults } from "../lib/display.js";
+import { printUninstallPlannedHuman, printUninstallSuccessHuman, } from "../lib/mcp-cli-human-output.js";
 import { uninstallMcpConfig } from "../lib/mcp-config-writer.js";
+import { warnIfGlobalJsonBeforeSubcommand } from "../lib/global-json-hint.js";
 export function uninstallCommand() {
     return new Command("uninstall")
-        .description("Remove the RiskModels MCP server from client configs")
+        .description("Remove the RiskModels MCP server from client configs (default: friendly summary; pass --json for machine-readable)")
         .option("--client <name>", "claude | cursor | codex | vscode")
         .option("--all", "Check all supported clients")
         .option("--dry-run", "Show planned removals without writing")
-        .option("--json", "JSON output")
+        .option("--json", "Structured JSON instead of formatted text (matches historical output shape)")
         .action(async (opts, cmd) => {
         const json = opts.json || cmd.optsWithGlobals().json || false;
         const clients = selectedClients({ client: opts.client, all: opts.all });
@@ -29,17 +30,26 @@ export function uninstallCommand() {
             })),
         };
         if (dryRun) {
-            printResults(output, json);
+            if (json) {
+                warnIfGlobalJsonBeforeSubcommand("uninstall");
+                printResults(output, json);
+            }
+            else {
+                printUninstallPlannedHuman(detections);
+            }
             return;
         }
         const removals = await Promise.all(detections.map((detection) => uninstallMcpConfig(detection)));
-        printResults({ ...output, removals }, json);
+        if (json) {
+            warnIfGlobalJsonBeforeSubcommand("uninstall");
+            printResults({ ...output, removals }, json);
+        }
+        else {
+            printUninstallSuccessHuman(removals);
+        }
         if (removals.some((removal) => removal.action === "error")) {
             process.exitCode = 1;
             return;
         }
-        if (!json) {
-            console.error(chalk.green("RiskModels MCP uninstall completed with backups where files changed."));
-        }
     });
 }

package/dist/index.js

@@ -10,6 +10,7 @@ import { mcpConfigCommand } from "./commands/mcp-config.js";
 import { mcpServeCommand } from "./commands/mcp.js";
 import { agentCommand } from "./commands/agent.js";
 import { metricsCommand } from "./commands/metrics.js";
+import { decomposeCommand } from "./commands/decompose.js";
 import { batchCommand } from "./commands/batch.js";
 import { portfolioCommand } from "./commands/portfolio.js";
 import { tickersCommand } from "./commands/tickers.js";
@@ -28,15 +29,17 @@ const program = new Command();
 program
     .name("riskmodels")
     .description("RiskModels CLI — REST API, SQL query, schema, billing, and agent manifests")
-    .version("2.0.0", "-V, --version", "output version")
+    .version("2.0.2", "-V, --version", "output version")
     .option("--json", "JSON output for supported commands (query, schema, balance, API calls, config list)")
     .configureHelp({ sortSubcommands: true })
     .addHelpText("after", `
 ${chalk.bold("Quick start")}
   ${chalk.dim("$")} riskmodels config init
   ${chalk.dim("$")} riskmodels install --dry-run
+  ${chalk.dim("$")} riskmodels uninstall --dry-run
   ${chalk.dim("$")} riskmodels health
   ${chalk.dim("$")} riskmodels metrics NVDA
+  ${chalk.dim("$")} riskmodels decompose NVDA
   ${chalk.dim("$")} riskmodels query ${chalk.green('"SELECT ticker FROM ticker_metadata LIMIT 3"')}
   ${chalk.dim("$")} riskmodels manifest --format anthropic
 
@@ -48,6 +51,7 @@ program.addCommand(doctorCommand());
 program.addCommand(uninstallCommand());
 program.addCommand(queryCommand());
 program.addCommand(metricsCommand());
+program.addCommand(decomposeCommand());
 program.addCommand(batchCommand());
 program.addCommand(portfolioCommand());
 program.addCommand(returnsCommand());

package/dist/lib/cli-human-diagnostics.d.ts

@@ -0,0 +1,21 @@
+import type { ClientDetection } from "./mcp-config-paths.js";
+export type DoctorPayload = {
+    ok: boolean;
+    checks: {
+        id: string;
+        ok: boolean;
+        detail: string;
+    }[];
+    clients: ClientDetection[];
+    note: string;
+};
+export declare function printDoctorHuman(payload: DoctorPayload): void;
+export type StatusPayload = {
+    configPath: string;
+    configFound: boolean;
+    apiBaseUrl: string;
+    apiKey: string;
+    oauthConfigured: boolean;
+    mcpClients: ClientDetection[];
+};
+export declare function printStatusHuman(payload: StatusPayload): void;

package/dist/lib/cli-human-diagnostics.js

@@ -0,0 +1,49 @@
+import chalk from "chalk";
+import { abbreviatePath } from "./path-display.js";
+import { formatCliVersionLabel } from "./cli-version.js";
+const BULLET = "•";
+function logLine(line = "") {
+    console.log(line);
+}
+export function printDoctorHuman(payload) {
+    logLine("");
+    logLine(`${chalk.bold("riskmodels doctor")} ${chalk.dim(`(CLI ${formatCliVersionLabel()})`)}`);
+    logLine("");
+    logLine(payload.ok ? chalk.green.bold("All checks passed") : chalk.yellow.bold("Some checks need attention"));
+    logLine("");
+    logLine(chalk.bold("Checks:"));
+    for (const c of payload.checks) {
+        const icon = c.ok ? chalk.green("✓") : chalk.red("✗");
+        logLine(`  ${icon} ${chalk.bold(c.id)}${c.detail ? chalk.dim(` — ${c.detail}`) : ""}`);
+    }
+    logLine("");
+    logLine(chalk.bold("MCP client detection:"));
+    for (const d of payload.clients) {
+        const p = d.configPath ? chalk.dim(` — ${abbreviatePath(d.configPath)}`) : "";
+        logLine(`  ${BULLET} ${d.label} (${d.status}${d.mode !== "guidance" ? `, ${d.mode}` : ""})${p}`);
+    }
+    logLine("");
+    logLine(chalk.dim(payload.note));
+    logLine("");
+}
+export function printStatusHuman(payload) {
+    logLine("");
+    logLine(`${chalk.bold("riskmodels status")} ${chalk.dim(`(CLI ${formatCliVersionLabel()})`)}`);
+    logLine("");
+    const cfgDisp = abbreviatePath(payload.configPath);
+    logLine(`${chalk.bold("Shared config:")} ${cfgDisp}`);
+    if (cfgDisp !== payload.configPath) {
+        logLine(chalk.dim(`  (full path: ${payload.configPath})`));
+    }
+    logLine(`  ${BULLET} ${payload.configFound ? chalk.green("file present") : chalk.dim("file missing (run install or config init)")}`);
+    logLine(`  ${BULLET} ${chalk.bold("apiBaseUrl")} ${chalk.dim(payload.apiBaseUrl)}`);
+    logLine(`  ${BULLET} ${chalk.bold("API key")} ${payload.apiKey}`);
+    logLine(`  ${BULLET} ${chalk.bold("OAuth")} ${payload.oauthConfigured ? chalk.green("configured") : chalk.dim("not configured")}`);
+    logLine("");
+    logLine(chalk.bold("MCP-related clients:"));
+    for (const d of payload.mcpClients) {
+        const p = d.configPath ? chalk.dim(` — ${abbreviatePath(d.configPath)}`) : "";
+        logLine(`  ${BULLET} ${d.label}: ${d.status}${p}`);
+    }
+    logLine("");
+}

package/dist/lib/cli-version.d.ts

@@ -0,0 +1,4 @@
+/** Resolved from sibling `cli/package.json` at runtime (`dist/` → repo `cli/`). */
+export declare function getCliPackageVersion(): string;
+/** e.g. `v2.0.2` for human-facing footers (package.json omits leading v). */
+export declare function formatCliVersionLabel(): string;

package/dist/lib/cli-version.js

@@ -0,0 +1,25 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const pkgDir = dirname(fileURLToPath(import.meta.url));
+let cachedVersion = null;
+/** Resolved from sibling `cli/package.json` at runtime (`dist/` → repo `cli/`). */
+export function getCliPackageVersion() {
+    if (cachedVersion !== null)
+        return cachedVersion;
+    try {
+        const pkgPath = join(pkgDir, "..", "..", "package.json");
+        const raw = readFileSync(pkgPath, "utf8");
+        cachedVersion = JSON.parse(raw).version;
+        return cachedVersion;
+    }
+    catch {
+        cachedVersion = "0.0.0";
+        return cachedVersion;
+    }
+}
+/** e.g. `v2.0.2` for human-facing footers (package.json omits leading v). */
+export function formatCliVersionLabel() {
+    const v = getCliPackageVersion();
+    return v.startsWith("v") ? v : `v${v}`;
+}

package/dist/lib/config.d.ts

@@ -13,6 +13,8 @@ export interface RiskmodelsConfig {
 }
 export declare const DEFAULT_API_BASE = "https://riskmodels.app";
 export declare function configPath(): string;
+/** True when shared config file exists (used for MCP install welcome on first-ever setup). */
+export declare function sharedRiskmodelsConfigExists(): Promise<boolean>;
 export declare function loadConfig(): Promise<RiskmodelsConfig | null>;
 export declare function saveConfig(cfg: RiskmodelsConfig): Promise<void>;
 export declare function maskSecret(value: string | undefined, visible?: number): string;

package/dist/lib/config.js

@@ -1,10 +1,22 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
 export const DEFAULT_API_BASE = "https://riskmodels.app";
 export function configPath() {
     return path.join(homedir(), ".config", "riskmodels", "config.json");
 }
+/** True when shared config file exists (used for MCP install welcome on first-ever setup). */
+export async function sharedRiskmodelsConfigExists() {
+    try {
+        await stat(configPath());
+        return true;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
 export async function loadConfig() {
     const p = configPath();
     try {

package/dist/lib/global-json-hint.d.ts

@@ -0,0 +1,4 @@
+/** True when `--json` appears in argv before the subcommand (parent-level flag). */
+export declare function usedGlobalJsonBeforeSubcommand(subcommandName: string): boolean;
+/** Explains JSON output when `--json` was set before the subcommand (stderr, dim). */
+export declare function warnIfGlobalJsonBeforeSubcommand(subcommandName: string): void;

package/dist/lib/global-json-hint.js

@@ -0,0 +1,16 @@
+import chalk from "chalk";
+/** True when `--json` appears in argv before the subcommand (parent-level flag). */
+export function usedGlobalJsonBeforeSubcommand(subcommandName) {
+    const args = process.argv.slice(2);
+    const jsonIdx = args.findIndex((a) => a === "--json" || a.startsWith("--json="));
+    const subIdx = args.indexOf(subcommandName);
+    if (jsonIdx === -1 || subIdx === -1)
+        return false;
+    return jsonIdx < subIdx;
+}
+/** Explains JSON output when `--json` was set before the subcommand (stderr, dim). */
+export function warnIfGlobalJsonBeforeSubcommand(subcommandName) {
+    if (!usedGlobalJsonBeforeSubcommand(subcommandName))
+        return;
+    console.error(chalk.dim(`Note: JSON mode is on because --json appears before "${subcommandName}". Move --json after "${subcommandName}" when you want default human output.`));
+}

package/dist/lib/mcp-cli-human-output.d.ts

@@ -0,0 +1,28 @@
+import type { SharedConfigWriteResult, ConfigWriteResult } from "./mcp-config-writer.js";
+import type { InstallPlan } from "./mcp-install-plan.js";
+import type { ClientDetection } from "./mcp-config-paths.js";
+/** Shown wherever we direct users to obtain an API key (matches key-issued email sender). */
+export declare const API_KEY_EMAIL_HINT = "If you requested a key already, check your inbox for mail from RiskModels (service@riskmodels.app).";
+export declare function printInstallSuccessHuman(opts: {
+    isFirstInstall: boolean;
+    writes: ConfigWriteResult[];
+    sharedConfigWrite: SharedConfigWriteResult;
+    connectionTest: {
+        ok: boolean;
+        endpoint: string;
+        message: string;
+    };
+    firstPrompt: string;
+    hadErrors: boolean;
+    /** When Claude CLI is detected, suggest native `claude mcp` as an alternative. */
+    showClaudeCodeMcpTip?: boolean;
+}): void;
+export declare function printInstallDryRunHuman(opts: {
+    plans: InstallPlan[];
+    willStoreSharedKey?: boolean;
+    firstPrompt: string;
+}): void;
+export declare function printInstallMissingKeyHuman(): void;
+export declare function printUninstallSuccessHuman(removals: ConfigWriteResult[]): void;
+/** Human-readable detection list for uninstall dry-run (before removals computed). */
+export declare function printUninstallPlannedHuman(detections: ClientDetection[]): void;

package/dist/lib/mcp-cli-human-output.js

@@ -0,0 +1,224 @@
+import chalk from "chalk";
+import { platform } from "node:os";
+import { configPath } from "./config.js";
+import { formatCliVersionLabel } from "./cli-version.js";
+import { abbreviatePath } from "./path-display.js";
+const BULLET = "•";
+/** Shown wherever we direct users to obtain an API key (matches key-issued email sender). */
+export const API_KEY_EMAIL_HINT = "If you requested a key already, check your inbox for mail from RiskModels (service@riskmodels.app).";
+function logRiskmodelsCliFooter(phase) {
+    logLine("");
+    logLine(chalk.bold("riskmodels CLI (still on PATH):"));
+    logLine(chalk.dim(phase === "dry-run"
+        ? "Uninstalling MCP only edits AI client configs; it does not remove the riskmodels terminal command."
+        : 'The RiskModels MCP integration was removed from the configs above. The "riskmodels" terminal command was not.'));
+    logLine(chalk.dim("To remove the CLI, use what matches how you installed it:"));
+    if (platform() !== "win32") {
+        logLine(chalk.dim(`  ${BULLET} Homebrew (macOS / Linux): brew uninstall riskmodels`));
+    }
+    logLine(chalk.dim(`  ${BULLET} npm (any OS): npm uninstall -g riskmodels`));
+    if (platform() === "win32") {
+        logLine(chalk.dim(`  ${BULLET} Package manager installs (winget / Chocolatey / Scoop / etc.): use that tool's uninstall`));
+    }
+    logLine("");
+    logLine(chalk.dim(`riskmodels CLI ${formatCliVersionLabel()}`));
+}
+function logLine(line = "") {
+    console.log(line);
+}
+function formatBackupBullets(paths) {
+    return paths
+        .filter(Boolean)
+        .sort()
+        .map((p) => `${BULLET} ${abbreviatePath(p)}`);
+}
+export function printInstallSuccessHuman(opts) {
+    const { isFirstInstall, writes, sharedConfigWrite, connectionTest, firstPrompt, hadErrors, showClaudeCodeMcpTip, } = opts;
+    if (isFirstInstall) {
+        logLine("");
+        logLine(chalk.bold("👋 Welcome to RiskModels MCP!"));
+        logLine("");
+        logLine("This one-time setup connects your AI coding tools (Claude, Cursor, etc.)");
+        logLine("to real-time portfolio risk snapshots, hedge ratios, and factor models.");
+        logLine("");
+    }
+    logLine("");
+    if (hadErrors) {
+        logLine(chalk.yellow.bold("⚠ RiskModels MCP install finished with errors"));
+    }
+    else {
+        logLine(chalk.green.bold("✅ RiskModels MCP install completed"));
+    }
+    logLine("");
+    logLine(chalk.bold("Installed / updated in:"));
+    const installed = writes.filter((w) => w.action === "written");
+    if (installed.length === 0) {
+        logLine(`  ${chalk.dim("(no client MCP configs were modified — check detection / permissions)")}`);
+    }
+    else {
+        for (const w of installed) {
+            logLine(`  ${BULLET} ${w.label}`);
+        }
+    }
+    const skipped = writes.filter((w) => w.action === "skipped" && w.client !== "vscode");
+    if (skipped.length > 0) {
+        logLine("");
+        logLine(chalk.dim("Skipped (no change):"));
+        for (const w of skipped) {
+            logLine(`  ${BULLET} ${w.label} — ${chalk.dim(w.message)}`);
+        }
+    }
+    const vsSkipped = writes.find((w) => w.action === "skipped" && w.client === "vscode");
+    if (vsSkipped) {
+        logLine("");
+        logLine(chalk.dim(`VS Code: ${vsSkipped.message}`));
+    }
+    const backupPaths = [];
+    if (sharedConfigWrite.backupPath)
+        backupPaths.push(sharedConfigWrite.backupPath);
+    for (const w of writes) {
+        if (w.backupPath)
+            backupPaths.push(w.backupPath);
+    }
+    logLine("");
+    logLine(chalk.bold("Backups created for safety:"));
+    if (backupPaths.length === 0) {
+        logLine(`  ${chalk.dim("(none — configs were newly created)")}`);
+    }
+    else {
+        for (const line of formatBackupBullets(backupPaths))
+            logLine(`  ${line}`);
+    }
+    logLine("");
+    if (connectionTest.ok) {
+        logLine(`${chalk.bold("Connection test:")} OK (${chalk.cyan(connectionTest.endpoint)})`);
+    }
+    else {
+        logLine(`${chalk.bold("Connection test:")} ${chalk.red("FAILED")} ${chalk.dim(`(${connectionTest.endpoint})`)}`);
+        logLine(chalk.dim(`  ${connectionTest.message}`));
+        logLine(chalk.dim("Tip: check network/VPN, apiBaseUrl in shared config if non-default, corporate proxy, then run: riskmodels health"));
+    }
+    if (showClaudeCodeMcpTip) {
+        logLine("");
+        logLine("Claude Code users: you can also run");
+        logLine(chalk.dim("  claude mcp add riskmodels npx -y @riskmodels/mcp"));
+    }
+    if (!hadErrors) {
+        logLine("");
+        logLine(`${chalk.bold("Next step:")} Restart your AI clients, then try:`);
+        logLine("");
+        logLine(`"${firstPrompt}"`);
+        logLine("");
+    }
+    else {
+        logLine("");
+        const failed = writes.filter((w) => w.action === "error");
+        if (failed.length > 0) {
+            logLine(chalk.bold("Errors:"));
+            for (const w of failed) {
+                logLine(`  ${BULLET} ${w.label}: ${chalk.red(w.message)}`);
+            }
+            logLine("");
+        }
+    }
+    logLine(chalk.dim(`riskmodels CLI ${formatCliVersionLabel()}`));
+}
+export function printInstallDryRunHuman(opts) {
+    logLine("");
+    logLine(chalk.bold("Dry run — planned RiskModels MCP install"));
+    logLine("");
+    logLine(chalk.bold("Clients to merge into:"));
+    for (const p of opts.plans) {
+        const pathPart = p.configPath ? chalk.dim(` — ${abbreviatePath(p.configPath)}`) : "";
+        logLine(`  ${BULLET} ${p.label}${pathPart}`);
+    }
+    logLine("");
+    const cfgAbs = configPath();
+    const cfgShort = abbreviatePath(cfgAbs);
+    if (opts.willStoreSharedKey) {
+        logLine(chalk.dim(`A shared API key file would be created or updated at ${cfgShort}`));
+        if (cfgShort !== cfgAbs)
+            logLine(chalk.dim(`  (full path: ${cfgAbs})`));
+        logLine(chalk.dim("(with backup if replacing)."));
+    }
+    else {
+        logLine(chalk.dim("No API key resolved — rerun with --api-key or set RISKMODELS_API_KEY after obtaining a key."));
+        logLine(chalk.dim(API_KEY_EMAIL_HINT));
+    }
+    logLine("");
+    logLine(chalk.dim("Rerun without --dry-run after you are happy with this plan."));
+    logLine("");
+    logLine(`${chalk.bold("First prompt to paste into your AI client:")} "${opts.firstPrompt}"`);
+    logLine("");
+    logLine(chalk.dim(`riskmodels CLI ${formatCliVersionLabel()}`));
+}
+export function printInstallMissingKeyHuman() {
+    logLine("");
+    logLine(chalk.red.bold("✗ Missing RiskModels API key"));
+    logLine("");
+    logLine(`Get a key: ${chalk.cyan("https://riskmodels.app/get-key")}`);
+    logLine("");
+    logLine(chalk.dim(API_KEY_EMAIL_HINT));
+    logLine("");
+    logLine(chalk.dim("Pass --api-key, set RISKMODELS_API_KEY, or rerun without --yes to enter it interactively."));
+    logLine("");
+    logLine(chalk.dim(`riskmodels CLI ${formatCliVersionLabel()}`));
+}
+export function printUninstallSuccessHuman(removals) {
+    logLine("");
+    logLine(chalk.green.bold("✅ RiskModels MCP uninstall completed"));
+    logLine("");
+    logLine(chalk.bold("Updates to MCP configs:"));
+    logLine("");
+    for (const r of removals) {
+        const bullet = `${BULLET} ${r.label}`;
+        const pathSuffix = r.configPath !== undefined ? chalk.dim(` — ${abbreviatePath(r.configPath)}`) : "";
+        if (r.action === "written") {
+            logLine(`  ${bullet}${pathSuffix}`);
+            logLine(chalk.green.dim(`      ${r.message}`));
+            if (r.backupPath)
+                logLine(chalk.dim(`      backup: ${abbreviatePath(r.backupPath)}`));
+        }
+        else if (r.action === "skipped") {
+            logLine(`  ${bullet}${pathSuffix}`);
+            logLine(chalk.dim(`      (skipped — ${r.message})`));
+        }
+        else if (r.action === "error") {
+            logLine(`  ${bullet}${pathSuffix}`);
+            logLine(chalk.red(`      error: ${r.message}`));
+        }
+    }
+    logLine("");
+    const sharedAbs = configPath();
+    const sharedShort = abbreviatePath(sharedAbs);
+    logLine(`${chalk.bold("Shared API key / billing profile:")} unchanged ${chalk.dim(`(${sharedShort})`)}`);
+    if (sharedShort !== sharedAbs) {
+        logLine(chalk.dim(`  (full path: ${sharedAbs})`));
+    }
+    logLine(chalk.dim("Only the riskmodels MCP server block was removed from each AI client config above; your key file was not modified."));
+    const backupPaths = removals.filter((r) => r.backupPath).map((r) => r.backupPath);
+    if (backupPaths.length > 0) {
+        logLine("");
+        logLine(chalk.bold("Backups stored:"));
+        for (const line of formatBackupBullets(backupPaths))
+            logLine(`  ${line}`);
+    }
+    logRiskmodelsCliFooter("done");
+}
+/** Human-readable detection list for uninstall dry-run (before removals computed). */
+export function printUninstallPlannedHuman(detections) {
+    logLine("");
+    logLine(chalk.bold("Dry run — RiskModels MCP would be inspected on:"));
+    logLine("");
+    for (const d of detections) {
+        const p = d.configPath ? chalk.dim(` — ${abbreviatePath(d.configPath)}`) : "";
+        logLine(`  ${BULLET} ${d.label}${p}`);
+    }
+    logLine("");
+    const sharedAbs = configPath();
+    const sharedShort = abbreviatePath(sharedAbs);
+    logLine(chalk.dim(`Only the "riskmodels" MCP server block would be removed; ${sharedShort} would not be touched.`));
+    if (sharedShort !== sharedAbs)
+        logLine(chalk.dim(`  (full path: ${sharedAbs})`));
+    logRiskmodelsCliFooter("dry-run");
+}

package/dist/lib/path-display.d.ts

@@ -0,0 +1,2 @@
+/** Shorten home-prefixed paths for readability (~ on POSIX; Windows uses same tilde-in-shell convention in Git Bash). */
+export declare function abbreviatePath(absolutePath: string): string;

package/dist/lib/path-display.js

@@ -0,0 +1,18 @@
+import { homedir } from "node:os";
+/** Shorten home-prefixed paths for readability (~ on POSIX; Windows uses same tilde-in-shell convention in Git Bash). */
+export function abbreviatePath(absolutePath) {
+    if (!absolutePath.trim())
+        return absolutePath;
+    const home = homedir();
+    if (absolutePath === home)
+        return "~";
+    const sep = absolutePath.includes("\\") ? "\\" : "/";
+    const homeNorm = home.replace(/\\/g, "/");
+    const pathNorm = absolutePath.replace(/\\/g, "/");
+    if (pathNorm === homeNorm || pathNorm === `${homeNorm}/`)
+        return "~";
+    if (pathNorm.startsWith(`${homeNorm}/`)) {
+        return `~/${pathNorm.slice(homeNorm.length + 1)}`;
+    }
+    return absolutePath;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "riskmodels",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "RiskModels CLI — REST API, SQL query, schema, billing, and agent manifests",
   "type": "module",
   "bin": {