@niroai/niro 0.16.0 → 0.18.0

package/src/commands/start.js

@@ -1,270 +1,503 @@
 /**
- * `niro start` — the one command a new user runs.
+ * `niro start` — the first run: one wizard, then a ready screen. The graph is built and kept
+ * on this machine (Niro Local). A cloud ("web") mode is planned for a later version.
  *
- * 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.
+ *   1/5  Checking this machine     OS and arch, free disk, Node, the folder. Windows stops
+ *                                  here, before any account exists.
+ *                                  The npx-to-global install happens here too, quietly.
+ *   2/5  Sign in                   login.js device flow. Waiting, blocked and a Teams request
+ *                                  end the wizard with login.js's own words and exit code.
+ *   3/5  Local engine              engine.ensure(); checksum only, never "signature". Then
+ *                                  the engine is asked whether its graph file opens.
+ *   4/5  Building your graph       niro-local init --progress (adds and builds), streamed into a bar.
+ *   5/5  Connect your AI assistant the existing `niro mcp install` wizard, full client list.
+ *        Niro is ready             graph, assistant, plan; the watch daemon keeps it current.
  *
- *   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.
+ * Each step checks its own completion and prints ✓ instead of redoing it, so a second run
+ * resumes at the first unfinished step and a run after full success changes nothing:
+ * credentials, the engine resolved, the folder indexed per `niro-local projects --json`, and
+ * `mcpConnectedAt`.
  *
- * 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.
+ * No cloud fallback (design §9.3, and Niraj's D2 of 2026-10-31): an engine that cannot open its
+ * graph says why in its own words and the wizard stops. Each step's timing and outcome go to
+ * ~/.niro/onboarding.json.
  *
- * Why step 1 exists at all: service.js registers the watch daemon with PM2 using
+ * Why the npx hand-over 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.
+ * garbage-collects on its own schedule, so a watcher registered from an npx run would look
+ * healthy and then stop days later with no error anywhere.
  */
 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 os = require("os");
+// Required as namespaces, not destructured, so tests can substitute each collaborator.
 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 machineCheck = require("../lib/machineCheck");
+const engine = require("../lib/engine");
+const graphCheck = require("../lib/graphCheck");
+const localOnboard = require("../lib/localOnboard");
+const languages = require("../lib/languages");
+const lease = require("../lib/lease");
+const progressBar = require("../lib/progressBar");
+const onboardingLog = require("../lib/onboardingLog");
+const watchDaemon = require("../lib/watchDaemon");
+const mcpClients = require("../lib/mcpClients");
+const planUsage = require("../lib/planUsage");
+const service = require("../lib/service");
+const watchState = require("../lib/watchState");
+const migrationNotice = require("../lib/migrationNotice");
+const release = require("../lib/release");
 
-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;
+/** The steps, in order; a step's number is its place here. */
+const order = ["machine", "sign-in", "engine", "build", "assistant"];
 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
-};
+const GB = 1024 ** 3;
 
 /** Set on the re-exec so the installed copy can never bootstrap a second time. */
 const BOOTSTRAP_ENV = "NIRO_START_BOOTSTRAPPED";
 
