@askthew/mcp-plugin 0.4.4 → 0.4.6

package/README.md

@@ -3,7 +3,7 @@
 Connect a local coding agent to Ask The W. The fastest path is free and local-first:
 
 ```bash
-npx -y --prefer-online @askthew/mcp-plugin@latest install --host claude_code --free --email you@founder.com
+npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp install --host claude_code --free --email you@founder.com
 ```
 
 This captures decisions and session signals to `~/.askthew/store.sqlite` and lets your agent run `review_decisions`, `review_session`, `recap`, `coach`, and `promote_signal_to_decision` without onboarding into the web app.
@@ -35,7 +35,7 @@ Ask The W performs inference, linking, approval state, dedupe, and outcome updat
 ## Free Local Install
 
 ```bash
-npx -y --prefer-online @askthew/mcp-plugin@latest install \
+npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp install \
   --host claude_code \
   --free \
   --email you@founder.com
@@ -45,6 +45,24 @@ Free install is local-first: it generates `~/.askthew/identity.json`, writes MCP
 
 Telemetry is aggregate-only and opt-out. Ask The W does not receive code, file contents, file paths, file names, command text, summaries, or decision content in free mode telemetry. Aggregate summaries are signed by the local install identity and stored under the generated install ID. Opt out with `--no-telemetry`, `ASKTHEW_TELEMETRY=off`, or `askthew-mcp telemetry opt-out`.
 
+## Refresh vs Uninstall
+
+Use `refresh` when you want the latest installed MCP config and instruction blocks without touching local identity or local data:
+
+```bash
+npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp refresh --host claude_code
+```
+
+`refresh` preserves `~/.askthew/identity.json` and `~/.askthew/store.sqlite`, reuses any existing email claim silently, rewrites the host MCP config, and rewrites the marked Ask The W blocks in `CLAUDE.md` and `AGENTS.md`. This is the recommended QA update path after a plugin publish.
+
+Use `uninstall` when you want to remove the plugin from a host:
+
+```bash
+npx -y @askthew/mcp-plugin@latest uninstall --host claude_code --keep-local-data --keep-auth
+```
+
+Without `--keep-local-data`, uninstall removes `~/.askthew`; without `--keep-auth`, it removes the local install identity. Uninstall does not clear npm's cache.
+
 ## Workspace Install
 
 Create a workspace token in Ask The W at `/decisions/settings/connectors`, then run the installer from your coding agent or terminal. Treat the token like a password; anyone with it can write compact source signals into that workspace.
@@ -54,7 +72,7 @@ Use setup tokens promptly. They expire after 24 hours if the connector never sen
 Codex:
 
 ```bash
-npx -y --prefer-online @askthew/mcp-plugin@latest install \
+npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp install \
   --host codex \
   --token "<ASKTHEW_INSTALL_TOKEN>" \
   --api-url "https://app.askthew.com/" \
@@ -64,7 +82,7 @@ npx -y --prefer-online @askthew/mcp-plugin@latest install \
 Claude Code:
 
 ```bash
-npx -y --prefer-online @askthew/mcp-plugin@latest install \
+npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp install \
   --host claude_code \
   --token "<ASKTHEW_INSTALL_TOKEN>" \
   --api-url "https://app.askthew.com/" \
@@ -74,7 +92,7 @@ npx -y --prefer-online @askthew/mcp-plugin@latest install \
 Cursor:
 
 ```bash
-npx -y --prefer-online @askthew/mcp-plugin@latest install \
+npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp install \
   --host cursor \
   --token "<ASKTHEW_INSTALL_TOKEN>" \
   --api-url "https://app.askthew.com/" \
@@ -112,7 +130,7 @@ Codex example:
 ```toml
 [mcp_servers.askthew]
 command = "npx"
-args = ["-y", "--prefer-online", "@askthew/mcp-plugin@latest"]
+args = ["-y", "--prefer-online", "--package", "@askthew/mcp-plugin@latest", "askthew-mcp"]
 env = { ASKTHEW_INSTALL_TOKEN = "<ASKTHEW_INSTALL_TOKEN>", ASKTHEW_HOST_TYPE = "codex", ASKTHEW_API_URL = "https://app.askthew.com/", ASKTHEW_SERVER_NAME = "askthew" }
 ```
 
