sakuraai 0.0.9 → 0.0.11

package/dist/index.js

@@ -103,8 +103,8 @@ var init_config = __esm({
 function apiBase() {
   return (loadAuth().serverUrl || DEFAULT_API_URL).replace(/\/+$/, "");
 }
-async function postJson(base, path10, body, token) {
-  const res = await fetch(`${base}${path10}`, {
+async function postJson(base, path12, body, token) {
+  const res = await fetch(`${base}${path12}`, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
@@ -114,7 +114,7 @@ async function postJson(base, path10, body, token) {
   });
   if (!res.ok) {
     const text = await res.text().catch(() => "");
-    throw new Error(`${path10} \u2192 ${res.status} ${res.statusText}${text ? `: ${text}` : ""}`);
+    throw new Error(`${path12} \u2192 ${res.status} ${res.statusText}${text ? `: ${text}` : ""}`);
   }
   return await res.json();
 }
@@ -535,7 +535,7 @@ function sessionCwd(sessionId) {
   }
   return void 0;
 }
-function send(sessionId, message, onData, images) {
+function send(sessionId, message, onData, images, model) {
   return new Promise((resolve) => {
     const bin = process.env.CLAUDE_BIN || "claude";
     const cwd = sessionCwd(sessionId);
@@ -546,6 +546,7 @@ function send(sessionId, message, onData, images) {
 
 ${refs}` : refs;
     }
+    const modelArgs = model ? ["--model", model] : [];
     const child2 = spawn2(
       bin,
       [
@@ -553,6 +554,7 @@ ${refs}` : refs;
         sessionId,
         "-p",
         prompt,
+        ...modelArgs,
         "--output-format",
         "stream-json",
         "--include-partial-messages",
@@ -723,10 +725,11 @@ function messages2(sessionId) {
   const file = findFile2(sessionId);
   return file ? readMessages2(file) : [];
 }
-function send2(sessionId, message, onData, images) {
+function send2(sessionId, message, onData, images, model) {
   return new Promise((resolve) => {
     const imageArgs = (images ?? []).flatMap((p) => ["-i", p]);
-    const child2 = spawn3(codexBin(), ["exec", "resume", sessionId, ...imageArgs, message], {
+    const modelArgs = model ? ["--model", model] : [];
+    const child2 = spawn3(codexBin(), ["exec", ...modelArgs, "resume", sessionId, ...imageArgs, message], {
       stdio: ["ignore", "pipe", "pipe"],
       env: process.env
     });
@@ -870,10 +873,11 @@ async function messages3(sessionId) {
     db.close();
   }
 }
-function send3(sessionId, message, onData, images) {
+function send3(sessionId, message, onData, images, model) {
   return new Promise((resolve) => {
     const fileArgs = (images ?? []).flatMap((p) => ["-f", p]);
-    const child2 = spawn4(opencodeBin(), ["run", "-s", sessionId, ...fileArgs, message], {
+    const modelArgs = model ? ["-m", model] : [];
+    const child2 = spawn4(opencodeBin(), ["run", "-s", sessionId, ...modelArgs, ...fileArgs, message], {
       stdio: ["ignore", "pipe", "pipe"],
       env: process.env
     });
@@ -1002,11 +1006,11 @@ async function history(sessionId, opts = {}, agent) {
   if (opts.reverse) msgs = [...msgs].reverse();
   return msgs;
 }
-async function chat(sessionId, prompt, agent, onData, images) {
+async function chat(sessionId, prompt, agent, onData, images, model) {
   const a = agent ?? await detectAgent(sessionId);
-  if (a === "claude") return send(sessionId, prompt, onData, images);
-  if (a === "codex") return send2(sessionId, prompt, onData, images);
-  if (a === "opencode") return send3(sessionId, prompt, onData, images);
+  if (a === "claude") return send(sessionId, prompt, onData, images, model);
+  if (a === "codex") return send2(sessionId, prompt, onData, images, model);
+  if (a === "opencode") return send3(sessionId, prompt, onData, images, model);
   return {
     ok: false,
     output: "",
@@ -1512,6 +1516,94 @@ var init_tailscale = __esm({
   }
 });
 
+// src/runtime/models.ts
+import fs10 from "fs";
+import path8 from "path";
+import { execFileSync } from "child_process";
+function codexModels() {
+  const out = [{ id: "", label: "Default" }];
+  const seen = /* @__PURE__ */ new Set();
+  let configured;
+  try {
+    const cfg = fs10.readFileSync(path8.join(HOME, ".codex", "config.toml"), "utf8");
+    configured = /^\s*model\s*=\s*"([^"]+)"/m.exec(cfg)?.[1];
+    for (const m of cfg.matchAll(/model\s*=\s*"([^"]+)"/g)) {
+      const id = m[1];
+      if (id && !seen.has(id)) {
+        seen.add(id);
+        out.push({ id, label: id === configured ? `${id} (config)` : id });
+      }
+    }
+  } catch {
+  }
+  for (const id of CODEX_CURATED) {
+    if (!seen.has(id)) {
+      seen.add(id);
+      out.push({ id, label: id });
+    }
+  }
+  return out;
+}
+function opencodeModels() {
+  const out = [{ id: "", label: "Default" }];
+  const allowed = /* @__PURE__ */ new Set(["opencode"]);
+  try {
+    const auth = JSON.parse(
+      fs10.readFileSync(path8.join(HOME, ".local", "share", "opencode", "auth.json"), "utf8")
+    );
+    for (const k of Object.keys(auth)) allowed.add(k);
+  } catch {
+  }
+  try {
+    const raw = execFileSync(opencodeBin(), ["models"], { encoding: "utf8", timeout: 15e3 });
+    for (const line of raw.split("\n").map((l) => l.trim()).filter(Boolean)) {
+      const slash = line.indexOf("/");
+      if (slash < 0) continue;
+      const provider = line.slice(0, slash);
+      const model = line.slice(slash + 1);
+      if (!allowed.has(provider)) continue;
+      out.push({
+        id: line,
+        // opencode wants the full provider/model string
+        label: model,
+        group: OC_PROVIDER_LABELS[provider] ?? provider,
+        free: provider === "opencode" || /free/i.test(model)
+      });
+    }
+  } catch {
+  }
+  return out;
+}
+function listModels(agent) {
+  if (agent === "codex") return codexModels();
+  if (agent === "opencode") return opencodeModels();
+  return CLAUDE_MODELS;
+}
+var CLAUDE_MODELS, CODEX_CURATED, OC_PROVIDER_LABELS;
+var init_models = __esm({
+  "src/runtime/models.ts"() {
+    "use strict";
+    init_util();
+    init_opencode();
+    CLAUDE_MODELS = [
+      { id: "", label: "Default" },
+      { id: "opus", label: "Opus" },
+      { id: "sonnet", label: "Sonnet" },
+      { id: "haiku", label: "Haiku" },
+      { id: "opus[1m]", label: "Opus (1M context)" }
+    ];
+    CODEX_CURATED = ["gpt-5.5-codex", "gpt-5.5", "gpt-5-codex", "gpt-5"];
+    OC_PROVIDER_LABELS = {
+      opencode: "OpenCode Zen",
+      "opencode-go": "OpenCode Go",
+      openrouter: "OpenRouter",
+      zai: "Z.AI",
+      "zai-coding-plan": "Z.AI Coding",
+      "zhipuai-coding-plan": "Zhipu Coding"
+    };
+  }
+});
+
 // src/daemon/hub.ts
 function sessionKey(agent, sessionId) {
   return `${agent}:${sessionId}`;
@@ -1550,7 +1642,7 @@ var init_hub = __esm({
 });
 
 // src/daemon/stream.ts
-async function runTurn(sessionId, agent, prompt, images) {
+async function runTurn(sessionId, agent, prompt, images, model) {
   const key = sessionKey(agent, sessionId);
   const emit = (e) => hub.broadcast(key, e);
   let lastEmitted = "\0";
@@ -1590,7 +1682,7 @@ async function runTurn(sessionId, agent, prompt, images) {
     } catch {
     }
   }, POLL_MS);
-  const result = await chat(sessionId, prompt, agent, onData, images);
+  const result = await chat(sessionId, prompt, agent, onData, images, model);
   clearInterval(timer);
   emit({ type: "done", sessionId, agent, ok: result.ok, error: result.error });
   notifyTurnEnd(agent, sessionId, result.ok, result.error, stdoutAcc);
@@ -1698,15 +1790,15 @@ var init_terminal = __esm({
 
 // src/daemon/server.ts
 import http from "http";
-import fs10 from "fs";
+import fs11 from "fs";
 import os7 from "os";
-import path8 from "path";
+import path9 from "path";
 import { URL } from "url";
 import { WebSocketServer } from "ws";
-function add(method, path10, handler) {
+function add(method, path12, handler) {
   const keys = [];
   const pattern = new RegExp(
-    "^" + path10.replace(/:[^/]+/g, (m) => {
+    "^" + path12.replace(/:[^/]+/g, (m) => {
       keys.push(m.slice(1));
       return "([^/]+)";
     }) + "/?$"
@@ -1720,8 +1812,8 @@ function fail(code, stderr, data = null) {
   return { ok: false, data, stdout: "", stderr, code };
 }
 function saveImages(sessionId, images) {
-  const dir = path8.join(os7.tmpdir(), "sakura-uploads", sessionId.slice(0, 24));
-  fs10.mkdirSync(dir, { recursive: true });
+  const dir = path9.join(os7.tmpdir(), "sakura-uploads", sessionId.slice(0, 24));
+  fs11.mkdirSync(dir, { recursive: true });
   const paths = [];
   images.forEach((img, i) => {
     const raw = String(img?.data ?? "");
@@ -1732,8 +1824,8 @@ function saveImages(sessionId, images) {
     }
     const ext = EXT_BY_MIME[m[1]] ?? "png";
     const safe = img.name && /\.[a-z0-9]+$/i.test(img.name) ? img.name.replace(/[^\w.\-]/g, "_") : `image-${Date.now()}-${i + 1}.${ext}`;
-    const file = path8.join(dir, safe);
-    fs10.writeFileSync(file, Buffer.from(m[2], "base64"));
+    const file = path9.join(dir, safe);
+    fs11.writeFileSync(file, Buffer.from(m[2], "base64"));
     log.info(`saveImages: wrote ${file} (${m[2].length} b64 chars)`);
     paths.push(file);
   });
@@ -1874,6 +1966,7 @@ var init_server = __esm({
     init_fsops();
     init_tailscale();
     init_registry();
+    init_models();
     init_hub();
     init_stream();
     init_terminal();
@@ -1905,7 +1998,8 @@ var init_server = __esm({
       log.info(`send: agent=${agent} msgLen=${message.length} bodyKeys=[${Object.keys(body ?? {}).join(",")}] images=${incoming.length}`);
       const imagePaths = incoming.length ? saveImages(params.id, incoming) : [];
       if (imagePaths.length) log.info(`send: attached ${imagePaths.length} image(s) to ${agent} prompt`);
-      const r = await runTurn(params.id, agent, message, imagePaths);
+      const model = body?.model ? String(body.model) : void 0;
+      const r = await runTurn(params.id, agent, message, imagePaths, model);
       return { ok: r.ok, error: r.error };
     });
     add("POST", "/sessions/:id/rename", ({ params, body }) => {
@@ -1944,7 +2038,7 @@ var init_server = __esm({
         case "logs": {
           let logs2 = "";
           try {
-            const lines = fs10.readFileSync(LOG_PATH, "utf8").split("\n");
+            const lines = fs11.readFileSync(LOG_PATH, "utf8").split("\n");
             logs2 = lines.slice(-200).join("\n");
           } catch {
           }
@@ -1977,6 +2071,10 @@ var init_server = __esm({
       ({ url }) => ok(listMachines(url.searchParams.get("onlineOnly") === "true"))
     );
     add("GET", "/sakura/projects", () => ok(listProjects()));
+    add("GET", "/sakura/models", ({ url }) => {
+      const agent = url.searchParams.get("agent") || "claude";
+      return ok(listModels(agent));
+    });
     add("POST", "/sakura/push-token", ({ body }) => {
       const token = String(body?.token ?? "");
       if (!token) return fail("bad_request", "token required");
@@ -2012,7 +2110,8 @@ var init_server = __esm({
     add("POST", "/sakura/sessions/:id/chat", async ({ params, body }) => {
       const agent = body?.agent || await detectAgent(params.id);
       if (!agent) return fail("nonzero", "unknown agent for session");
-      const r = await runTurn(params.id, agent, String(body?.prompt ?? ""));
+      const model = body?.model ? String(body.model) : void 0;
+      const r = await runTurn(params.id, agent, String(body?.prompt ?? ""), void 0, model);
       return r.ok ? ok({ ok: true }) : fail("nonzero", r.error ?? "chat failed");
     });
     add(
@@ -2131,24 +2230,24 @@ var init_server = __esm({
 });
 
 // src/daemon/tsnet.ts
-import fs11 from "fs";
-import path9 from "path";
+import fs12 from "fs";
+import path10 from "path";
 import { fileURLToPath } from "url";
 import { spawn as spawn8 } from "child_process";
 function resolveBinary() {
   const envBin = process.env.SAKURA_TSNET_BIN;
-  if (envBin && fs11.existsSync(envBin)) return envBin;
-  const here = path9.dirname(fileURLToPath(import.meta.url));
+  if (envBin && fs12.existsSync(envBin)) return envBin;
+  const here = path10.dirname(fileURLToPath(import.meta.url));
   const name = process.platform === "win32" ? "sakura-tsnet.exe" : "sakura-tsnet";
   const candidates = [
-    path9.join(here, "..", "bin", name),
+    path10.join(here, "..", "bin", name),
     // package/bin (postinstall download / build-sidecar.sh)
-    path9.join(here, "bin", name),
-    path9.join(process.cwd(), "bin", name),
-    path9.join(SAKURA_DIR, name)
+    path10.join(here, "bin", name),
+    path10.join(process.cwd(), "bin", name),
+    path10.join(SAKURA_DIR, name)
     // user-dropped
   ];
-  return candidates.find((p) => fs11.existsSync(p)) ?? null;
+  return candidates.find((p) => fs12.existsSync(p)) ?? null;
 }
 function startTsnet(port2) {
   const cfg = loadConfig();
@@ -2171,11 +2270,11 @@ function spawnSidecar(bin, controlUrl, authKey, hostname2, port2) {
     SAKURA_TS_CONTROL_URL: controlUrl,
     SAKURA_TS_AUTH_KEY: authKey,
     SAKURA_TS_HOSTNAME: hostname2,
-    SAKURA_TS_STATE_DIR: path9.join(SAKURA_DIR, "tsnet-state"),
+    SAKURA_TS_STATE_DIR: path10.join(SAKURA_DIR, "tsnet-state"),
     SAKURA_TS_STATE_FILE: TSNET_PATH,
     SAKURA_TS_PORT: String(port2)
   };
-  log.info(`starting embedded Tailscale sidecar (${path9.basename(bin)})`);
+  log.info(`starting embedded Tailscale sidecar (${path10.basename(bin)})`);
   const c = spawn8(bin, [], { stdio: ["ignore", "pipe", "pipe"], env });
   child = c;
   const pipe = (buf) => buf.toString().split("\n").filter(Boolean).forEach((line) => log.info(`[tsnet] ${line}`));
@@ -2204,7 +2303,7 @@ function stopTsnet() {
     child = null;
   }
   try {
-    fs11.rmSync(TSNET_PATH, { force: true });
+    fs12.rmSync(TSNET_PATH, { force: true });
   } catch {
   }
 }
@@ -2221,7 +2320,7 @@ var init_tsnet = __esm({
 });
 
 // src/daemon/manager.ts
-import fs12 from "fs";
+import fs13 from "fs";
 import { spawn as spawn9 } from "child_process";
 async function ensureTailnetProvisioned() {
   const serverToken = getServerToken();
@@ -2244,7 +2343,7 @@ async function ensureTailnetProvisioned() {
 }
 function readDaemonInfo() {
   try {
-    return JSON.parse(fs12.readFileSync(DAEMON_PATH, "utf8"));
+    return JSON.parse(fs13.readFileSync(DAEMON_PATH, "utf8"));
   } catch {
     return null;
   }
@@ -2261,8 +2360,8 @@ function running() {
   const info2 = readDaemonInfo();
   if (info2 && pidAlive(info2.pid)) return info2;
   if (info2) {
-    fs12.rmSync(DAEMON_PATH, { force: true });
-    fs12.rmSync(PID_PATH, { force: true });
+    fs13.rmSync(DAEMON_PATH, { force: true });
+    fs13.rmSync(PID_PATH, { force: true });
   }
   return null;
 }
@@ -2285,8 +2384,8 @@ async function runServer(version) {
     url: `http://${host}:${port2}`,
     startedAt: Date.now()
   };
-  fs12.writeFileSync(DAEMON_PATH, JSON.stringify(info2, null, 2));
-  fs12.writeFileSync(PID_PATH, String(process.pid));
+  fs13.writeFileSync(DAEMON_PATH, JSON.stringify(info2, null, 2));
+  fs13.writeFileSync(PID_PATH, String(process.pid));
   await ensureTailnetProvisioned();
   startTsnet(port2);
   const tailnet = await discoverBaseUrl(port2).catch(() => null);
@@ -2297,8 +2396,8 @@ async function runServer(version) {
     log.info("shutting down");
     stopTsnet();
     server.close();
-    fs12.rmSync(DAEMON_PATH, { force: true });
-    fs12.rmSync(PID_PATH, { force: true });
+    fs13.rmSync(DAEMON_PATH, { force: true });
+    fs13.rmSync(PID_PATH, { force: true });
     process.exit(0);
   };
   process.on("SIGINT", shutdown);
@@ -2309,8 +2408,8 @@ function start() {
   if (existing) return existing;
   ensureSakuraDirs();
   const entry = process.argv[1] ?? "";
-  const out = fs12.openSync(LOG_PATH, "a");
-  const err = fs12.openSync(LOG_PATH, "a");
+  const out = fs13.openSync(LOG_PATH, "a");
+  const err = fs13.openSync(LOG_PATH, "a");
   const child2 = spawn9(process.execPath, [entry, "__run-daemon"], {
     detached: true,
     stdio: ["ignore", out, err],
@@ -2332,8 +2431,8 @@ function stop() {
     process.kill(info2.pid, "SIGTERM");
   } catch {
   }
-  fs12.rmSync(DAEMON_PATH, { force: true });
-  fs12.rmSync(PID_PATH, { force: true });
+  fs13.rmSync(DAEMON_PATH, { force: true });
+  fs13.rmSync(PID_PATH, { force: true });
   return true;
 }
 function restart() {
@@ -2343,7 +2442,7 @@ function restart() {
 }
 function logs(lines = 50) {
   try {
-    const all2 = fs12.readFileSync(LOG_PATH, "utf8").split("\n");
+    const all2 = fs13.readFileSync(LOG_PATH, "utf8").split("\n");
     return all2.slice(-lines).join("\n");
   } catch {
     return "";
@@ -2428,11 +2527,15 @@ async function showPairing(opts = {}) {
   info(`  Token: ${pairing.token}`);
   info("");
   if (pairing.embeddedTailscale) {
-    info("Embedded Tailscale: the QR also carries the tailnet join key, so the");
-    info("phone connects privately over the tunnel with no Tailscale app needed.");
+    info("Embedded Tailscale: the QR carries the private tailnet join key, so the");
+    info("phone connects over the tunnel from any network \u2014 no Tailscale app needed.");
     info("");
+    info("\u26A0 Scan the QR to connect from another network or mobile data. Pasting the");
+    info("  URL + token by hand does NOT include the join key, so it only works when");
+    info("  the phone is on the same Wi\u2011Fi as this Mac.");
+  } else {
+    info("Or paste the URL + token into the app (Settings \u2192 Connect) \u2014 same Wi\u2011Fi.");
   }
-  info("Or paste the token into the app (Settings \u2192 Connect).");
 }
 function registerPair(program) {
   program.command("pair").description("Show a QR code + token to pair the Sakura mobile app").option("--json", "output the pairing payload as JSON").action(async (opts) => {
@@ -2461,7 +2564,7 @@ var init_pair = __esm({
 import { Command } from "commander";
 
 // src/version.ts
-var VERSION = "0.0.9";
+var VERSION = "0.0.11";
 
 // src/index.ts
 init_config();
@@ -2522,7 +2625,25 @@ function registerAuth(program) {
 init_manager();
 init_tailscale();
 init_auth();
+init_config();
 init_output();
+var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
+async function tunnelUrl(port2) {
+  const ts = readTsnetState();
+  if (ts?.tailscaleIp && ts.backendState === "Running") return `http://${ts.tailscaleIp}:${port2}`;
+  return await discoverBaseUrl(port2).catch(() => null);
+}
+async function waitForTunnel(timeoutMs) {
+  if (!getServerToken()) return false;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const cfg = loadConfig();
+    const ts = readTsnetState();
+    if (cfg.tailscale?.controlUrl && ts?.tailscaleIp && ts.backendState === "Running") return true;
+    await sleep2(500);
+  }
+  return false;
+}
 function registerRuntime(program, version) {
   program.command("start").description("Run the Sakura runtime in this terminal (foreground)").option("--auth <token>", "sign in with a CLI token before starting").action(async (opts) => {
     if (opts.auth) {
@@ -2539,9 +2660,11 @@ function registerRuntime(program, version) {
     if (!isLoggedIn()) die("Not signed in. Run `sakuraai login` first.");
     const info0 = start();
     success(`Daemon running (pid ${info0.pid}) on ${info0.url}`);
-    const tailnet = await discoverBaseUrl(info0.port).catch(() => null);
-    if (!tailnet) {
-      warn("Tailscale not detected. Run `sakuraai serve` after `tailscale up` for a private URL.");
+    const ready = await waitForTunnel(2e4);
+    if (ready) {
+      info("Embedded Tailscale tunnel up \u2014 the phone can connect from any network, no Tailscale app needed.");
+    } else if (getServerToken()) {
+      warn("Tunnel not up yet \u2014 pairing over LAN for now. Re-run `sakuraai pair` in a moment for the private URL.");
     }
     const { showPairing: showPairing2 } = await Promise.resolve().then(() => (init_pair(), pair_exports));
     await showPairing2();
@@ -2555,7 +2678,7 @@ function registerRuntime(program, version) {
   });
   d.command("status").description("Show runtime + connection status").option("--json", "output as JSON").action(async (opts) => {
     const i = running();
-    const tailnet = i ? await discoverBaseUrl(i.port).catch(() => null) : null;
+    const tailnet = i ? await tunnelUrl(i.port) : null;
     if (opts.json) return printJson({ running: !!i, daemon: i, tailnetBaseUrl: tailnet });
     if (!i) return warn("Daemon is not running. Start it with `sakuraai daemon start`.");
     success(`Daemon running (pid ${i.pid}) on ${i.url}`);
@@ -2570,7 +2693,7 @@ function registerRuntime(program, version) {
 // src/commands/session.ts
 init_sessions();
 init_output();
-import fs13 from "fs";
+import fs14 from "fs";
 function resolveSessionId(arg) {
   const id = arg || process.env.SAKURA_SESSION_ID;
   if (!id) die("Provide a sessionId (positional or via SAKURA_SESSION_ID).");
@@ -2579,7 +2702,7 @@ function resolveSessionId(arg) {
 async function resolvePrompt(positional, opts) {
   if (positional) return positional;
   if (opts.prompt) return opts.prompt;
-  if (opts.promptFile) return fs13.readFileSync(opts.promptFile, "utf8");
+  if (opts.promptFile) return fs14.readFileSync(opts.promptFile, "utf8");
   if (!process.stdin.isTTY) {
     const chunks = [];
     for await (const c of process.stdin) chunks.push(c);
@@ -2891,6 +3014,86 @@ function registerConnectivity(program) {
 
 // src/index.ts
 init_pair();
+
+// src/commands/welcome.ts
+init_config();
+import fs15 from "fs";
+import path11 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { spawn as spawn10 } from "child_process";
+var WELCOMED_MARKER = path11.join(SAKURA_DIR, ".welcomed");
+function resolveBinary2() {
+  const envBin = process.env.SAKURA_ONBOARD_BIN;
+  if (envBin && fs15.existsSync(envBin)) return envBin;
+  const here = path11.dirname(fileURLToPath2(import.meta.url));
+  const name = process.platform === "win32" ? "sakura-onboard.exe" : "sakura-onboard";
+  const candidates = [
+    path11.join(here, "..", "bin", name),
+    // package/bin (postinstall download)
+    path11.join(here, "bin", name),
+    path11.join(process.cwd(), "bin", name),
+    path11.join(SAKURA_DIR, name)
+    // user-dropped
+  ];
+  return candidates.find((p) => fs15.existsSync(p)) ?? null;
+}
+function showWelcome() {
+  return new Promise((resolve) => {
+    const bin = resolveBinary2();
+    if (!bin) {
+      printFallback();
+      return resolve();
+    }
+    const child2 = spawn10(bin, [], { stdio: "inherit" });
+    child2.on("error", () => {
+      printFallback();
+      resolve();
+    });
+    child2.on("close", () => resolve());
+  });
+}
+async function maybeFirstRunWelcome() {
+  if (fs15.existsSync(WELCOMED_MARKER)) return;
+  if (!process.stdout.isTTY || !process.stdin.isTTY) return;
+  try {
+    fs15.writeFileSync(WELCOMED_MARKER, (/* @__PURE__ */ new Date()).toISOString());
+  } catch {
+  }
+  await showWelcome();
+}
+function printFallback() {
+  const out = `
+\u{1F338} Sakura \u2014 your coding agents, in your pocket
+
+Two ways your phone reaches this Mac:
+
+  1  Home Wi-Fi  (same network, simple)
+       Phone \u2500\u2500Wi-Fi\u2500\u2500> Mac  (192.168.x.x)
+       \u2022 sakura daemon start
+       \u2022 paste the URL + token in the app (or scan the QR)
+       \u2022 works only while both are on the same Wi-Fi
+
+  2  Tailscale  (any network / mobile data, private)
+       Phone \u2550tunnel\u2550> private mesh \u2550tunnel\u2550> Mac  (100.x)
+       \u2022 sakura login            (links this Mac to your account)
+       \u2022 sakura daemon start     (joins the tunnel, prints a QR)
+       \u2022 SCAN THE QR in the app  (the QR carries the private key)
+       \u2022 no Tailscale app needed \u2014 it's built in
+
+Pasting the URL by hand can't carry the tunnel key, so paste is
+same-Wi-Fi only. Scan the QR to connect from anywhere.
+
+Docs: https://www.sakura.mom  \xB7  Show again: sakura welcome
+`;
+  process.stdout.write(out + "\n");
+}
+function registerWelcome(program) {
+  program.command("welcome").aliases(["guide"]).description("Show the Sakura connection guide (Home Wi-Fi vs Tailscale)").action(async () => {
+    await showWelcome();
+  });
+}
+
+// src/index.ts
 init_manager();
 async function main() {
   ensureSakuraDirs();
@@ -2898,6 +3101,10 @@ async function main() {
     await runServer(VERSION);
     return;
   }
+  const sub = process.argv[2];
+  if (sub !== "welcome" && sub !== "guide") {
+    await maybeFirstRunWelcome();
+  }
   const program = new Command();
   program.name("sakuraai").description(
     "Sakura Agent CLI \u2014 manage local AI coding sessions and reach them from the Sakura app over Tailscale"
@@ -2908,6 +3115,7 @@ async function main() {
   registerRegistry(program);
   registerConnectivity(program);
   registerPair(program);
+  registerWelcome(program);
   program.showHelpAfterError("(add --help for usage)");
   await program.parseAsync(process.argv);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sakuraai",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "Sakura Agent CLI + local runtime for managing AI coding sessions (Claude Code, Codex, OpenCode) and reaching them privately from the Sakura mobile app over Tailscale",
   "type": "module",
   "main": "dist/index.js",
@@ -28,6 +28,7 @@
     "dist",
     "!dist/**/*.map",
     "scripts/download-tsnet.js",
+    "scripts/download-onboard.js",
     "README.md"
   ],
   "scripts": {
@@ -36,7 +37,7 @@
     "dev": "tsx src/index.ts",
     "clean": "rimraf dist",
     "typecheck": "tsc --noEmit",
-    "postinstall": "node scripts/download-tsnet.js",
+    "postinstall": "node scripts/download-tsnet.js && node scripts/download-onboard.js",
     "prepublishOnly": "npm run clean && npm run build"
   },
   "dependencies": {

package/scripts/download-onboard.js

@@ -0,0 +1,68 @@
+// postinstall: fetch the prebuilt `sakura-onboard` bubbletea welcome UI for this
+// OS/arch from the public Nishu0/sakura-tsnet Release matching this package
+// version. Best-effort by design — if anything fails (offline, unsupported
+// platform, missing asset) we exit 0 so `npm install` never breaks; the CLI just
+// prints a plain-text guide instead of the interactive one.
+//
+// Skips:  SAKURA_SKIP_ONBOARD_DOWNLOAD=1, SAKURA_ONBOARD_BIN set, or already present.
+// Override source:  SAKURA_ONBOARD_TAG, SAKURA_ONBOARD_BASE_URL.
+
+import fs from "node:fs";
+import path from "node:path";
+import https from "node:https";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(fs.readFileSync(path.join(here, "..", "package.json"), "utf8"));
+
+const PLAT = { darwin: "darwin", linux: "linux", win32: "windows" }[process.platform];
+const ARCH = { x64: "amd64", arm64: "arm64" }[process.arch];
+const isWin = process.platform === "win32";
+
+const binDir = path.join(here, "..", "bin");
+const outPath = path.join(binDir, isWin ? "sakura-onboard.exe" : "sakura-onboard");
+
+if (process.env.SAKURA_SKIP_ONBOARD_DOWNLOAD === "1" || process.env.SAKURA_ONBOARD_BIN) process.exit(0);
+if (fs.existsSync(outPath)) process.exit(0);
+if (!PLAT || !ARCH) process.exit(0);
+
+const asset = `sakura-onboard-${PLAT}-${ARCH}${isWin ? ".exe" : ""}`;
+const tag = process.env.SAKURA_ONBOARD_TAG || `v${pkg.version}`;
+const base = process.env.SAKURA_ONBOARD_BASE_URL || `https://github.com/Nishu0/sakura-tsnet/releases/download/${tag}`;
+const url = `${base}/${asset}`;
+
+function download(u, redirectsLeft = 5) {
+  return new Promise((resolve, reject) => {
+    https
+      .get(u, { headers: { "User-Agent": "sakuraai-postinstall" } }, (res) => {
+        if ([301, 302, 303, 307, 308].includes(res.statusCode) && res.headers.location) {
+          if (redirectsLeft <= 0) return reject(new Error("too many redirects"));
+          res.resume();
+          return resolve(download(res.headers.location, redirectsLeft - 1));
+        }
+        if (res.statusCode !== 200) {
+          res.resume();
+          return reject(new Error(`HTTP ${res.statusCode} for ${u}`));
+        }
+        fs.mkdirSync(binDir, { recursive: true });
+        const tmp = `${outPath}.download`;
+        const file = fs.createWriteStream(tmp);
+        res.pipe(file);
+        file.on("finish", () => file.close(() => {
+          fs.renameSync(tmp, outPath);
+          if (!isWin) fs.chmodSync(outPath, 0o755);
+          resolve();
+        }));
+        file.on("error", reject);
+      })
+      .on("error", reject);
+  });
+}
+
+try {
+  await download(url);
+  console.log(`[sakura] installed welcome guide (${asset}). Run \`sakura welcome\` any time.`);
+} catch {
+  // Silent — the CLI falls back to a plain-text guide.
+  process.exit(0);
+}