+/** Where the graph lives, said plainly on the ready screen: niro-local's one SQLite file. */
+
+// The setup rail: ┌ opens, │ carries, ◆ is the step under way, ◇ a finished one, └ closes.
+const rail = (s = "") => console.log(s ? `│  ${s}` : "│");
+const num = (name) => `${order.indexOf(name) + 1}/${order.length}`;
+// A step that already printed its ◆ heading closes without repeating the number.
+const opened = new Set();
+const active = (name, title) => { opened.add(name); console.log(`◆  ${num(name)}  ${title}`); };
+const done = (name, text) => console.log(opened.has(name) ? `◇  ${text}` : `◇  ${num(name)}  ${text}`);
+
+/** Time one step and leave a note of how it ended. `fn` returns its outcome, or throws. */
+async function timed(step, fn) {
+  const startedAt = new Date().toISOString();
+  let outcome = "error";
+  try {
+    outcome = await fn();
+    return outcome;
+  } finally {
+    onboardingLog.record({ step, startedAt, endedAt: new Date().toISOString(), outcome: String(outcome) });
+  }
+}
+
+/** Stop the wizard: every step returns a string outcome, and these are the ones that end it. */
+const GO = "ok";
+const STOPPED = new Set(["refused", "waiting", "blocked", "request_submitted", "failed", "handed_over"]);
+
 async function start(pathArg, opts = {}) {
+  opened.clear();
   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("    Run it once in a terminal: signing in opens your browser. After that, these take flags:");
+    console.error(`        ${color.cyan("niro engine install")}`);
+    console.error(`        ${color.cyan("niro init <folder>")}`);
     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();
+  const dir = path.resolve(pathArg || process.cwd());
 
-  // 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];
+  // The handed-over child repeats nothing the parent already printed.
+  if (!process.env[BOOTSTRAP_ENV]) printWelcome();
 
-  console.log(`\n    ${color.bold("Niro")}  ${color.dim("·")}  ${firstRun ? "first-time setup" : "set up another repo"}\n`);
+  const ctx = { dir, claims: null, built: null, worktree: null };
+  const run = {
+    machine: () => checkMachine(ctx, pathArg),
+    "sign-in": () => signIn(ctx),
+    engine: () => ensureEngine(),
+    build: () => buildGraph(ctx),
+    assistant: () => connectAssistant(ctx),
+  };
+  for (const step of order) {
+    const outcome = await timed(step, run[step]);
+    if (STOPPED.has(outcome)) return;
+  }
+  await moveWebFolders(ctx);
+  await keepItCurrent(ctx);
+  await printReady(ctx);
+}
 
-  if (firstRun && !handedOver) printWelcome();
+/** Close the rail the way it opened: the outcome on └, then what Niro does, off the rail. */
+const LINKS = {
+  app: "https://console.niroai.dev/",
+  docs: "https://help.niroai.dev/cli/",
+  discord: "https://discord.gg/gcbzePZHn",
+};
 
-  // 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;
+function closeReady(who = "your assistant", restart = false) {
+  rail();
+  console.log(`└  ${color.bold(ok("Niro is ready"))}`);
+  // Right under "Niro is ready": what to do next, when an assistant was just connected.
+  if (restart) console.log(color.bold(`Restart ${who} to start using Niro.`));
+  console.log("");
+  console.log(`Carry on using ${who} as usual, and ask it about your code. When it needs`);
+  console.log(`facts, it calls Niro, and you will see lines such as ${color.cyan("niro · get_reverse_call_chain")}.`);
+  console.log(`\n${color.bold(color.cyan("Useful commands"))}`);
+  for (const [cmd, what] of USEFUL) console.log(`  ${color.cyan(cmd.padEnd(18))}${what}`);
+  const link = (label, url) => `${color.dim(label)}  ${color.cyan(url)}`;
+  console.log(`\n${[link("App", LINKS.app), link("Docs", LINKS.docs), link("Discord", LINKS.discord)].join("   ")}`);
+  console.log("");
+}
 
-  // 1. Bootstrap. Returns true when it re-execed, meaning this process is done.
-  if (await bootstrapIfNpx(pathArg, firstRun)) return;
+function printWelcome() {
+  console.log("");
+  console.log(`┌  Niro setup  ${color.dim(`v${require("../../package.json").version}`)}`);
+  rail();
+  rail(color.bold("Give your AI assistant verified facts about your code: call chains, impact, cross-repo links."));
+  rail(color.dim("Built on this machine · 5 steps · about 5 minutes"));
+  rail();
+}
 
