@niroai/niro 0.9.0 → 0.10.1

package/src/commands/release.js

@@ -141,11 +141,11 @@ async function release(pathArg, opts = {}) {
     } catch { /* can't inspect — don't block on it */ }
   }
   if (stillDiverged.length) {
-    console.log(warn(`\n  ⚠ This temporary project still covers in-flight work:`));
+    console.log(warn(`\n    ⚠ This temporary project still covers in-flight work:`));
     for (const d of stillDiverged) {
       console.log(warn(`    ${d.folder} is on \`${d.branch}\` (source: \`${d.sourceBranch}\`)`));
     }
-    console.log(warn("  Discarding deletes the WHOLE temporary project — those repos lose their coverage" +
+    console.log(warn("    Discarding deletes the WHOLE temporary project — those repos lose their coverage" +
         " until you run `niro new-temp-project` there again (local code is untouched)."));
     if (!opts.yes) {
       if (!process.stdout.isTTY || prompt.isNonInteractive()) {
@@ -233,25 +233,25 @@ async function release(pathArg, opts = {}) {
   }
 
   if (alreadyGone) {
-    console.log(`\n  ${ok("✓")} Temporary project ${color.bold(tempProjectId)} was already gone from the server` +
+    console.log(`\n    ${ok("✓")} Temporary project ${color.bold(tempProjectId)} was already gone from the server` +
         color.dim(" (deleted from the UI, or reaped after sitting idle)."));
     console.log(repinned.length
       ? `  ${ok("✓")} Cleaned up ${repinned.length} local registration(s) that still pointed at it. ` +
         "Niro routes back to the original project automatically."
       : `  ${ok("✓")} Nothing left to clean up locally.`);
   } else {
-    console.log(`\n  ${ok("✓")} Temporary project discarded. Niro routes back to the original project automatically.`);
+    console.log(`\n    ${ok("✓")} Temporary project discarded. Niro routes back to the original project automatically.`);
   }
   if (healed.length) {
-    console.log(color.dim("  Healed old-style pins:"));
+    console.log(color.dim("    Healed old-style pins:"));
     for (const h of healed) console.log(color.dim(`    ${h.folder} → ${h.to}`));
   }
   if (failed.length) {
-    console.log(warn(`\n  ⚠ ${failed.length} folder(s) could not be restored locally (the temporary project` +
+    console.log(warn(`\n    ⚠ ${failed.length} folder(s) could not be restored locally (the temporary project` +
         " is already gone server-side):"));
     for (const f of failed) console.log(color.dim(`    ${f.folder} — ${f.error}`));
   }
-  console.log(color.dim("  The original project picks up your merged commits via its normal remote polling."));
+  console.log(color.dim("    The original project picks up your merged commits via its normal remote polling."));
 }
 
 module.exports = { release };

package/src/commands/remove.js

@@ -71,9 +71,9 @@ async function remove(opts = {}) {
     const expected = alias ? `"${alias}" or ${projectId}` : projectId;
     console.error(`${color.red("✗")} Refusing to delete: --confirm-name must equal the project's name (${expected}).`);
     if (confirm == null) {
-      console.error(color.dim("   Pass --confirm-name <name> to confirm this destructive delete."));
+      console.error(color.dim("    Pass --confirm-name <name> to confirm this destructive delete."));
     } else {
-      console.error(color.dim(`   You passed --confirm-name "${confirm}", which does not match.`));
+      console.error(color.dim(`    You passed --confirm-name "${confirm}", which does not match.`));
     }
     process.exitCode = 1;
     return;
@@ -86,9 +86,9 @@ async function remove(opts = {}) {
 
 function printUsage() {
   console.error("niro remove — remove a project or a repo mapping. Exactly one mode required:");
-  console.error("  --project                  delete the whole project (DESTRUCTIVE)");
-  console.error("                             requires --confirm-name <project alias or id>");
-  console.error("  --unmap-repo <gitId>       remove one repo from the project (non-destructive)");
+  console.error("    --project                  delete the whole project (DESTRUCTIVE)");
+  console.error("                                requires --confirm-name <project alias or id>");
+  console.error("    --unmap-repo <gitId>       remove one repo from the project (non-destructive)");
   console.error("Target project: --target <alias|id>, or a .niro-project pin in this folder.");
 }
 

package/src/commands/start.js

@@ -0,0 +1,567 @@
+/**
+ * `niro start` — the one command a new user runs.
+ *
+ * A thin ORCHESTRATOR over the commands that already exist. It deliberately owns no
+ * onboarding logic of its own: a second implementation of project creation or env
+ * scanning would drift from init.js within a release. Every step below either calls an
+ * existing command module or asks a question.
+ *
+ *   0. Beta gate      — access code, asked BEFORE anything is installed or contacted.
+ *   1. Bootstrap      — install globally and re-exec when running from the npx cache.
+ *   2. Sign in        — login.js (device flow), skipped when credentials exist.
+ *   3. Choose folder  — show what was detected, confirm, re-ask on a refusal.
+ *   4. Onboard        — init.js, unchanged.
+ *   5. Connect        — mcp.js install(), skipped when this machine already did it.
+ *
+ * Why step 0 precedes step 1: the beta needs an access code and a work email, so
+ * someone without a code cannot get an account. Asking first costs one prompt and
+ * saves them installing software they cannot use. Nothing touches their machine
+ * before they answer.
+ *
+ * Why step 1 exists at all: service.js registers the watch daemon with PM2 using
+ * `process.argv[1]`. Under npx that path lives in ~/.npm/_npx/<hash>/, which npm
+ * garbage-collects on its own schedule, so a watcher registered from an npx run would
+ * look healthy and then stop syncing days later with no error anywhere. npx is the
+ * bootstrapper, not the way to run Niro.
+ */
+const path = require("path");
+const fs = require("fs");
+// Required as a namespace, not destructured, so tests can substitute spawnSync
+// without shelling out to npm or re-execing a real binary.
+const childProcess = require("child_process");
+
+const color = require("../lib/color");
+const prompt = require("../lib/prompt");
+const credentials = require("../lib/credentials");
+const config = require("../lib/config");
+const git = require("../lib/git");
+const onboardTarget = require("../lib/onboardTarget");
+
+const step = (n) => color.bold(color.cyan(n));
+const ok = (s) => color.green(s);
+const warn = (s) => color.yellow(s);
+const fail = (s) => color.red(s);
+
+const TOTAL_STEPS = 5;
+const PACKAGE_NAME = "@niroai/niro";
+
+/** Offered in the welcome screen and again at the end. Not shown to returning users. */
+const BOOK_A_CALL = "https://tidycal.com/nirajaswani/45-minutes-meeting-mpy606v";
+
+/**
+ * Private-beta copy. There is no endpoint that reports whether the gate is on, and
+ * adding one to serve a first prompt is not worth the round-trip, so this is a local
+ * constant. DELETE THIS BLOCK (and betaGate below) when the beta ends — see
+ * docs/usecases/first-run-wizard.md.
+ */
+const BETA = {
+  on: true,
+  // The marketing site, NOT the app: niro.ai, not the niroai.dev hosts everything else in
+  // this CLI talks to. Confirmed by the user 2026-08-27 — it cannot be derived from anything
+  // in this repo, so it must not be guessed at from the backend hostnames.
+  requestUrl: "https://www.niro.ai",
+  requestAction: '"Request Access"',   // the button on that home page
+};
+
+/** Set on the re-exec so the installed copy can never bootstrap a second time. */
+const BOOTSTRAP_ENV = "NIRO_START_BOOTSTRAPPED";
+
+async function start(pathArg, opts = {}) {
+  if (prompt.isNonInteractive()) {
+    console.error(fail("`niro start` is interactive and there is no terminal to prompt on."));
+    console.error("    For scripts and agents use the individual commands, which take flags:");
+    console.error(`        ${color.cyan("niro login --api-key")}`);
+    console.error(`        ${color.cyan("niro init --defaults")}`);
+    console.error(`        ${color.cyan("niro mcp install --client <id>")}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // One decision, read once and used everywhere the wizard treats a newcomer differently:
+  // the banner, the welcome screen, the what-is-installed note, the beta gate and the
+  // booking offer. Separate checks would eventually disagree with each other.
+  const firstRun = !hasCredentials();
+
+  // True in the process step 1 handed over to. That process has no credentials yet, so it
+  // looks like a first run and would replay the welcome screen and ask for the access code a
+  // SECOND time. The parent already showed both and already got an answer; repeating them
+  // makes the install look like a restart. Observed live: the whole opening printed twice.
+  const handedOver = !!process.env[BOOTSTRAP_ENV];
+
+  console.log(`\n    ${color.bold("Niro")}  ${color.dim("·")}  ${firstRun ? "first-time setup" : "set up another repo"}\n`);
+
+  if (firstRun && !handedOver) printWelcome();
+
+  // 0. Beta gate. Skipped for anyone already holding credentials: they plainly have an
+  //    account, and asking again would be theatre. Also skipped after a hand-over, where it
+  //    was answered a moment ago in the parent.
+  if (!handedOver && !(await betaGate())) return;
+
+  // 1. Bootstrap. Returns true when it re-execed, meaning this process is done.
+  if (await bootstrapIfNpx(pathArg, firstRun)) return;
+
+  // 2. Sign in.
+  if (!(await ensureSignedIn())) return;
+
+  // 3. Choose the folder.
+  const target = await chooseFolder(pathArg);
+  if (!target) return;
+
+  // 4. Onboard. init re-validates the folder itself; it stays the authority.
+  console.log(`\n    ${step(`4/${TOTAL_STEPS}`)}  Onboarding and building the index\n`);
+  const initCmd = require("./init");
+  // Everything init prints belongs under this step, including what its own helpers print.
+  const { withIndent } = require("../lib/nestedOutput");
+  await withIndent(4, () => initCmd.init(target, { nested: true }));
+  if (process.exitCode) return; // init already explained why
+
+  // 5. Connect an assistant.
+  await connectAssistant();
+
+  if (firstRun) await offerMeasurement();
+
+  printNextSteps(firstRun);
+}
+
+/**
+ * The opening screen: what this thing is for, before asking anyone to install it.
+ *
+ * Four lines, not a tour. Someone who has just typed an unfamiliar command deserves to know
+ * what they are about to spend five minutes on, and someone evaluating deserves to know a
+ * person is available before they invest that time — which is why the call is offered here
+ * and not only at the end.
+ */
+function printWelcome() {
+  console.log("    Niro maps how your code actually fits together, so your AI");
+  console.log("    assistant answers from that map instead of guessing.\n");
+  // "in", not "with": the point is that there is no new tool and no new window, you ask
+  // inside the thing already open. "it" is dropped because it read ambiguously against
+  // "the assistant" — and without it the line fits on one.
+  console.log(`        ${color.cyan("·")}  Ask anything about your code, in the assistant you already use`);
+  console.log(`        ${color.cyan("·")}  See what breaks before you change it, across services`);
+  console.log(`        ${color.cyan("·")}  Get a standing review of the issues already in your code`);
+  console.log(`        ${color.cyan("·")}  Find bugs' root causes from your alerts`);
+  console.log(`        ${color.cyan("·")}  Measure it: run half your sessions without Niro and compare\n`);
+  console.log("    Setting up takes about five minutes.");
+  console.log("    Prefer a walkthrough first? 45 minutes with us:");
+  console.log(`        ${color.cyan(BOOK_A_CALL)}\n`);
+}
+
+/**
+ * Offer the A/B measurement window, once, at the end.
+ *
+ * Not in the opening, even though the capability is claimed there: enabling needs a signed-in
+ * account, and asking someone to measure a thing they have not yet seen work is the wrong
+ * order. First run only, and it defaults to NO — this is a measurement option, not something
+ * to be nudged into. A returning user finds it in the next-steps list instead.
+ *
+ * Never fails the wizard. The repo IS indexed by this point; a measurement window is a nicety
+ * and a network hiccup here must not read as a broken setup.
+ */
+async function offerMeasurement() {
+  const abCmd = require("./ab");
+  console.log("\n    One more thing, entirely optional.\n");
+  console.log(`        Niro can run ${color.bold("off")} for half your sessions for the next`);
+  console.log(`        ${abCmd.DEFAULT_WINDOW_DAYS} days, so you can see the difference rather than take`);
+  console.log("        our word for it. It applies to your whole account, and");
+  console.log(`        ${color.cyan("niro ab disable")} stops it at any time.\n`);
+
+  if (!(await prompt.confirm("    Turn on A/B measurement?", false))) {
+    console.log(`\n    Left off. Turn it on later with ${color.cyan("niro ab enable")}.`);
+    return;
+  }
+  try {
+    await abCmd.enable({ yes: true });
+  } catch (err) {
+    console.log(`\n        ${warn("⚠")} Could not start the measurement window.`);
+    console.log(`            Your repo is indexed and working. Try ${color.cyan("niro ab enable")} later.`);
+    console.log(`            (${err && err.message ? err.message : err})`);
+  }
+}
+
+/**
+ * What to do now that a repo is indexed.
+ *
+ * Ordered by when they will need it, not by how impressive it is: one question they can paste
+ * straight away, then the three things they will reach for over the next few days. The web app
+ * line is where code review and the graph views get named, because those are things you look
+ * at rather than ask for.
+ *
+ * The web address is whatever the server told us at login, never a constant: a self-hosted
+ * install has its own, and a wrong link here is worse than none. Omitted when unknown, which
+ * is the case for anyone who logged in before the CLI started recording it.
+ */
+function printNextSteps(firstRun) {
+  const appUrl = config.load().appUrl;
+
+  console.log(`\n    ${ok("✓ You are set up.")}`);
+  console.log("\n    Ask this in the assistant you just connected, from this folder:\n");
+  console.log(`        ${color.bold('"What are the entry points into this repo, and what does each one do?"')}`);
+
+  console.log("\n    When you need them:\n");
+  if (appUrl) {
+    console.log(`        ${color.cyan(appUrl)}`);
+    console.log("            the graph, impact views and your code review, in the browser");
+  }
+  console.log(`        ${color.cyan("niro start")}  in another repo`);
+  console.log("            cross-service answers need more than one repo indexed");
+  console.log(`        ${color.cyan("niro new-temp-project")}`);
+  console.log("            run it once on a branch Niro has not indexed, so answers match your work");
+  console.log(`        ${color.cyan("niro status")}`);
+  console.log("            check the index is current");
+  console.log(`        ${color.cyan("niro ab")}`);
+  console.log("            measure what Niro changes, by running it off half the time");
+
+  if (firstRun) {
+    console.log(`\n    Questions, or want us to walk through your codebase with you?`);
+    console.log(`    45 minutes with us: ${color.cyan(BOOK_A_CALL)}`);
+  }
+  console.log("");
+}
+
+/**
+ * What one `npm install` actually puts on the machine.
+ *
+ * Printed at the install step, because that is the moment software lands and the honest time
+ * to say what it is. Three things arrive from one package and nothing else in the flow says
+ * so: the CLI is visible (they just typed it), but the MCP server and the skills are not, and
+ * a developer who does not know the skills exist will never think to ask for a rebuild in
+ * plain English.
+ *
+ * First run only, like the welcome screen. Someone setting up their fifth repo knows.
+ */
+function printWhatIsInstalled() {
+  console.log("        One package, three parts:\n");
+  console.log(`            ${color.bold("niro")}         the command you are running now: onboard a repo,`);
+  console.log("                         check status, rebuild, manage projects");
+  console.log(`            ${color.bold("MCP server")}   how your AI assistant reaches Niro's map of your`);
+  console.log("                         code, so it answers from that instead of guessing");
+  console.log(`            ${color.bold("two skills")}   so you can say \"index this repo\" or \"what breaks`);
+  console.log("                         if I change this\" instead of remembering commands");
+  console.log("");
+}
+
+/**
+ * Step 0. Returns false when the user has no access code, having changed nothing.
+ *
+ * Deliberately NOT a server capability probe: see BETA above.
+ */
+async function betaGate() {
+  if (!BETA.on) return true;
+  if (hasCredentials()) return true; // already has an account on this machine
+
+  console.log("    Niro is in private beta. To create an account you need:");
+  console.log("        · an access code (the browser signup form asks for it by that name)");
+  console.log("        · a work email address (personal addresses are not accepted yet)\n");
+  console.log(`    No access code? Click ${BETA.requestAction} at ${color.cyan(BETA.requestUrl)}\n`);
+
+  const hasCode = await prompt.confirm("    Do you have an access code?", true);
+  if (hasCode) return true;
+
+  console.log(`\n    No problem. Open ${color.cyan(BETA.requestUrl)} and click ${BETA.requestAction},`);
+  console.log("    then run this again when your code arrives:\n");
+  console.log(`        ${color.cyan(`npx ${PACKAGE_NAME} start`)}\n`);
+  console.log("    Nothing was installed or changed on this machine.\n");
+  return false;
+}
+
+/**
+ * The same condition credentials.requireCreds() enforces, and deliberately not a second
+ * definition of it: any usable credential counts, because the request layer refreshes an
+ * expired JWT from the durable cliToken on its own.
+ */
+function hasCredentials() {
+  const c = credentials.load();
+  return !!(c && (c.token || c.cliToken || c.niroApiKey));
+}
+
+/** True when this process is running out of npm's throwaway npx cache. */
+function runningFromNpxCache(argv1 = process.argv[1]) {
+  return /[\\/]_npx[\\/]/.test(argv1 || "");
+}
+
+/**
+ * The absolute path of a PERMANENTLY installed `niro`, or null.
+ *
+ * Deliberately not "is niro on PATH". Under npx, PATH begins with npx's own throwaway cache,
+ * so a PATH probe finds THIS process's binary and concludes a global install already exists:
+ * the install is skipped, and the hand-over re-execs the same temporary copy. Which is the
+ * whole bug step 1 exists to prevent, plus a wizard that restarts from its first screen.
+ * Observed for real: `command -v niro` inside npx returns
+ * ~/.npm/_npx/<hash>/node_modules/.bin/niro.
+ *
+ * npm's own global prefix is the only answer that cannot be the cache.
+ */
+function globalNiroPath() {
+  const r = childProcess.spawnSync("npm", ["prefix", "-g"], { shell: true, encoding: "utf8" });
+  if (r.status !== 0) return null;
+  const prefix = String(r.stdout || "").trim();
+  if (!prefix) return null;
+  const bin = process.platform === "win32"
+    ? path.join(prefix, "niro.cmd")
+    : path.join(prefix, "bin", "niro");
+  return fs.existsSync(bin) ? bin : null;
+}
+
+/** True when the installed copy at `bin` is at least as new as this one. */
+function isCurrent(bin) {
+  const r = childProcess.spawnSync(bin, ["--version"], { encoding: "utf8" });
+  if (r.status !== 0) return false;
+  return !isOlder(String(r.stdout || "").trim(), require("../../package.json").version);
+}
+
+/** True when semver string `a` is strictly older than `b`. Unparseable counts as older. */
+function isOlder(a, b) {
+  const parts = (v) => {
+    const m = /(\d+)\.(\d+)\.(\d+)/.exec(v || "");
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+  };
+  const x = parts(a);
+  const y = parts(b);
+  if (!x || !y) return true;
+  for (let i = 0; i < 3; i++) {
+    if (x[i] !== y[i]) return x[i] < y[i];
+  }
+  return false;
+}
+
+/**
+ * Step 1. Install globally and hand over, when and only when this copy came from npx.
+ *
+ * Returns true if it re-execed (the caller must stop). The global install is NOT
+ * prompted for: the alternative is a question whose wrong answer produces a silently
+ * dead watch daemon days later.
+ */
+async function bootstrapIfNpx(pathArg, firstRun = false) {
+  const handedOver = !!process.env[BOOTSTRAP_ENV];
+  if (handedOver || !runningFromNpxCache()) {
+    // Nothing to do: either this IS the handed-over child, or niro was installed
+    // properly in the first place. Still announced, so the wizard shows all five steps
+    // and reads as a finite process rather than an open-ended one.
+    console.log(`    ${step(`1/${TOTAL_STEPS}`)}  ${ok("✓")} niro is installed.\n`);
+    if (firstRun && !handedOver) printWhatIsInstalled();
+    return false;
+  }
+
+  console.log(`    ${step(`1/${TOTAL_STEPS}`)}  Installing niro\n`);
+  if (firstRun) printWhatIsInstalled();
+  console.log("        Background sync has to outlive npx's temporary cache, so Niro");
+  console.log("        installs itself properly first.\n");
+
+  let bin = globalNiroPath();
+  if (bin && isCurrent(bin)) {
+    console.log(`        ${ok("✓")} Already installed at ${bin}.\n`);
+  } else {
+    const r = childProcess.spawnSync("npm", ["install", "-g", PACKAGE_NAME], { shell: true, stdio: "inherit" });
+    bin = r.status === 0 ? globalNiroPath() : null;
+    // Only claim success once the binary is actually THERE. The old wording announced an
+    // install that had been skipped, which is how an empty global folder came to look fine.
+    if (!bin) {
+      console.error(fail("\n    ✗ Global install failed."));
+      console.error(`        Install it yourself, then run ${color.cyan("niro start")}:`);
+      console.error(`        ${color.cyan(`npm install -g ${PACKAGE_NAME}`)}`);
+      process.exitCode = 1;
+      return true;
+    }
+    console.log(`        ${ok("✓")} ${PACKAGE_NAME} installed at ${bin}.\n`);
+  }
+
+  const args = ["start"];
+  if (pathArg) args.push(pathArg);
+  // The resolved absolute path, never the bare name: under npx the name resolves back to the
+  // cache we are trying to escape.
+  const handover = childProcess.spawnSync(bin, args, {
+    stdio: "inherit",
+    env: { ...process.env, [BOOTSTRAP_ENV]: "1" },
+  });
+  process.exitCode = handover.status === null ? 1 : handover.status;
+  return true;
+}
+
+/** Step 2. Returns false only when login failed. */
+async function ensureSignedIn() {
+  if (hasCredentials()) {
+    const creds = credentials.load();
+    console.log(`    ${step(`2/${TOTAL_STEPS}`)}  ${ok("✓")} Signed in${creds.email ? ` as ${color.bold(creds.email)}` : ""}.\n`);
+    return true;
+  }
+
+  console.log(`    ${step(`2/${TOTAL_STEPS}`)}  Sign in\n`);
+  console.log("        Opening your browser. Sign in there, or create your account");
+  console.log("        with your access code.\n");
+  console.log("        Creating an account? You will get a verification email. Take");
+  console.log("        your time. This keeps waiting.\n");
+
+  const loginCmd = require("./login");
+  await loginCmd.login({});
+  if (!hasCredentials()) {
+    console.error(fail("\n    ✗ Not signed in, so there is nothing to onboard to."));
+    console.error(`        Run ${color.cyan("niro start")} again when you are ready.`);
+    process.exitCode = 1;
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Step 3. Confirm what is about to be uploaded, and keep asking on a refusal.
+ *
+ * The refusal RULES are not re-implemented here: protectedRootReason and
+ * findProjectIndicators are the same functions init.js validates with, so the preview
+ * can never disagree with the gate. init.js re-runs the authoritative check.
+ *
+ * Returns the chosen absolute path, or null if the user gave up.
+ */
+async function chooseFolder(pathArg) {
+  let candidate = path.resolve(pathArg || process.cwd());
+
+  for (;;) {
+    console.log(`    ${step(`3/${TOTAL_STEPS}`)}  Choose what to index\n`);
+
+    const problem = describeProblem(candidate);
+    if (problem) {
+      console.log(`        ${fail("✗")} ${problem.headline}\n`);
+      for (const line of problem.detail) console.log(`            ${line}`);
+      console.log("");
+      const answer = await prompt.ask("        Which folder do you want to index? (blank to give up)");
+      if (!answer || !answer.trim()) {
+        console.log(`\n    Stopped. Nothing was changed. Run ${color.cyan("niro start")} from a project folder.\n`);
+        return null;
+      }
+      candidate = path.resolve(expandHome(answer.trim()));
+      console.log("");
+      continue;
+    }
+
+    printPreview(candidate);
+    if (await prompt.confirm("        Index this folder?", true)) return candidate;
+
+    const answer = await prompt.ask("        Which folder instead? (blank to give up)");
+    if (!answer || !answer.trim()) {
+      console.log(`\n    Stopped. Nothing was changed.\n`);
+      return null;
+    }
+    candidate = path.resolve(expandHome(answer.trim()));
+    console.log("");
+  }
+}
+
+/** A leading ~ is expanded here because a prompt answer never goes through a shell. */
+function expandHome(p) {
+  if (p === "~") return require("os").homedir();
+  if (p.startsWith("~/") || p.startsWith("~\\")) return path.join(require("os").homedir(), p.slice(2));
+  return p;
+}
+
+/**
+ * Why this folder cannot be onboarded, in the wizard's voice, or null if it can.
+ * Mirrors ensureOnboardable's two rules by calling the same functions it calls.
+ */
+function describeProblem(dir) {
+  if (!fs.existsSync(dir)) {
+    return { headline: `${dir} does not exist.`, detail: ["Check the path and try again."] };
+  }
+  if (!fs.statSync(dir).isDirectory()) {
+    return { headline: `${dir} is a file, not a folder.`, detail: [] };
+  }
+
+  const reason = onboardTarget.protectedRootReason(dir);
+  if (reason) {
+    return {
+      headline: `${dir} is ${reason}. Niro will not index it.`,
+      // Says only what is true. folderSync never descends into a dot directory
+      // (folderSync.js walkDir) and only uploads source, build and committed config files
+      // (isUploadableName), so keys, documents and photos are never eligible and claiming
+      // otherwise is scaremongering. What IS lost is .gitignore: it is only honoured when
+      // the onboarded folder is itself a git work tree, and a home folder is not one, so
+      // each nested repo's ignored files stop being protected.
+      detail: [
+        "It would upload source from every repository under it, and lose the",
+        ".gitignore protection each one has, because the folder you point at",
+        "has to be the git repository for that to apply.",
+      ],
+    };
+  }
+
+  const { indicators } = onboardTarget.findProjectIndicators(dir);
+  if (indicators.size === 0) {
+    return {
+      headline: `No project found in ${dir}.`,
+      detail: [
+        "Niro looks for a build file (package.json, pom.xml, go.mod, ...) in",
+        "this folder or just below it. None found.",
+        `If you really mean this folder, use ${color.cyan("niro init --force")} instead.`,
+      ],
+    };
+  }
+  return null;
+}
+
+/**
+ * The screen that prevents the accident: what is about to be uploaded, before it is.
+ *
+ * Deliberately cheap — no full tree walk. The project scan has already run for the
+ * refusal check and git.inspect reads two small files, so this adds nothing the wizard
+ * was not doing anyway. init.js does the real manifest walk a moment later.
+ */
+function printPreview(dir) {
+  const { roots, indicators } = onboardTarget.findProjectIndicators(dir);
+  const info = git.inspect(dir);
+
+  console.log(`        Folder:    ${color.bold(dir)}`);
+  console.log(`        Detected:  ${onboardTarget.describeIndicators(indicators)}`);
+  console.log(`        Projects:  ${roots} module${roots === 1 ? "" : "s"}`);
+  if (info.repoRoot) {
+    console.log(`        Git:       branch ${info.branch || "(detached)"}${info.originUrl ? `, ${info.originUrl}` : ""}`);
+  } else {
+    console.log(`        Git:       ${color.dim("not a git repo, which is fine; it uploads as-is")}`);
+  }
+  console.log("");
+}
+
+/**
+ * Step 5. `mcp install` prompts for the client itself and resolves the key from the
+ * login session, so there is nothing to pass it.
+ *
+ * "Already connected" is a wizard-local flag rather than a probe of 14 clients' config
+ * files: those paths live inside src/mcp/setup.js and are not exported, and a wrong
+ * guess here would silently skip the step that makes Niro usable. The flag only ever
+ * records what THIS wizard did, and re-running mcp install is harmless anyway.
+ */
+async function connectAssistant() {
+  const saved = config.load();
+  if (saved.mcpConnectedAt) {
+    console.log(`\n    ${step(`5/${TOTAL_STEPS}`)}  ${ok("✓")} Assistant already connected on this machine.`);
+    console.log(`        Connect another with ${color.cyan("niro mcp install")}.`);
+    return;
+  }
+
+  console.log(`\n    ${step(`5/${TOTAL_STEPS}`)}  Connect your AI assistant\n`);
+  const mcpCmd = require("./mcp");
+  try {
+    await mcpCmd.install();
+    config.save({ mcpConnectedAt: new Date().toISOString() });
+  } catch (err) {
+    // Never fail the whole wizard here: the repo IS indexed by this point, and the
+    // user can retry a single command.
+    console.log(`\n        ${warn("⚠")} Could not configure an assistant automatically.`);
+    console.log(`            Run ${color.cyan("niro mcp install")} when you are ready.`);
+    console.log(`            (${err && err.message ? err.message : err})`);
+  }
+}
+
+module.exports = {
+  start,
+  // exported for tests
+  hasCredentials,
+  printWelcome,
+  printWhatIsInstalled,
+  offerMeasurement,
+  printNextSteps,
+  BOOK_A_CALL,
+  runningFromNpxCache,
+  isOlder,
+  describeProblem,
+  expandHome,
+  BOOTSTRAP_ENV,
+};