doc2mcp 0.1.17 → 0.1.18

package/README.md

@@ -29,6 +29,20 @@ npm install -g doc2mcp
 > Install with **`-g`** (global). The `doc2mcp` command only lands on your `PATH` when installed globally.
 > If you ran `npm i doc2mcp` (without `-g`) and see `command not found: doc2mcp`, either reinstall with `-g`
 > or run it through your package runner: `npx doc2mcp <docs-url>`.
+>
+> If `npm install -g doc2mcp` succeeds but `doc2mcp` is still `command not found`, your npm global bin folder is
+> not on PATH. Run:
+>
+> ```bash
+> echo 'export PATH="'$(npm prefix -g)'/bin:$PATH"' >> ~/.zshrc
+> source ~/.zshrc
+> ```
+>
+> Quick no-setup option:
+>
+> ```bash
+> npx doc2mcp login
+> ```
 
 Other package managers:
 
@@ -54,6 +68,9 @@ doc2mcp https://docs.stripe.com
 
 # 4. Chat with your docs without leaving the terminal
 doc2mcp chat
+
+# Or paste a docs URL directly into chat mode
+doc2mcp chat https://uagents.fetch.ai/docs
 ```
 
 That's it. The same hosted pipeline powers the [website](https://doc2mcp.site), so a project you
@@ -69,7 +86,7 @@ create in the CLI shows up in your dashboard and marketplace too.
 | [`doc2mcp whoami`](#doc2mcp-whoami) | Show the account you're signed in as |
 | [`doc2mcp list`](#doc2mcp-list) | List the MCP projects on your account |
 | [`doc2mcp install <projectId>`](#doc2mcp-install-projectid) | Install an existing MCP into your editors |
-| [`doc2mcp chat [projectId]`](#doc2mcp-chat-projectid) | Chat with your docs in the terminal (AI answers from your MCP) |
+| [`doc2mcp chat [target]`](#doc2mcp-chat-target) | Chat with your docs in the terminal; target can be a project ID or docs URL |
 | `doc2mcp --version` | Print the installed CLI version |
 | `doc2mcp --help` | Show usage and all commands |
 
@@ -166,16 +183,19 @@ Existing config is merged, not overwritten.
 
 ---
 
-### `doc2mcp chat [projectId]`
+### `doc2mcp chat [target]`
 
 Chat with your docs **right from the terminal**. doc2mcp answers natural-language questions from
 the crawled documentation — with cited sources — using the project's hosted MCP (the same
-`ask_documentation` tool your editor calls). This is the Playground experience, in your shell.
+`ask_documentation` tool your editor calls). This is the Playground experience, in a Claude Code-style shell loop.
 
 ```bash
-# Interactive: choose a project, then ask anything
+# Interactive: paste a docs URL, project ID, or choose an existing MCP
 doc2mcp chat
 
+# Paste a docs URL directly: doc2mcp converts it, then starts chat
+doc2mcp chat https://uagents.fetch.ai/docs
+
 # Skip the picker by passing a project ID
 doc2mcp chat prj_123abc
 