@@ -176,8 +194,8 @@ The plugin also exposes v1 API tools that map to the app's authenticated routes:
 Free PLG helpers:
 
 ```bash
-npx @askthew/mcp-plugin install-hook --pre-commit
-npx @askthew/mcp-plugin digest --weekly
+npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp install-hook --pre-commit
+npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp digest --weekly
 ```
 
 The hook prompts when staged files recently had implementation signals but no linked decision. The weekly digest writes `~/Documents/askthew-digest-YYYY-WW.md`.

package/dist/cli-actions.test.js

@@ -44,7 +44,7 @@ test("pre-commit hook installer writes the documented inline prompt hook", () =>
     const hookPath = installPreCommitHook({ cwd: dir });
     const hook = fs.readFileSync(hookPath, "utf8");
     assert.match(hook, /Ask The W pre-commit decision prompt/);
-    assert.match(hook, /@askthew\/mcp-plugin@latest hook-check --pre-commit/);
+    assert.match(hook, /--package @askthew\/mcp-plugin@latest askthew-mcp hook-check --pre-commit/);
     assert.equal((fs.statSync(hookPath).mode & 0o111) > 0, true);
     fs.rmSync(dir, { recursive: true, force: true });
 });

package/dist/cli.js

@@ -5,7 +5,7 @@ import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { createAskTheWMcpServer } from "./index.js";
-import { ensureAskTheWDataDir, identityPath } from "./lib/paths.js";
+import { askTheWDataDir, ensureAskTheWDataDir, identityPath } from "./lib/paths.js";
 import { loadCliCredentials } from "./lib/free-tier-policy.js";
 import { describeFreeIdentity, tryRegisterFreeInstall } from "./lib/free-install-registration.js";
 import { ensureLocalIdentity, loadLocalIdentity, publicIdentity } from "./lib/local-identity.js";