-  // 2. Sign in.
-  if (!(await ensureSignedIn())) return;
+/** Step 1. Nothing here contacts Niro or changes the machine, bar the npx hand-over. */
+async function checkMachine(ctx, pathArg) {
+  active("machine", "Checking this machine");
+  const m = machineCheck.check();
+  if (m.platformProblem) {
+    rail(`${fail("✗")} ${m.os}, ${m.arch}`);
+    rail(m.platformProblem);
+    rail("Niro Local runs on macOS and Linux. On Windows, use WSL 2.");
+    console.log("└");
+    process.exitCode = 1;
+    return "refused";
+  }
+  rail(`${ok("✓")} ${m.os}, ${m.arch}`);
+  if (m.freeBytes !== null) {
+    const free = `${(m.freeBytes / GB).toFixed(1)} GB free`;
+    rail(m.lowDisk ? `${warn("⚠")} ${free}. A large repository's graph may need more.` : `${ok("✓")} ${free}`);
+  }
+  if (!m.nodeOk) {
+    rail(`${fail("✗")} Node ${m.node}. Niro needs Node 18 or newer.`);
+    console.log("└");
+    process.exitCode = 1;
+    return "refused";
+  }
 
-  // 3. Choose the folder.
-  const target = await chooseFolder(pathArg);
-  if (!target) return;
+  const problem = describeProblem(ctx.dir);
+  if (problem) {
+    rail(`${fail("✗")} ${problem.headline}`);
+    for (const line of problem.detail) rail(line);
+    console.log("└");
+    process.exitCode = 1;
+    return "refused";
+  }
+  rail();
+  return (await bootstrapIfNpx(pathArg)) ? "handed_over" : GO;
+}
 
-  // 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
+/** Step 2. login.js prints its own outcome; this only decides whether to go on. */
+async function signIn(ctx) {
+  if (!hasCredentials()) {
+    active("sign-in", "Sign in");
+    rail("Sign in, choose a plan and approve this terminal in one screen.");
+    const { withPrefix } = require("../lib/nestedOutput");
+    const result = await withPrefix("│", () => require("./login").login({}));
+    if (result && result.waiting) return "waiting";
+    if (result && result.blocked) return "blocked";
+    if (result && result.requestSubmitted) return "request_submitted";
+    if (!hasCredentials()) {
+      console.error(fail("\n✗ Not signed in, so there is nothing to set up yet."));
+      console.error(`  Run ${color.cyan("niro start")} again when you are ready.`);
+      process.exitCode = 1;
+      return "failed";
+    }
+  }
+  const email = credentials.load().email;
+  ctx.claims = await lease.currentClaims().catch(() => null);
+  const plan = ctx.claims && ctx.claims.plan_name ? ` · ${ctx.claims.plan_name}` : "";
+  done("sign-in", `${ok("✓")} Signed in${email ? ` as ${email}` : ""}${plan}`);
+  return GO;
+}
 
-  // 5. Connect an assistant.
-  await connectAssistant();
+/** Step 3. */
+async function ensureEngine() {
+  const found = engine.resolve();
+  if (found) {
+    if (!(await graphOpens())) return "failed";
+    done("engine", ok(`✓ Engine ready${engineVersion(found.path)}`));
+    return GO;
+  }
+  active("engine", "Local engine");
+  let where;
+  try {
+    // engine.ensure says "Downloading the local engine <version> for <label>..." itself.
+    where = await engine.ensure({ log: (line) => rail(line) });
+  } catch (err) {
+    rail(`${fail("✗")} ${err && err.message ? err.message : err}`);
+    if (!err || err.code !== "EENGINEREFUSED") rail(`Try again with ${color.cyan("niro start")}.`);
+    console.log("└");
+    process.exitCode = 1;
+    return "failed";
+  }
+  if (!(await graphOpens())) return "failed";
+  rail(ok(`✓ Engine ready${engineVersion(where)}`));
+  rail();
+  return GO;
+}
 
-  if (firstRun) await offerMeasurement();
+/** Can the engine open its graph file? If not, its own words, and the wizard stops. */
+async function graphOpens() {
+  const usable = await graphCheck.graphDatabaseUsable();
+  if (usable.ok) return true;
+  rail(`${fail("✗")} ${usable.problem}`);
+  console.log("└");
+  process.exitCode = 1;
+  return false;
+}
 