@@ -184,7 +204,7 @@ doc2mcp chat prj_123abc -m "How do I authenticate requests?"
 ```
 
 - With no arguments, you pick from your `ready` projects.
-- Type `/exit` (or press Esc) to leave an interactive session.
+- Type `/exit` to leave an interactive session.
 - Each answer lists the source pages it used so you can verify it.
 
 ## Configuration
@@ -198,7 +218,8 @@ doc2mcp chat prj_123abc -m "How do I authenticate requests?"
 
 | Symptom | Fix |
 | --- | --- |
-| `command not found: doc2mcp` | You installed locally or your shell cached PATH. Reinstall with `npm i -g doc2mcp`, then run `hash -r` or open a new terminal. You can also use `npx doc2mcp <url>`. |
+| `command not found: doc2mcp` | You installed locally or npm's global bin is not on PATH. Use `npx doc2mcp <url>`, or add `$(npm prefix -g)/bin` to PATH in `~/.zshrc`. |
+| `pnpm add -g doc2mcp` says `ERR_PNPM_NO_GLOBAL_BIN_DIR` | Run `pnpm setup`, then `source ~/.zshrc`, then retry `pnpm add -g doc2mcp`. |
 | Browser doesn't open on `login` | Copy the printed URL into your browser manually, then approve. |
 | `login` can't reach the server | Confirm you're online; for self-hosting set `DOC2MCP_API_URL` to your instance. |
 | "Limit reached" | You've hit your plan's monthly conversion limit (shared across CLI and web). |

package/dist/index.js

@@ -74,9 +74,10 @@ async function runWhoami() {
 }
 
 // src/commands/chat.ts
-import { cancel, intro, isCancel, outro, select, text } from "@clack/prompts";
+import { createInterface } from "readline/promises";
+import { stdin as input, stdout as output } from "process";
 import ora2 from "ora";
-import pc4 from "picocolors";
+import pc6 from "picocolors";
 
 // src/api.ts
 import pc2 from "picocolors";
@@ -90,14 +91,14 @@ var ApiError = class extends Error {
   }
 };
 async function parseJson(response) {
-  const text2 = await response.text();
-  if (!text2) {
+  const text = await response.text();
+  if (!text) {
     return null;
   }
   try {
-    return JSON.parse(text2);
+    return JSON.parse(text);
   } catch {
-    return { raw: text2 };
+    return { raw: text };
   }
 }
 async function apiFetch(path, options = {}) {
@@ -138,6 +139,9 @@ function printError(error) {
 `);
 }
 
+// src/commands/convert.ts
+import pc5 from "picocolors";
+
 // src/commands/login.ts
 import open from "open";
 import ora from "ora";
@@ -232,151 +236,9 @@ async function ensureLoggedIn() {
   }
 }
 
-// src/commands/chat.ts
-async function pickProject(explicitId) {
-  if (explicitId) {
-    return await apiFetch(`/api/cli/projects/${explicitId}`);
-  }
-  const data = await apiFetch(
-    "/api/cli/projects"
-  );
-  const ready = data.projects.filter((p) => p.status === "ready");
-  if (ready.length === 0) {
-    process.stdout.write(
-      `${pc4.yellow("No ready MCP projects yet.")} Create one: ${pc4.bold("doc2mcp <docs-url>")}
-`
-    );
-    return null;
-  }
-  const choice = await select({
-    message: "Which docs do you want to chat with?",
-    options: ready.map((p) => ({
-      value: p.id,
-      label: p.name,
-      hint: p.sourceUrl ?? void 0
-    }))
-  });
-  if (isCancel(choice)) {
-    cancel("Cancelled.");
-    return null;
-  }
-  return await apiFetch(`/api/cli/projects/${choice}`);
-}
-async function askDocs(mcp, question) {
-  const response = await fetch(mcp.url, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: `Bearer ${mcp.token}`
-    },
-    body: JSON.stringify({
-      jsonrpc: "2.0",
-      id: 1,
-      method: "tools/call",
-      params: { name: "ask_documentation", arguments: { question } }
-    })
-  });
-  const payload = await response.json();
-  if (!response.ok || payload.error) {
-    throw new ApiError(
-      payload.error?.message ?? `MCP request failed (${response.status})`,
-      response.status,
-      payload
-    );
-  }
-  const raw = payload.result?.content?.[0]?.text ?? "";
-  try {
-    return JSON.parse(raw);
-  } catch {
-    return { question, answer: raw };
-  }
-}
-function renderAnswer(answer) {
-  process.stdout.write(`
-${pc4.cyan("\u25C6")} ${answer.answer.trim()}
-`);
-  if (answer.sources && answer.sources.length > 0) {
-    process.stdout.write(`
-${pc4.dim("Sources:")}
-`);
-    for (const source of answer.sources.slice(0, 6)) {
-      process.stdout.write(`  ${pc4.dim("\u2022")} ${source.title} ${pc4.dim(source.url)}
-`);
-    }
-  }
-  process.stdout.write("\n");
-}
-async function answerOnce(mcp, question) {
-  const spinner = ora2("Thinking\u2026").start();
-  try {
-    const answer = await askDocs(mcp, question);
-    spinner.stop();
-    renderAnswer(answer);
-  } catch (error) {
-    spinner.fail("Failed to get an answer");
-    printError(error);
-  }
-}
-async function runChat(projectId, options = {}) {
-  try {
-    await ensureLoggedIn();
-    const detail = await pickProject(projectId);
-    if (!detail) {
-      return;
-    }
-    if (!detail.mcp) {
-      process.stderr.write(
-        `${pc4.red("That project is not ready yet.")} Check: ${pc4.bold("doc2mcp list")}
-`
-      );
-      process.exitCode = 1;
-      return;
-    }
-    const { mcp } = detail;
-    if (options.message) {
-      await answerOnce(mcp, options.message);
-      return;
-    }
-    intro(
-      `${pc4.bold(`Chatting with ${detail.project.name}`)} ${pc4.dim("\u2014 ask anything about these docs")}`
-    );
-    process.stdout.write(
-      `${pc4.dim("Type your question. Use /exit to leave.")}
-`
-    );
-    let active = true;
-    while (active) {
-      const question = await text({
-        message: "You",
-        placeholder: "How do I authenticate requests?"
-      });
-      if (isCancel(question)) {
-        active = false;
-        break;
-      }
-      const trimmed = String(question).trim();
-      if (!trimmed) {
-        continue;
-      }
-      if (trimmed === "/exit" || trimmed === "/quit") {
-        active = false;
-        break;
-      }
-      await answerOnce(mcp, trimmed);
-    }
-    outro(pc4.dim("Bye \u2014 your docs MCP stays live for your editor."));
-  } catch (error) {
-    printError(error);
-    process.exitCode = 1;
-  }
-}
-
-// src/commands/convert.ts
-import pc6 from "picocolors";
-
 // src/commands/install.ts
 import { confirm, multiselect } from "@clack/prompts";