@@ -22,6 +22,7 @@ function usage() {
         "  askthew-mcp",
         "  askthew-mcp install --host <claude_code|codex|cursor> --token <install-token> --api-url <url> --server-name <name> [--client-id <id>] [--client-label <label>] [--dry-run] [--no-agent-instructions]",
         "  askthew-mcp install --host <claude_code|codex|cursor> --free [--email <email>] [--api-url <url>] [--server-name <name>]",
+        "  askthew-mcp refresh --host <claude_code|codex|cursor> [--free] [--token <install-token>] [--api-url <url>] [--server-name <name>] [--dry-run]",
         "  askthew-mcp uninstall --host <claude_code|codex|cursor> [--server-name <name>] [--dry-run] [--keep-local-data] [--keep-auth] [--keep-agent-instructions]",
         "  askthew-mcp identify --email <email> [--no-telemetry]",
         "  askthew-mcp identity status",
@@ -132,6 +133,16 @@ function parseInstallArgs(argv) {
 function normalizeInstallToken(token) {
     return String(token ?? "").trim().replace(/^['"]/, "").replace(/['"]$/, "");
 }
+function packageVersion() {
+    try {
+        const packagePath = fileURLToPath(new URL("../package.json", import.meta.url));
+        const parsed = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+        return typeof parsed.version === "string" ? parsed.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
 function detectLoginEmail() {
     for (const value of [
         process.env.ASKTHEW_EMAIL,
@@ -229,6 +240,10 @@ async function main() {
         }
         return;
     }
+    if (command === "refresh") {
+        await runRefreshCommand(argv);
+        return;
+    }
     if (command === "identify") {
         await runIdentifyCommand(argv);
         return;
@@ -270,7 +285,7 @@ async function main() {
         return;
     }
     if (command === "upgrade") {
-        console.log("Open https://askthew.com/mcp to upgrade, then run `askthew-mcp upgrade --finalize`.");
+        console.log("Open https://askthew.com/plugin to upgrade, then run `askthew-mcp upgrade --finalize`.");
         if (argv.includes("--finalize")) {
             console.log("Finalize will rewrite host config after a paid workspace token is available in the web app.");
         }
@@ -333,26 +348,114 @@ async function runUninstallCommand(argv) {
     const instructions = keepAgentInstructions
         ? null
         : uninstallBehaviorInstructions({ hostType, dryRun });
+    const dataDir = askTheWDataDir();
+    const hadLocalData = fs.existsSync(dataDir);
+    const authFile = identityPath();
+    const hadAuth = fs.existsSync(authFile);
     if (!keepLocalData && !dryRun) {
-        fs.rmSync(ensureAskTheWDataDir(), { recursive: true, force: true });
+        fs.rmSync(dataDir, { recursive: true, force: true });
     }
     if (!keepAuth && !dryRun) {
-        const file = identityPath();
-        if (fs.existsSync(file))
-            fs.rmSync(file, { force: true });
+        if (fs.existsSync(authFile))
+            fs.rmSync(authFile, { force: true });
     }
     console.log(dryRun ? "Ask The W plugin uninstall dry run complete." : "Ask The W plugin uninstall complete.");
     console.log(`Settings path: ${config.settingsPath}`);
+    console.log(config.removedServer
+        ? `${dryRun ? "Would remove" : "Removed"} MCP server "${config.removedServerName}".`
+        : config.foundConfigFile
+            ? `No MCP server "${config.removedServerName}" found in host config.`
+            : "No host config file found.");
     if (instructions) {
-        console.log(`Agent instructions removed: ${instructions.paths.join(", ") || "none"}`);
-    }
-    console.log(keepLocalData ? "Local data kept." : "Local data removed.");
-    console.log(keepAuth ? "Auth tokens kept." : "Auth tokens removed.");
+        console.log(instructions.paths.length > 0
+            ? `Agent instructions ${dryRun ? "would be removed from" : "removed from"}: ${instructions.paths.join(", ")}`
+            : "No Ask The W agent instruction blocks found.");
+    }
+    console.log(keepLocalData
+        ? "Local data kept."
+        : hadLocalData
+            ? `${dryRun ? "Local data would be removed" : "Local data removed"}.`
+            : "No local data directory found.");
+    console.log(keepAuth
+        ? "Auth tokens kept."
+        : hadAuth
+            ? `${dryRun ? "Local identity would be removed" : "Local identity removed"}.`
+            : "No local identity found.");
     if (dryRun) {
         console.log("");
         console.log(config.json);
     }
 }
+async function runRefreshCommand(argv) {
+    const parsed = parseInstallArgs(["--free", ...argv]);
+    const isPaidRefresh = Boolean(parsed.token && !argv.includes("--free"));
+    const options = {
+        ...parsed,
+        free: !isPaidRefresh,
+    };
+    const existingIdentity = loadLocalIdentity();
+    let freeIdentity = existingIdentity;
+    if (options.free && !options.dryRun && !freeIdentity) {
+        freeIdentity = ensureLocalIdentity({
+            emailClaim: options.email,
+            apiUrl: options.apiUrl,
+        });
+    }
+    const uninstall = uninstallHostConfig({
+        hostType: options.hostType,
+        serverName: options.serverName,
+        dryRun: options.dryRun,
+    });
+    const removedInstructions = uninstallBehaviorInstructions({
+        hostType: options.hostType,
+        dryRun: options.dryRun,
+    });
+    const install = installHostConfig(options);
+    const installedInstructions = options.installAgentInstructions
+        ? installBehaviorInstructions({
+            hostType: options.hostType,
+            dryRun: options.dryRun,
+        })
+        : null;
+    if (options.free && freeIdentity && !options.dryRun) {
+        await tryRegisterFreeInstall({
+            identity: freeIdentity,
+            deviceLabel: options.clientLabel ?? `${options.hostType} free refresh`,
+            repo: {
+                repoName: process.env.ASKTHEW_REPO_NAME,
+                repoRoot: process.env.ASKTHEW_REPO_ROOT,
+                hostType: options.hostType,
+            },
+            options: { apiUrl: options.apiUrl },
+        });
+    }
+    console.log(options.dryRun ? "Ask The W plugin refresh dry run complete." : "Ask The W plugin refresh complete.");
+    console.log(`Plugin package version: ${packageVersion()}`);
+    console.log(`Settings path: ${install.settingsPath}`);
+    console.log(`Removed instructions: ${removedInstructions.paths.join(", ") || "none"}`);
+    if (installedInstructions) {
+        console.log(`Installed instructions: ${installedInstructions.paths.join(", ") || installedInstructions.path}`);
+    }
+    if (options.free) {
+        console.log(freeIdentity
+            ? `Local identity preserved: ${freeIdentity.installId}`
+            : "Local identity would be created on a non-dry-run refresh.");
+        console.log("Local data preserved: ~/.askthew/store.sqlite");
+    }
+    else {
+        const heartbeatSent = install.wroteFile
+            ? await sendInstallHeartbeat(options).catch(() => false)
+            : false;
+        console.log(heartbeatSent ? "Paid workspace heartbeat sent." : "Paid workspace heartbeat not sent yet.");
+    }
+    console.log(`Next step: ${install.nextStep}`);
+    if (options.dryRun) {
+        console.log("");
+        console.log(uninstall.json);
+        console.log("");
+        console.log(install.json);
+    }
+}
 function argValue(argv, name) {
     const index = argv.indexOf(name);
     return index >= 0 ? argv[index + 1] : undefined;
@@ -474,7 +577,7 @@ async function runHookCheckCommand(argv) {
     const gap = preCommitDecisionGap({ store, stagedFiles: stagedFiles(), scopeKey: localScopeKey() });
     if (gap.missing) {
         console.log('Ask The W: this change has no decision attached, draft one?');
-        console.log("Run: npx @askthew/mcp-plugin digest --weekly or ask your agent to call promote_signal_to_decision.");
+        console.log("Run: npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp digest --weekly or ask your agent to call promote_signal_to_decision.");
     }
 }
 async function runDigestCommand(argv) {
@@ -502,7 +605,17 @@ async function runSyncCommand(argv) {
     }
     console.log(JSON.stringify(await uploadLocalStore({ store, credentials, syncToken }), null, 2));
 }
-const isDirectCliExecution = Boolean(process.argv[1]) && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+const isDirectCliExecution = Boolean(process.argv[1]) &&
+    (() => {
+        const cliPath = fileURLToPath(import.meta.url);
+        const invokedPath = path.resolve(process.argv[1]);
+        try {
+            return fs.realpathSync(invokedPath) === fs.realpathSync(cliPath);
+        }
+        catch {
+            return invokedPath === cliPath;
+        }
+    })();
 if (isDirectCliExecution) {
     main().catch((error) => {
         if (error instanceof Error) {

package/dist/cli.test.js

@@ -38,6 +38,34 @@ function runCli(input) {
         },
     });
 }
+function runCliViaBinSymlink(input) {
+    const binDir = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-cli-bin-"));
+    const binPath = path.join(binDir, "askthew-mcp");
+    fs.symlinkSync(cliPath, binPath);
+    try {
+        return spawnSync(binPath, input.args, {
+            cwd: input.cwd,
+            encoding: "utf8",
+            env: {
+                ...process.env,
+                PATH: `${binDir}${path.delimiter}${process.env.PATH ?? ""}`,
+                HOME: input.home,
+                USERPROFILE: input.home,
+                ASKTHEW_DATA_DIR: input.dataDir,
+                ASKTHEW_EMAIL: "founder@example.com",
+                ASKTHEW_CLI_TOKEN: "",
+                ASKTHEW_CLI_TOKEN_ID: "",
+                ASKTHEW_USER_ID: "",
+                ASKTHEW_INSTALL_TOKEN: "",
+                ASKTHEW_FREE_MODE: "",
+                ...(input.extraEnv ?? {}),
+            },
+        });
+    }
+    finally {
+        fs.rmSync(binDir, { recursive: true, force: true });
+    }
+}
 async function withCliEnv(dataDir, fn) {
     const previous = {
         ASKTHEW_DATA_DIR: process.env.ASKTHEW_DATA_DIR,
@@ -93,6 +121,41 @@ test("free install without prior auth writes config, instructions, and local ide
         fs.rmSync(fixture.root, { recursive: true, force: true });
     }
 });
+test("published-style bin symlink runs free install instead of silently exiting", () => {
+    const fixture = makeFixture();
+    try {
+        const help = runCliViaBinSymlink({
+            args: ["--help"],
+            cwd: fixture.project,
+            home: fixture.home,
+            dataDir: fixture.dataDir,
+        });
+        assert.equal(help.status, 0, help.stderr);
+        assert.match(help.stdout, /Ask The W Coding Agent Connector/);
+        const result = runCliViaBinSymlink({
+            args: [
+                "install",
+                "--host",
+                "codex",
+                "--free",
+                "--email",
+                "founder@example.com",
+                "--api-url",
+                "http://127.0.0.1:9",
+                "--dry-run",
+            ],
+            cwd: fixture.project,
+            home: fixture.home,
+            dataDir: fixture.dataDir,
+        });
+        assert.equal(result.status, 0, result.stderr);
+        assert.match(result.stdout, /Ask The W plugin dry run complete/);
+        assert.match(result.stdout, /--package @askthew\/mcp-plugin@latest askthew-mcp install/);
+    }
+    finally {
+        fs.rmSync(fixture.root, { recursive: true, force: true });
+    }
+});
 test("free install dry-run stays non-mutating and does not create identity", () => {
     const fixture = makeFixture();
     try {
@@ -138,6 +201,57 @@ test("free install ignores stale legacy credentials and writes local identity",
         fs.rmSync(fixture.root, { recursive: true, force: true });
     }
 });
+test("refresh rewrites host config and instructions while preserving local identity and data", () => {
+    const fixture = makeFixture();
+    try {
+        const install = runCli({
+            args: ["install", "--host", "claude_code", "--free", "--email", "founder@example.com", "--api-url", "http://127.0.0.1:9"],
+            cwd: fixture.project,
+            home: fixture.home,
+            dataDir: fixture.dataDir,
+        });
+        assert.equal(install.status, 0, install.stderr);
+        const beforeIdentity = JSON.parse(fs.readFileSync(path.join(fixture.dataDir, "identity.json"), "utf8"));
+        fs.writeFileSync(path.join(fixture.dataDir, "store.sqlite"), "keep me", "utf8");
+        const refresh = runCli({
+            args: ["refresh", "--host", "claude_code", "--api-url", "http://127.0.0.1:9"],
+            cwd: fixture.project,
+            home: fixture.home,
+            dataDir: fixture.dataDir,
+        });
+        assert.equal(refresh.status, 0, refresh.stderr);
+        assert.match(refresh.stdout, /plugin refresh complete/);
+        assert.match(refresh.stdout, /Local identity preserved/);
+        assert.match(refresh.stdout, /Plugin package version:/);
+        const afterIdentity = JSON.parse(fs.readFileSync(path.join(fixture.dataDir, "identity.json"), "utf8"));
+        assert.equal(afterIdentity.installId, beforeIdentity.installId);
+        assert.equal(afterIdentity.emailClaim, "founder@example.com");
+        assert.equal(fs.readFileSync(path.join(fixture.dataDir, "store.sqlite"), "utf8"), "keep me");
+        assert.match(fs.readFileSync(path.join(fixture.project, "CLAUDE.md"), "utf8"), /ASKTHEW_PLUGIN_INSTRUCTIONS_START/);
+        assert.match(fs.readFileSync(path.join(fixture.project, "AGENTS.md"), "utf8"), /ASKTHEW_PLUGIN_INSTRUCTIONS_START/);
+    }
+    finally {
+        fs.rmSync(fixture.root, { recursive: true, force: true });
+    }
+});
+test("refresh dry-run does not create a local identity", () => {
+    const fixture = makeFixture();
+    try {
+        const refresh = runCli({
+            args: ["refresh", "--host", "codex", "--dry-run"],
+            cwd: fixture.project,
+            home: fixture.home,
+            dataDir: fixture.dataDir,
+        });
+        assert.equal(refresh.status, 0, refresh.stderr);
+        assert.match(refresh.stdout, /refresh dry run complete/);
+        assert.equal(fs.existsSync(path.join(fixture.dataDir, "identity.json")), false);
+        assert.equal(fs.existsSync(path.join(fixture.home, ".codex", "config.toml")), false);
+    }
+    finally {
+        fs.rmSync(fixture.root, { recursive: true, force: true });
+    }
+});
 test("auth status reports missing local identity without pending-code guidance", () => {
     const fixture = makeFixture();
     try {

package/dist/index.js

@@ -482,10 +482,10 @@ function loginCommandHint() {
     ]) {
         const email = String(value ?? "").trim();
         if (/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) {
-            return `npx @askthew/mcp-plugin identify --email ${email}`;
+            return `npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp identify --email ${email}`;
         }
     }
-    return "npx @askthew/mcp-plugin identify --email <your-email>";
+    return "npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp identify --email <your-email>";
 }
 async function sendStartupHeartbeat(options) {
     if (!hasServerIdentity(options?.credentials)) {
@@ -1278,7 +1278,7 @@ export function createAskTheWMcpServer(options = {}) {
                 extra: {
                     tool: "review_session",
                     limit: 3,
-                    upgradeUrl: "https://askthew.com/mcp?utm_source=mcp-plugin&utm_medium=tool-nudge&utm_campaign=mcp-free&tool=review_session",
+                    upgradeUrl: "https://askthew.com/plugin?utm_source=mcp-plugin&utm_medium=tool-nudge&utm_campaign=mcp-free&tool=review_session",
                     cta: "Upgrade to review more than three sessions in the workspace dashboard.",
                 },
             });

package/dist/index.test.js

@@ -743,7 +743,7 @@ test("free decisions, recap, coach, and promote return human-readable compact ou
             assert.equal(response.ok, false);
             assert.equal(response.code, "free_tier_paid_feature");
             assert.equal(response.tool, "coach");
-            assert.match(response.upgradeUrl, /askthew\.com\/mcp/);
+            assert.match(response.upgradeUrl, /askthew\.com\/plugin/);
         }
     });
 });
@@ -910,7 +910,7 @@ test("free review_session markdown is capped and json is cursor-paginated with a
         assert.equal(capped.ok, false);
         assert.equal(capped.code, "free_tier_limit");
         assert.equal(capped.limit, 3);
-        assert.match(capped.upgradeUrl, /askthew\.com\/mcp/);
+        assert.match(capped.upgradeUrl, /askthew\.com\/plugin/);
     });
 });
 test("paid tools return canonical paywall envelope before transport in free mode", async () => {
@@ -943,7 +943,7 @@ test("paid tools return canonical paywall envelope before transport in free mode
             assert.equal(response.ok, false, toolName);
             assert.equal(response.code, "free_tier_paid_feature", toolName);
             assert.equal(response.tool, toolName, toolName);
-            assert.match(response.upgradeUrl, /askthew\.com\/mcp/, toolName);
+            assert.match(response.upgradeUrl, /askthew\.com\/plugin/, toolName);
             assert.equal(response.supportEmail, "support@askthew.com", toolName);
         }
     });

package/dist/install.d.ts

@@ -111,6 +111,8 @@ export declare function uninstallHostConfig(input: UninstallHostConfigInput): {
     settingsPath: string;
     json: string;
     removedServerName: string;
+    foundConfigFile: boolean;
+    removedServer: boolean;
     wroteFile: boolean;
 };
 export declare function sendInstallHeartbeat(input: HostConfigInput & {

package/dist/install.js

@@ -21,7 +21,7 @@ export function createServerEntry(input) {
     const scope = resolvePluginScope(input.cwd ?? process.cwd());
     return {
         command: "npx",
-        args: ["-y", "--prefer-online", "@askthew/mcp-plugin@latest"],
+        args: ["-y", "--prefer-online", "--package", "@askthew/mcp-plugin@latest", "askthew-mcp"],
         env: {
             ASKTHEW_API_URL: input.apiUrl,
             ...(input.free ? { ASKTHEW_FREE_MODE: "1" } : { ASKTHEW_INSTALL_TOKEN: input.token ?? "" }),
@@ -133,24 +133,23 @@ export function formatInstallCommand(input) {
         "npx",
         "-y",
         "--prefer-online",
+        "--package",
         "@askthew/mcp-plugin@latest",
+        "askthew-mcp",
         "install",
         "--host",
         input.hostType,
+        ...(input.free ? ["--free"] : ["--token", JSON.stringify(input.token ?? "")]),
         "--api-url",
         JSON.stringify(input.apiUrl),
         "--server-name",
         JSON.stringify(input.serverName),
     ];
     if (input.free) {
-        parts.push("--free");
         if (input.email) {
             parts.push("--email", JSON.stringify(input.email));
         }
     }
-    else {
-        parts.splice(7, 0, "--token", JSON.stringify(input.token ?? ""));
-    }
     return parts.join(" ");
 }
 export function verificationNextStep(hostType) {
@@ -219,9 +218,13 @@ export function uninstallHostConfig(input) {
     });
     const serverName = input.serverName?.trim() || "askthew";
     let json = "";
+    let foundConfigFile = false;
+    let removedServer = false;
     if (fs.existsSync(settingsPath)) {
+        foundConfigFile = true;
         const raw = fs.readFileSync(settingsPath, "utf8");
         if (input.hostType === "codex") {
+            removedServer = raw !== removeCodexTomlServer(raw, serverName) || (serverName !== "askthew" && raw !== removeCodexTomlServer(raw, "askthew"));
             json = removeCodexTomlServer(raw, serverName);
             if (serverName !== "askthew") {
                 json = removeCodexTomlServer(json, "askthew");
@@ -236,6 +239,7 @@ export function uninstallHostConfig(input) {
                 const existingProject = isRecord(existingProjects[cwd]) ? existingProjects[cwd] : {};
                 const existingMcpServers = isRecord(existingProject.mcpServers) ? existingProject.mcpServers : {};
                 const nextServers = { ...existingMcpServers };
+                removedServer = serverName in nextServers || (serverName !== "askthew" && "askthew" in nextServers);
                 delete nextServers[serverName];
                 if (serverName !== "askthew")
                     delete nextServers.askthew;
@@ -253,6 +257,7 @@ export function uninstallHostConfig(input) {
             else {
                 const existingMcpServers = isRecord(parsed.mcpServers) ? parsed.mcpServers : {};
                 const nextServers = { ...existingMcpServers };
+                removedServer = serverName in nextServers || (serverName !== "askthew" && "askthew" in nextServers);
                 delete nextServers[serverName];
                 if (serverName !== "askthew")
                     delete nextServers.askthew;
@@ -268,7 +273,9 @@ export function uninstallHostConfig(input) {
         settingsPath,
         json,
         removedServerName: serverName,
-        wroteFile: !input.dryRun,
+        foundConfigFile,
+        removedServer,
+        wroteFile: !input.dryRun && foundConfigFile,
     };
 }
 export async function sendInstallHeartbeat(input) {

package/dist/install.test.js

@@ -29,7 +29,7 @@ test("mergeHostSettings preserves unrelated MCP servers and replaces askthew", (
     assert.deepEqual(Object.keys(merged.mcpServers ?? {}).sort(), ["askthew_workspace_a", "github"]);
     assert.deepEqual(merged.mcpServers.askthew_workspace_a, {
         command: "npx",
-        args: ["-y", "--prefer-online", "@askthew/mcp-plugin@latest"],
+        args: ["-y", "--prefer-online", "--package", "@askthew/mcp-plugin@latest", "askthew-mcp"],
         env: {
             ASKTHEW_INSTALL_TOKEN: "token-123",
             ASKTHEW_API_URL: "https://askthew.example.com",
@@ -176,7 +176,7 @@ test("formatInstallCommand emits the one-command guided install form", () => {
         apiUrl: "https://askthew.example.com",
         serverName: "askthew_workspace_a",
     });
-    assert.equal(command, 'npx -y --prefer-online @askthew/mcp-plugin@latest install --host codex --token "token-abc" --api-url "https://askthew.example.com" --server-name "askthew_workspace_a"');
+    assert.equal(command, 'npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp install --host codex --token "token-abc" --api-url "https://askthew.example.com" --server-name "askthew_workspace_a"');
 });
 test("verificationNextStep points users to every-session startup capture", () => {
     const nextStep = verificationNextStep("codex");
@@ -289,9 +289,26 @@ test("uninstall removes host config and Ask The W agent instruction blocks", ()
         cwd: tempRoot,
     });
     assert.doesNotMatch(fs.readFileSync(removed.settingsPath, "utf8"), /askthew/);
+    assert.equal(removed.foundConfigFile, true);
+    assert.equal(removed.removedServer, true);
+    assert.equal(removed.wroteFile, true);
     assert.equal(instructions.paths.length, 2);
     assert.doesNotMatch(fs.readFileSync(path.join(tempRoot, "AGENTS.md"), "utf8"), /ASKTHEW_PLUGIN_INSTRUCTIONS_START/);
     assert.doesNotMatch(fs.readFileSync(path.join(tempRoot, "CLAUDE.md"), "utf8"), /ASKTHEW_PLUGIN_INSTRUCTIONS_START/);
     fs.rmSync(tempHome, { recursive: true, force: true });
     fs.rmSync(tempRoot, { recursive: true, force: true });
 });
+test("uninstall reports when no broken-npx install artifacts exist", () => {
+    const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-uninstall-empty-home-"));
+    const removed = uninstallHostConfig({
+        hostType: "codex",
+        serverName: "askthew",
+        homeDirectory: tempHome,
+        dryRun: true,
+    });
+    assert.equal(removed.foundConfigFile, false);
+    assert.equal(removed.removedServer, false);
+    assert.equal(removed.wroteFile, false);
+    assert.equal(removed.json, "");
+    fs.rmSync(tempHome, { recursive: true, force: true });
+});

package/dist/lib/cli-actions.js

@@ -22,7 +22,7 @@ export function installPreCommitHook(input = {}) {
     const hook = [
         "#!/bin/sh",
         "# Ask The W pre-commit decision prompt",
-        "npx -y --prefer-online @askthew/mcp-plugin@latest hook-check --pre-commit",
+        "npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp hook-check --pre-commit",
         "",
     ].join("\n");
     fs.mkdirSync(path.dirname(hookPath), { recursive: true });

package/dist/lib/upgrade-nudge.js

@@ -20,9 +20,9 @@ export function paidFeatureNudge(tool) {
         tool,
         message: `${feature.label} ${feature.verb} a paid feature. See ${PRICING_URL}.`,
         pricingUrl: PRICING_URL,
-        upgradeUrl: `https://askthew.com/mcp?utm_source=mcp-plugin&utm_medium=tool-nudge&utm_campaign=mcp-free&tool=${encodeURIComponent(tool)}`,
+        upgradeUrl: `https://askthew.com/plugin?utm_source=mcp-plugin&utm_medium=tool-nudge&utm_campaign=mcp-free&tool=${encodeURIComponent(tool)}`,
         supportEmail: SUPPORT_EMAIL,
-        cta: "Run: npx @askthew/mcp-plugin upgrade",
+        cta: "Run: npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp upgrade",
     };
 }
 export function toolJson(value) {

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@askthew/mcp-plugin",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "private": false,
   "description": "Ask The W plugin connector for local-first coding-agent decisions, signals, and review.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "askthew-mcp": "dist/cli.js"
+    "askthew-mcp": "dist/cli.js",
+    "mcp-plugin": "dist/cli.js"
   },
   "files": [
     "README.md",