-  printNextSteps(firstRun);
+/** Step 4. */
+async function buildGraph(ctx) {
+  const known = await localOnboard.worktreeFor(ctx.dir);
+  ctx.worktree = known;
+  if (known && known.worktree.indexed) {
+    const when = known.worktree.last_build_at ? `, ${ago(known.worktree.last_build_at)}` : "";
+    done("build", ok(`✓ Graph built for ${known.project.name}${when}`));
+    return GO;
+  }
+  active("build", "Building your graph");
+  rail(`Project  ${known ? known.project.name : path.basename(ctx.dir)}`);
+  // At or over the limit the engine refuses a folder that adds new lines, so the same question is
+  // asked of the engine here first (`refusesBuild`) and such a folder goes to the upgrade page, not to
+  // an error. A folder the engine already counts (a temporary copy, a service inside an indexed root)
+  // builds.
+  const before = await planUsage.linesUsed();
+  if (await planUsage.refusesBuild(ctx.claims, before, ctx.dir)) return overLimit(ctx, before);
+  const bar = progressBar.create({ prefix: "│  " });
+  const onProgress = (d, n) => bar.update(d, n);
+  try {
+    // A folder not added yet: the engine's `init` adds it and builds it, in one command, so it is built once. A
+    // folder added but not built yet (a step 4 that stopped part way): its build.
+    ctx.built = known ? await localOnboard.build(ctx.dir, onProgress) : await localOnboard.initAndBuild(ctx.dir, onProgress);
+  } catch (err) {
+    bar.stop();
+    const words = (err && (err.stderr || err.message)) || String(err);
+    if (/^Nothing that looks like a project in /m.test(words)) {
+      // The engine's refusal names niro-local and its own command; say it in niro start's words.
+      rail(`${fail("✗")} No project found here`);
+      rail(`  Niro looks for a build file (package.json, pom.xml, go.mod, …) in this folder or up to 3 folders down.`);
+      rail(`  Run ${color.cyan("niro start")} in your project's folder, or index this one anyway:  ${color.cyan("niro init --force")}`);
+      rail(`  ${color.dim(`Languages supported: ${languages.supportedList()}.`)}`);
+    } else {
+      for (const line of words.split("\n")) rail(`${line.replace(/^error:\s*/, "")}`);
+      rail(`${fail("✗")} The graph was not built. Fix the above and run ${color.cyan("niro start")} again.`);
+    }
+    console.log("└");
+    process.exitCode = 1;
+    return "failed";
+  }
+  bar.stop();
+  done("build", ok(`✓ Graph built: ${counts(ctx.built)} in ${ctx.built.seconds} s`));
+  if (!foundLanguages(ctx).length) {
+    rail(`${warn("⚠")} No code in a supported language here. Niro reads ${languages.supportedList()}.`);
+  }
+  const used = await planUsage.linesUsed();
+  ctx.plan = planUsage.describe(ctx.claims, used);
+  ctx.noRoom = planUsage.noRoomNote(ctx.claims, used);
+  // The plan is shown once, in the Setup complete summary (2026-11-11), not under the build line.
+  if (ctx.noRoom) {
+    rail(color.yellow(ctx.noRoom));
+    rail(`Run ${color.cyan("niro plan")} to unlock unlimited lines or start a Pro free trial, or free lines with ${color.cyan("niro remove --path <folder>")}.`);
+  }
+  rail();
+  return GO;
 }
 
-/**
- * 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`);
+/** No room under the line limit: say so in two lines and open the console's choice page. */
+function overLimit(ctx, used) {
+  const max = ctx.claims.max_lines;
+  const n = (x) => x.toLocaleString("en-US");
+  done("build", `${fail("✗")} Not built: this machine already holds ${n(used)} lines of code, over the ${n(max)} line limit`);
+  const url = planUsage.limitUrl(used, max);
+  rail(`Choose how to continue: unlock unlimited lines, a Pro free trial, or stay under the limit.`);
+  rail(`Opening ${color.cyan(url)}`);
+  require("../lib/browser").open(url);
+  rail(`Then run ${color.cyan("niro start")} again. ${color.dim(`Or see the options here: niro plan`)}`);
+  rail(`To free lines instead, stop indexing a folder: ${color.cyan("niro remove --path <folder>")}`);
+  console.log("└");
+  process.exitCode = 1;
+  return "failed";
 }
 
 /**
- * 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.
+ * Step 5. The `niro mcp install` wizard, which keeps the full client list. `[]` so the
+ * wizard's own argv (`start <path>`) is never forwarded to it as client flags.
  */