-import pc5 from "picocolors";
+import pc4 from "picocolors";
 
 // src/installers/detect.ts
 import { access } from "fs/promises";
@@ -563,8 +425,8 @@ async function promptInstall(install) {
     }
     await installToClient(client.id, client.configPath, install);
     process.stdout.write(
-      `${pc5.green("Installed")} ${client.label}
-${pc5.dim(client.configPath)}
+      `${pc4.green("Installed")} ${client.label}
+${pc4.dim(client.configPath)}
 `
     );
   }
@@ -574,7 +436,7 @@ async function runInstallCommand(projectId) {
     await ensureLoggedIn();
     const detail = await apiFetch(`/api/cli/projects/${projectId}`);
     if (!detail.install) {
-      process.stderr.write(`${pc5.red("Project is not ready or missing install bundle.")}
+      process.stderr.write(`${pc4.red("Project is not ready or missing install bundle.")}
 `);
       process.exitCode = 1;
       return;
@@ -595,66 +457,72 @@ function sleep2(ms) {
 function printStatus(detail) {
   const { project } = detail;
   process.stdout.write(
-    `\r${pc6.cyan("Status:")} ${project.status.padEnd(12)} ${pc6.dim(project.name)}`
+    `\r${pc5.cyan("Status:")} ${project.status.padEnd(12)} ${pc5.dim(project.name)}`
   );
 }
-async function runConvert(sourceUrl) {
-  try {
-    await ensureLoggedIn();
-    process.stdout.write(`${pc6.bold("Converting")} ${sourceUrl}
+async function convertUrlToProject(sourceUrl, options = { offerInstall: true }) {
+  await ensureLoggedIn();
+  process.stdout.write(`${pc5.bold("Converting")} ${sourceUrl}
 `);
-    const created = await apiFetch("/api/cli/convert", {
-      method: "POST",
-      body: JSON.stringify({ sourceUrl })
-    });
-    process.stdout.write(`${pc6.dim("Project:")} ${created.id}
+  const created = await apiFetch("/api/cli/convert", {
+    method: "POST",
+    body: JSON.stringify({ sourceUrl })
+  });
+  process.stdout.write(`${pc5.dim("Project:")} ${created.id}
 `);
-    let delayMs = 2e3;
-    const terminal = /* @__PURE__ */ new Set(["ready", "error"]);
-    while (true) {
-      const detail = await apiFetch(
-        `/api/cli/projects/${created.id}`
-      );
-      printStatus(detail);
-      if (terminal.has(detail.project.status)) {
-        process.stdout.write("\n");
-        break;
-      }
-      await sleep2(delayMs);
-      delayMs = Math.min(delayMs + 1e3, 1e4);
-    }
-    const finalDetail = await apiFetch(
+  let delayMs = 2e3;
+  const terminal = /* @__PURE__ */ new Set(["ready", "error"]);
+  while (true) {
+    const detail = await apiFetch(
       `/api/cli/projects/${created.id}`
     );
-    if (finalDetail.project.status === "error") {
-      const lastLog = finalDetail.project.logs.at(-1);
-      process.stderr.write(
-        `${pc6.red("Conversion failed.")}${lastLog ? ` ${lastLog.message}` : ""}
-`
-      );
-      process.exitCode = 1;
-      return;
+    printStatus(detail);
+    if (terminal.has(detail.project.status)) {
+      process.stdout.write("\n");
+      break;
     }
-    if (!finalDetail.mcp || !finalDetail.install) {
-      process.stderr.write(`${pc6.red("MCP ready but missing install bundle.")}
+    await sleep2(delayMs);
+    delayMs = Math.min(delayMs + 1e3, 1e4);
+  }
+  const finalDetail = await apiFetch(
+    `/api/cli/projects/${created.id}`
+  );
+  if (finalDetail.project.status === "error") {
+    const lastLog = finalDetail.project.logs.at(-1);
+    process.stderr.write(
+      `${pc5.red("Conversion failed.")}${lastLog ? ` ${lastLog.message}` : ""}
+`
+    );
+    process.exitCode = 1;
+    return null;
+  }
+  if (!finalDetail.mcp || !finalDetail.install) {
+    process.stderr.write(`${pc5.red("MCP ready but missing install bundle.")}
 `);
-      process.exitCode = 1;
-      return;
-    }
-    process.stdout.write(`
-${pc6.green("MCP ready")}
+    process.exitCode = 1;
+    return null;
+  }
+  process.stdout.write(`
+${pc5.green("MCP ready")}
 `);
-    process.stdout.write(`${pc6.bold("Server:")} ${finalDetail.mcp.serverName}
+  process.stdout.write(`${pc5.bold("Server:")} ${finalDetail.mcp.serverName}
 `);
-    process.stdout.write(`${pc6.bold("URL:")} ${finalDetail.mcp.url}
+  process.stdout.write(`${pc5.bold("URL:")} ${finalDetail.mcp.url}
 `);
-    process.stdout.write(`${pc6.bold("Token:")} ${finalDetail.mcp.token}
+  process.stdout.write(`${pc5.bold("Token:")} ${finalDetail.mcp.token}
 `);
-    process.stdout.write(
-      `${pc6.dim("Also listed in the doc2mcp marketplace when ready.")}
+  process.stdout.write(
+    `${pc5.dim("Also listed in the doc2mcp marketplace when ready.")}
 `
-    );
+  );
+  if (options.offerInstall) {
     await promptInstall(finalDetail.install);
+  }
+  return finalDetail;
+}
+async function runConvert(sourceUrl) {
+  try {
+    await convertUrlToProject(sourceUrl, { offerInstall: true });
   } catch (error) {
     printError(error);
     process.exitCode = 1;
@@ -665,18 +533,225 @@ async function runList() {
     await ensureLoggedIn();
     const data = await apiFetch("/api/cli/projects");
     if (data.projects.length === 0) {
-      process.stdout.write(`${pc6.dim("No projects yet.")}
+      process.stdout.write(`${pc5.dim("No projects yet.")}
 `);
       return;
     }
     for (const project of data.projects) {
       process.stdout.write(
-        `${pc6.bold(project.name)} ${pc6.dim(`[${project.status}]`)} ${project.source}
+        `${pc5.bold(project.name)} ${pc5.dim(`[${project.status}]`)} ${project.source}
+`
+      );
+      process.stdout.write(`  ${pc5.dim(project.id)} ${project.sourceUrl ?? ""}
+`);
+    }
+  } catch (error) {
+    printError(error);
+    process.exitCode = 1;
+  }
+}
+
+// src/commands/chat.ts
+function isDocsUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function createPrompt() {
+  return createInterface({ input, output });
+}
+async function readLine(prompt) {
+  const rl = createPrompt();
+  try {
+    const answer = await rl.question(prompt);
+    return answer.trim();
+  } catch {
+    return null;
+  } finally {
+    rl.close();
+  }
+}
+async function listReadyProjects() {
+  const data = await apiFetch(
+    "/api/cli/projects"
+  );
+  return data.projects.filter((p) => p.status === "ready");
+}
+async function pickExistingProject() {
+  const ready = await listReadyProjects();
+  if (ready.length === 0) {
+    process.stdout.write(
+      `${pc6.yellow("No ready MCP projects yet.")} Paste a docs URL to create one.
+`
+    );
+    return null;
+  }
+  process.stdout.write(`${pc6.dim("Ready MCPs")}
+`);
+  ready.forEach((p, index) => {
+    process.stdout.write(
+      `  ${pc6.cyan(String(index + 1).padStart(2, " "))}. ${pc6.bold(p.name)} ${pc6.dim(p.sourceUrl ?? p.id)}
+`
+    );
+  });
+  const choice = await readLine(
+    `${pc6.bold(">")} choose number, paste URL, or paste project id: `
+  );
+  if (!choice) {
+    return null;
+  }
+  if (isDocsUrl(choice)) {
+    return await convertUrlToProject(choice, { offerInstall: false });
+  }
+  const chosenIndex = Number(choice);
+  if (Number.isInteger(chosenIndex) && chosenIndex > 0) {
+    const project = ready.at(chosenIndex - 1);
+    if (project) {
+      return await apiFetch(`/api/cli/projects/${project.id}`);
+    }
+  }
+  return await apiFetch(`/api/cli/projects/${choice}`);
+}
+async function resolveProject(target) {
+  if (target) {
+    if (isDocsUrl(target)) {
+      return await convertUrlToProject(target, { offerInstall: false });
+    }
+    return await apiFetch(`/api/cli/projects/${target}`);
+  }
+  process.stdout.write(`${pc6.bold("doc2mcp chat")}
+`);
+  process.stdout.write(
+    `${pc6.dim("Paste a docs URL to create a new MCP, paste a project id, or press Enter to choose existing.")}
+
+`
+  );
+  const first = await readLine(`${pc6.bold(">")} docs url or project id: `);
+  if (!first) {
+    return await pickExistingProject();
+  }
+  if (isDocsUrl(first)) {
+    return await convertUrlToProject(first, { offerInstall: false });
+  }
+  return await apiFetch(`/api/cli/projects/${first}`);
+}
+async function askDocs(mcp, question) {
+  const response = await fetch(mcp.url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${mcp.token}`
+    },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "tools/call",
+      params: { name: "ask_documentation", arguments: { question } }
+    })
+  });
+  const payload = await response.json();
+  if (!response.ok || payload.error) {
+    throw new ApiError(
+      payload.error?.message ?? `MCP request failed (${response.status})`,
+      response.status,
+      payload
+    );
+  }
+  const raw = payload.result?.content?.[0]?.text ?? "";
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return { question, answer: raw };
+  }
+}
+function renderAnswer(answer) {
+  process.stdout.write(`
+${pc6.cyan("\u256D\u2500 doc2mcp")}
+`);
+  for (const line of answer.answer.trim().split("\n")) {
+    process.stdout.write(`${pc6.cyan("\u2502")} ${line}
+`);
+  }
+  if (answer.sources && answer.sources.length > 0) {
+    process.stdout.write(`${pc6.cyan("\u2502")}
+${pc6.cyan("\u2502")} ${pc6.dim("Sources:")}
+`);
+    for (const source of answer.sources.slice(0, 6)) {
+      process.stdout.write(
+        `${pc6.cyan("\u2502")} ${pc6.dim("\u2022")} ${source.title} ${pc6.dim(source.url)}
+`
+      );
+    }
+  }
+  process.stdout.write(`${pc6.cyan("\u2570")}
+
+`);
+}
+async function answerOnce(mcp, question) {
+  const spinner = ora2("Thinking\u2026").start();
+  try {
+    const answer = await askDocs(mcp, question);
+    spinner.stop();
+    renderAnswer(answer);
+  } catch (error) {
+    spinner.fail("Failed to get an answer");
+    printError(error);
+  }
+}
+async function runChat(target, options = {}) {
+  try {
+    await ensureLoggedIn();
+    const detail = await resolveProject(target);
+    if (!detail) {
+      return;
+    }
+    if (!detail.mcp) {
+      process.stderr.write(
+        `${pc6.red("That project is not ready yet.")} Check: ${pc6.bold("doc2mcp list")}
 `
       );
-      process.stdout.write(`  ${pc6.dim(project.id)} ${project.sourceUrl ?? ""}
+      process.exitCode = 1;
+      return;
+    }
+    const { mcp } = detail;
+    if (options.message) {
+      await answerOnce(mcp, options.message);
+      return;
+    }
+    process.stdout.write(
+      `
+${pc6.cyan("\u256D\u2500")} ${pc6.bold(`Chatting with ${detail.project.name}`)}
+`
+    );
+    process.stdout.write(
+      `${pc6.cyan("\u2502")} ${pc6.dim("Ask anything about these docs. Type /exit to leave.")}
+`
+    );
+    process.stdout.write(`${pc6.cyan("\u2570")}
+
 `);
+    let active = true;
+    while (active) {
+      const question = await readLine(`${pc6.bold(">")} `);
+      if (question === null) {
+        active = false;
+        break;
+      }
+      const trimmed = question.trim();
+      if (!trimmed) {
+        continue;
+      }
+      if (trimmed === "/exit" || trimmed === "/quit") {
+        active = false;
+        break;
+      }
+      await answerOnce(mcp, trimmed);
     }
+    process.stdout.write(`${pc6.dim("Bye \u2014 your docs MCP stays live for your editor.")}
+`);
   } catch (error) {
     printError(error);
     process.exitCode = 1;
@@ -685,7 +760,7 @@ async function runList() {
 
 // src/index.ts
 var program = new Command();
-program.name("doc2mcp").description("Generate documentation MCP servers from your terminal").version("0.1.17", "-v, --version", "Print the installed CLI version");
+program.name("doc2mcp").description("Generate documentation MCP servers from your terminal").version("0.1.18", "-v, --version", "Print the installed CLI version");
 program.command("login").description("Authorize the CLI via browser").action(async () => {
   await runLogin();
 });
@@ -701,8 +776,8 @@ program.command("list").description("List your MCP projects").action(async () =>
 program.command("install <projectId>").description("Install an existing MCP into Cursor, VS Code, Claude, or Windsurf").action(async (projectId) => {
   await runInstallCommand(projectId);
 });
-program.command("chat [projectId]").description("Chat with your docs in the terminal (AI answers from your MCP)").option("-m, --message <text>", "Ask a single question and exit").action(async (projectId, options) => {
-  await runChat(projectId, options);
+program.command("chat [target]").description("Chat with docs in the terminal; target can be a project id or docs URL").option("-m, --message <text>", "Ask a single question and exit").action(async (target, options) => {
+  await runChat(target, options);
 });
 program.argument("[url]", "Documentation URL to convert").action(async (url) => {
   if (!url) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doc2mcp",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Turn any documentation site into a hosted MCP server from your terminal — for Cursor, Claude, VS Code, Windsurf, and OpenAI agents.",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
   "files": [
     "assets",
     "dist",
+    "scripts",
     "README.md"
   ],
   "engines": {
@@ -26,6 +27,7 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
+    "postinstall": "node ./scripts/postinstall.js",
     "prepublishOnly": "pnpm build"
   },
   "keywords": [

package/scripts/postinstall.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+
+function isGlobalInstall() {
+  return (
+    process.env.npm_config_global === "true" ||
+    process.env.npm_config_location === "global"
+  );
+}
+
+function npmGlobalBin() {
+  try {
+    const prefix = execFileSync("npm", ["prefix", "-g"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    return path.join(prefix, "bin");
+  } catch {
+    return "";
+  }
+}
+
+if (isGlobalInstall()) {
+  const binDir = npmGlobalBin();
+  const pathEntries = (process.env.PATH || "").split(path.delimiter);
+  if (binDir && !pathEntries.includes(binDir)) {
+    process.stdout.write(`
+doc2mcp installed, but npm's global bin is not on your PATH.
+
+Run this once for zsh:
+  echo 'export PATH="${binDir}:$PATH"' >> ~/.zshrc
+  source ~/.zshrc
+
+Then try:
+  doc2mcp login
+
+Quick alternative (no PATH setup):
+  npx doc2mcp login
+
+For pnpm global installs, run:
+  pnpm setup
+  source ~/.zshrc
+
+`);
+  }
+}