-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;
+async function connectAssistant(ctx) {
+  if (config.load().mcpConnectedAt) {
+    const names = assistantNames();
+    done("assistant", ok(`✓ ${names.length ? names.join(", ") : "Assistant"} connected`));
+    return GO;
   }
+  active("assistant", "Connect your AI assistant");
   try {
-    await abCmd.enable({ yes: true });
+    const { withPrefix } = require("../lib/nestedOutput");
+    await withPrefix("│", () => require("./mcp").install([]));
+    config.save({ mcpConnectedAt: new Date().toISOString() });
+    done("assistant", ok("✓ Assistant connected"));
+    ctx.restartAssistant = true; // said after "Niro is ready", where it is the next thing to do
   } 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})`);
+    // The graph IS built by now; one command retries this. A wizard that printed to the terminal has
+    // already said why ("✗ Claude Code could not be set up"), so its exit code is not repeated.
+    done("assistant", warn("⚠ No assistant connected"));
+    if (!(err && err.alreadySaid)) rail(`Could not configure an assistant: ${err && err.message ? err.message : err}`);
+    rail(`Run ${color.cyan("niro mcp install")} when you are ready.`);
+    rail();
+    return "skipped";
   }
+  rail();
+  return GO;
 }
 
 /**
- * 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.
+ * Folders set up with Niro web, in a release without the cloud: say they are no longer uploaded,
+ * offer to index them here, then retire the list so it is said once. The folder just built is
+ * skipped, and indexing stops at the line limit rather than sending anyone to the upgrade page.
  */
-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)}`);
+async function moveWebFolders(ctx, { folders = watchState.allLocal, ask = prompt.confirm,
+  init = (dir) => require("./initLocal").initLocal(dir, { openUrl: () => {} }) } = {}) {
+  if (release.cloud) return;
+  const web = (() => { try { return folders() || []; } catch { return []; } })();
+  if (web.length === 0) return;
+  for (const line of migrationNotice.webLines(web)) console.log(line);
+  const here = web.filter((f) => path.resolve(f.folderPath) !== ctx.dir && fs.existsSync(f.folderPath));
+  if (here.length > 0 && await ask(`  Index ${here.length === 1 ? "it" : `these ${here.length} folders`} on this machine now?`, false)) {
+    for (const f of here) {
+      const used = await planUsage.linesUsed().catch(() => 0);
+      if (await planUsage.refusesBuild(ctx.claims, used, f.folderPath)) {
+        console.log(`  Stopped: the line limit is reached. See ${color.cyan("niro plan")}.`);
+        break;
+      }
+      await init(f.folderPath);
+      process.exitCode = 0;
+    }
   }
+  try { watchState.retireToWeb(); } catch { /* kept as is; the note shows again next time */ }
   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.
+ * True when niro-watch started before this copy was installed, so it still runs the code of the
+ * version before: `npm install -g` swaps the files but not a running process.
  */
-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("");
+function watcherIsOld() {
+  const at = service.startedAt();
+  if (!at) return false;
+  try {
+    return at < fs.statSync(path.join(__dirname, "..", "..", "package.json")).ctimeMs; // ctime: npm may stamp a fixed mtime
+  } catch {
+    return false;
+  }
 }
 
-/**
- * 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 watch daemon, so "updates automatically" on the ready screen is true. */
+async function keepItCurrent(ctx) {
+  if (watchDaemon.watchDaemonState() === "running") {
+    // A watcher saved by an older niro-cli holds the whole shell environment in ~/.pm2/dump.pm2:
+    // this starts it again with only what it needs (no password, the login hook is left alone).
+    let refreshed;
+    try { refreshed = service.refreshSavedEnv(); } catch { refreshed = null; }
+    if (refreshed !== null) {
+      if (!refreshed && watcherIsOld()) service.restart();
+      ctx.watching = true;
+      return;
+    }
+    // Starting it again failed, so it is not running now: the steps below install it as usual.
+  }
+  const heading = "◆  Keeping your graph current";
+  console.log(heading);
+  const { withPrefix } = require("../lib/nestedOutput");
+  const r = await withPrefix("│", () => watchDaemon.ensureWatchDaemon({ quiet: true, heading }));
+  ctx.watching = !!(r && r.ok);
+  if (!ctx.watching) console.log(`◇  ${warn("⚠")} The graph will not update on its own. Run ${color.cyan("niro service install")} to retry`);
+  else if (r.autostart === false) console.log(`◇  ${ok("✓")} Updating as files change, until you log out`);
+  else console.log(`◇  ${ok("✓")} Updating as files change, and after every login`);
+  rail();
+}
+
+/** The commands worth knowing after setup, on the ready screen. */
+const USEFUL = [
+  ["niro init", "Add another repo: run it inside that folder"],
+  ["niro status", "Check this folder's graph"],
+  ["niro plan", "See your line usage, folders and options"],
+  ["niro mcp install", "Connect another AI assistant"],
+  ["niro uninstall", "Remove Niro from this machine"],
+];
+
+/** The folder's languages, read and not, looked at once per run: listing a large repository takes a while. */
+function scanLanguages(ctx) {
+  if (!ctx.languages) ctx.languages = languages.scan(ctx.dir);
+  return ctx.languages;
+}
+
+const foundLanguages = (ctx) => scanLanguages(ctx).found;
+
+/** The request command for a language name, quoted when the shell would read it otherwise ("visual basic", "f#"). */
+function requestCommand(name) {
+  const word = name.toLowerCase();
+  return `niro request-integration ${/^[a-z0-9.+-]+$/.test(word) ? word : `"${word}"`}`;
+}
+
+async function printReady(ctx) {
+  const names = assistantNames();
+  console.log(`${ok("◆")}  Setup complete`);
+  const last = ctx.worktree && ctx.worktree.worktree && ctx.worktree.worktree.last_build_at;
+  rail(`Graph      ${ctx.built ? `${counts(ctx.built)} · built just now` : last ? `built ${ago(last)}` : "built"}`);
+  const { found, others } = scanLanguages(ctx);
+  rail(`Languages  ${found.length ? languages.short(found, 4) : `none found. Niro reads ${languages.supportedList()}`}`);
+  if (others.length) {
+    rail(`Not read   ${languages.short(others, 3)}. Ask for ${others.length === 1 ? "it" : "one"}: ${color.cyan(requestCommand(others[0]))}`);
+  }
+  rail(`Assistant  ${names.length ? names.join(", ") : `not connected. Run ${color.cyan("niro mcp install")}`}`);
+  rail(`Sync       ${ctx.watching ? "on, updates as files change" : `off. Run ${color.cyan("niro service install")}`}`);
+  const plan = ctx.plan || planUsage.describe(ctx.claims, await planUsage.linesUsed());
+  if (plan) rail(`Plan       ${plan}`);
+  if (ctx.noRoom) {
+    rail(`           ${color.yellow(ctx.noRoom)}`);
+    rail(`           Run ${color.cyan("niro plan")} to unlock unlimited lines or start a Pro free trial.`);
+  }
+  closeReady(names.length === 1 ? names[0] : "your assistant", !!ctx.restartAssistant);
+}
+
+function assistantNames() {
+  try {
+    return mcpClients.clientNames(mcpClients.configuredClients());
+  } catch {
+    return [];
+  }
+}
+
+/** " (0.1.1)": the version folder of an engine from the download cache, else nothing. */
+function engineVersion(executable) {
+  const m = /[\\/]bin[\\/]([^\\/]+)[\\/]niro-local-[^\\/]+[\\/]/.exec(String(executable || ""));
+  return m ? ` (${m[1]})` : "";
 }
 
+/** "just now", "5 min ago", "3 h ago", then the local date: when the graph was last built. */
+function ago(iso, now = Date.now()) {
+  const minutes = Math.floor((now - Date.parse(iso)) / 60000);
+  if (!Number.isFinite(minutes)) return `last built ${iso}`;
+  if (minutes < 1) return "just now";
+  if (minutes < 60) return `${minutes} min ago`;
+  if (minutes < 24 * 60) return `${Math.floor(minutes / 60)} h ago`;
+  return `on ${new Date(iso).toLocaleDateString("en-CA")}`;
+}
+
+function counts(b) {
+  const parts = [];
+  if (b.files !== null && b.files !== undefined) parts.push(`${b.files.toLocaleString("en-US")} files`);
+  if (b.lines !== null && b.lines !== undefined) parts.push(`${b.lines.toLocaleString("en-US")} lines`);
+  return parts.join(", ") || "done";
+}
+
+
 /**
  * The same condition credentials.requireCreds() enforces, and deliberately not a second
  * definition of it: any usable credential counts, because the request layer refreshes an
@@ -293,7 +526,7 @@ function runningFromNpxCache(argv1 = process.argv[1]) {
  * 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" });
+  const r = childProcess.spawnSync("npm", ["prefix", "-g"], { shell: process.platform === "win32", encoding: "utf8" });
   if (r.status !== 0) return null;
   const prefix = String(r.stdout || "").trim();
   if (!prefix) return null;
@@ -332,27 +565,18 @@ function isOlder(a, b) {
  * 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;
-  }
+async function bootstrapIfNpx(pathArg) {
+  // Nothing to do, and nothing said: either this IS the handed-over child, or niro was
+  // installed properly in the first place. Step 1's machine lines already cover it.
+  if (process.env[BOOTSTRAP_ENV] || !runningFromNpxCache()) 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");
+  rail("Installing niro so background updates outlive npx's temporary cache…");
 
   let bin = globalNiroPath();
   if (bin && isCurrent(bin)) {
-    console.log(`        ${ok("✓")} Already installed at ${bin}.\n`);
+    rail(`${ok("✓")} Already installed at ${bin}`);
   } else {
-    const r = childProcess.spawnSync("npm", ["install", "-g", PACKAGE_NAME], { shell: true, stdio: "inherit" });
+    const r = childProcess.spawnSync("npm", ["install", "-g", PACKAGE_NAME], { shell: process.platform === "win32", 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.
@@ -363,7 +587,7 @@ async function bootstrapIfNpx(pathArg, firstRun = false) {
       process.exitCode = 1;
       return true;
     }
-    console.log(`        ${ok("✓")} ${PACKAGE_NAME} installed at ${bin}.\n`);
+    rail(`${ok("✓")} ${PACKAGE_NAME} installed at ${bin}`);
   }
 
   const args = ["start"];
@@ -378,84 +602,15 @@ async function bootstrapIfNpx(pathArg, firstRun = false) {
   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.
+ * Why this folder can never be indexed, in the wizard's voice, or null when that is for the engine to say.
  *
- * 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.
+ * Only what needs no engine: a path that is not a folder, and a protected folder (home, the filesystem root, a system
+ * folder). Whether the folder holds a project is the engine's question, asked by the engine's own `init`
+ * (localOnboard.initAndBuild), because niro-cli's own answer disagreed with it: niro-cli looked for a build file two levels
+ * down and had no rule for a folder of repositories, the engine looks three levels down and accepts one, so the
+ * engine offered `niro init` for folders `niro init` then refused (VP-release-texts-2 note A; Niraj, 2026-11-06:
+ * "niro should ask niro-engine"). `niro start` runs this before the engine is downloaded, so no engine can be asked.
  */
 function describeProblem(dir) {
   if (!fs.existsSync(dir)) {
@@ -469,100 +624,25 @@ function describeProblem(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.`,
+        "It would index every repository under it as one project.",
+        "Run niro start from your project's folder 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,
   globalNiroPath,
   isOlder,
   describeProblem,
-  expandHome,
+  moveWebFolders,
+  watcherIsOld,
   BOOTSTRAP_ENV,
 };