svcloud 0.1.3 → 0.1.5

package/README.md

@@ -8,17 +8,33 @@ the way an AI coding agent reaches the platform.
 
 ## Install
 
+Installing `svcloud` is a required step of setting up an SV Cloud project, not
+an optional extra: it is how you sign in, and it is the only way your coding
+agent reaches the platform's tools.
+
 ```bash
 npm install -g svcloud
+svcloud --version
 svcloud login
 ```
 
-Or try it once without installing:
+The `--version` line is there to be run, not skipped. If it prints a version
+you are done. If it prints `command not found`, the install worked but your
+npm global bin directory is not on your shell's `PATH`:
 
 ```bash
-npx svcloud login
+echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
 ```
 
+Use `~/.bashrc` instead of `~/.zshrc` on most Linux shells. Then re-run
+`svcloud --version`. `svcloud mcp check` reports the same thing, along with
+everything else about your setup.
+
+`npx svcloud <command>` works too, and is fine for trying one command. It is
+the wrong thing to leave in place: every invocation re-resolves the package
+from the npm registry, which makes the registry a startup dependency of your
+coding agent's tools.
+
 An installed `svcloud` is what every example below uses, and is what a
 coding agent's harness config should point at too — see [Connect your coding
 agent](#connect-your-coding-agent).
@@ -41,7 +57,9 @@ svcloud init                  Connect a repo (defaults to the one in your workin
 svcloud runs <app>            Show or watch an app's provisioning run
 svcloud secrets <cmd>         Manage an app's keys & settings (list/set/remove)
 svcloud db <cmd>              Browse and edit an app's database (see `svcloud db` for subcommands)
+svcloud storage presign       Get a direct URL for one file in an app's file storage
 svcloud deploy <app>          Push the current branch and watch the build (must be the app's default branch)
+svcloud bundle <cmd>          Keep an app's starter current (status/update/done)
 svcloud mcp                   Run the local MCP bridge (for a coding agent's harness config)
 svcloud mcp setup <harness>   Write a coding agent harness's MCP config for svcloud
 svcloud mcp check             Diagnose sign-in state, harness configs, and live tool visibility
@@ -59,6 +77,33 @@ to skip what it would otherwise infer or ask about; `runs` reads `--id
 
 `logs` and `dev` are still on the way.
 
+### Keeping an app's starter current
+
+SV Cloud's starter gets better over time, and an app that never catches up
+keeps working but stops being able to do things the platform can now do. It can
+also keep a deploy step that fails for reasons nothing in the repo explains.
+
+```bash
+svcloud bundle status <app>   # is this app behind?
+svcloud bundle update <app>   # stage the update for review
+svcloud bundle done <app>     # record it, after you commit
+```
+
+`update` writes the new versions into `sv-cloud-bundle/` along with an
+`UPDATE.md` explaining what to do with each file. It changes nothing in your
+app's own source, and it does not commit or push — you read the diff, and
+`git` stays the undo. Most people will hand this to their coding agent
+instead: it can read the same plan through SV Cloud's tools, and it knows
+which files it may replace outright and which ones it has to merge into work
+you did.
+
+`update` refuses to run with uncommitted changes, so that the diff it produces
+means exactly one thing.
+
+Run `svcloud bundle done` once the changes are committed. Skipping it does no
+damage, but the app keeps reporting itself out of date and the next update
+starts from the wrong place.
+
 ## Connect your coding agent
 
 `svcloud mcp` runs a local MCP server that your coding agent — Antigravity,
@@ -85,8 +130,18 @@ actually expects — the config blocks below are the same data, by hand, for a
 harness that isn't in the list yet, or if you'd rather see exactly what gets
 written first. If something still doesn't work after setup, run
 `svcloud mcp check` — it reports sign-in state, a live count of tools your
-token can see, and whether each known harness's config file exists and has
-the right shape.
+token can see, whether `svcloud` is on your PATH, and whether each known
+harness's config file exists and has the right shape.
+
+**A note on `"command": "svcloud"` in the blocks below.** Your harness spawns
+that command itself, with its own environment, so the bare name only works if
+`svcloud` is on the PATH that harness inherits — and a harness that cannot
+spawn it shows you no error at all, just an MCP server with no tools.
+`svcloud mcp setup` checks first and writes an absolute path instead when the
+bare name would not resolve, which is one more reason to let it write the
+file rather than copying a block by hand. If you are writing one by hand and
+`svcloud --version` does not work in a fresh terminal, fix your PATH first
+(see [Install](#install)).
 
 ### Antigravity
 Add to `~/.gemini/config/mcp_config.json` (global) or `.agents/mcp_config.json` (workspace):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svcloud",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "The SV Cloud CLI. Alpha: login, logout, status, open, projects list, mcp, init, and runs are built; see PLANNING.md for what's still missing.",
   "type": "module",
   "license": "UNLICENSED",

package/src/commands/bundle.ts

@@ -0,0 +1,224 @@
+/**
+ * `svcloud bundle` — PLANNING.md §4 Step 8, apps/cloud F27. Brings a connected
+ * repo up to a newer starter template.
+ *
+ * The merge rules are the platform's, not the CLI's: `GET /bundle/plan`
+ * returns the base version's bytes, the new version's bytes, and a per-file
+ * action, and everything here is staging and presentation. That is deliberate,
+ * for the same reason the MCP bridge holds no tool registry — a rule that
+ * lives on the server cannot drift against the version of the CLI somebody
+ * happens to have installed.
+ *
+ * `update` writes into `sv-cloud-bundle/` and stops. It does not `git add`,
+ * commit, or push, and it never touches `src/`: the owner reads a diff, and
+ * git stays the undo. `done` is a separate command precisely because it has to
+ * run AFTER a human commits — folding it into `update` would mean recording
+ * that the update landed before it had.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { apiFetch } from "../lib/api";
+import { findProjectBySlug } from "../lib/find-project";
+import { gitWorkingState } from "../lib/git";
+import { die, printJson, printTable } from "../lib/output";
+
+const STAGE_DIR = "sv-cloud-bundle";
+
+interface BundleStatus {
+  project_id: string;
+  current_version: string | null;
+  latest_version: string;
+  update_available: boolean;
+  legacy: boolean;
+  base_unavailable_reason: string | null;
+  workflow_stale: boolean;
+  workflow_warning: string | null;
+}
+
+interface PlannedFile {
+  src: string;
+  path: string;
+  class: string;
+  action: string;
+  target?: string;
+  base?: string;
+  guidance: string;
+  retirement?: { src: string; replaced_by?: string | null; note: string };
+}
+
+interface BundlePlan extends BundleStatus {
+  framework: string;
+  migrate_once: boolean;
+  files: PlannedFile[];
+  migration_notes: string | null;
+  manifest_merge: unknown;
+  instructions: string;
+}
+
+/** Human-facing one-liners. The wire's `action` stays machine-readable. */
+const ACTION_LABEL: Record<string, string> = {
+  skip: "unchanged",
+  "fast-forward": "replace",
+  conflict: "merge (you edited it)",
+  create: "new file",
+  retire: "delete",
+  "retire-conflict": "retired, you use it",
+  locate: "find it first",
+  "merge-manifest": "merge fields",
+  "report-only": "yours, unchanged",
+};
+
+async function resolve(slug: string | undefined): Promise<{ id: string; name: string }> {
+  if (!slug) die("Usage: svcloud bundle <status|update|done> <app>");
+  const project = await findProjectBySlug(slug);
+  if (!project) die(`No app named "${slug}".`);
+  return { id: project.id, name: project.name };
+}
+
+async function statusCmd(slug: string | undefined, json: boolean): Promise<void> {
+  const project = await resolve(slug);
+  const status = await apiFetch<BundleStatus>(`/api/v1/projects/${project.id}/bundle`);
+  if (json) {
+    printJson(status);
+    return;
+  }
+  console.log(`App:      ${project.name}`);
+  console.log(`Starter:  ${status.current_version ?? "not recorded"}`);
+  console.log(`Newest:   ${status.latest_version}`);
+  if (status.workflow_warning) console.log(`\n! ${status.workflow_warning}`);
+  if (!status.update_available) {
+    console.log("\nUp to date.");
+    return;
+  }
+  if (status.legacy) {
+    console.log(
+      "\nThis app was set up before starter versions were recorded, so the first update " +
+        "has no starting point to compare against. Review every change it proposes.",
+    );
+  }
+  console.log("\nAn update is available. Run `svcloud bundle update " + (slug ?? "") + "`.");
+}
+
+async function updateCmd(slug: string | undefined, json: boolean): Promise<void> {
+  const project = await resolve(slug);
+
+  // Same preconditions as `deploy`, for the same reason: this writes files
+  // into the working tree, and a dirty tree makes the resulting diff
+  // impossible for the owner to read as "what the update did".
+  const state = await gitWorkingState();
+  if (!state) {
+    die("Run this from the app's local git repository (no repo found, or `git` isn't on PATH).");
+  }
+  if (state.dirty) {
+    die(
+      "Working tree has uncommitted changes. Commit or stash them first, so the update's own " +
+        "changes are the only thing in the diff.",
+    );
+  }
+
+  const plan = await apiFetch<BundlePlan>(`/api/v1/projects/${project.id}/bundle/plan`);
+  if (json) {
+    printJson(plan);
+    return;
+  }
+
+  if (!plan.update_available) {
+    console.log(`${project.name} is already on the newest starter (${plan.latest_version}).`);
+    return;
+  }
+
+  const actionable = plan.files.filter((f) => f.action !== "skip");
+  const cwd = process.cwd();
+  const written: string[] = [];
+
+  for (const f of actionable) {
+    if (f.target === undefined) continue;
+    const staged = join(cwd, STAGE_DIR, "files", f.src);
+    await mkdir(dirname(staged), { recursive: true });
+    await writeFile(staged, f.target, "utf8");
+    written.push(f.src);
+  }
+
+  const notes = [
+    `# Starter update: ${plan.current_version ?? "unrecorded"} to ${plan.latest_version}`,
+    "",
+    plan.instructions,
+    "",
+    plan.base_unavailable_reason ? `**Note.** ${plan.base_unavailable_reason}\n` : "",
+    "## Files",
+    "",
+    ...actionable.map((f) => {
+      const head = `### ${f.path} — ${ACTION_LABEL[f.action] ?? f.action}`;
+      const staged =
+        f.target === undefined ? "" : `\nNew version staged at \`${STAGE_DIR}/files/${f.src}\`.`;
+      const retired = f.retirement
+        ? `\nRetired${f.retirement.replaced_by ? `, superseded by ${f.retirement.replaced_by}` : ""}. ${f.retirement.note}`
+        : "";
+      return `${head}\n\n${f.guidance}${staged}${retired}\n`;
+    }),
+    plan.migration_notes ? `## Migration notes\n\n${plan.migration_notes}\n` : "",
+  ].join("\n");
+
+  await writeFile(join(cwd, STAGE_DIR, "UPDATE.md"), notes, "utf8");
+
+  printTable(
+    actionable.map((f) => ({
+      file: f.path,
+      what: ACTION_LABEL[f.action] ?? f.action,
+    })),
+    ["file", "what"],
+  );
+
+  console.log(`\nStaged ${written.length} file(s) under ${STAGE_DIR}/ — nothing in src/ changed.`);
+  console.log(`Read ${STAGE_DIR}/UPDATE.md, or open this repo with your coding agent and ask it`);
+  console.log("to apply the starter update; it can read the same plan through SV Cloud's tools.");
+  console.log(`\nWhen the changes are committed, run \`svcloud bundle done ${slug ?? ""}\`.`);
+}
+
+async function doneCmd(slug: string | undefined, json: boolean): Promise<void> {
+  const project = await resolve(slug);
+  const result = await apiFetch<{
+    version: string;
+    marker_path: string;
+    marker_contents: string;
+    changed: boolean;
+  }>(`/api/v1/projects/${project.id}/bundle/applied`, { method: "POST", body: {} });
+
+  // The marker is written HERE rather than by the server, because the server
+  // does not touch repos — same rule the rest of this feature follows.
+  const target = join(process.cwd(), result.marker_path);
+  await mkdir(dirname(target), { recursive: true });
+  await writeFile(target, result.marker_contents, "utf8");
+
+  if (json) {
+    printJson(result);
+    return;
+  }
+  console.log(`Recorded ${project.name} as running starter ${result.version}.`);
+  console.log(`Wrote ${result.marker_path}. Commit it — it is how the next update knows where to`);
+  console.log("start, and an app whose marker disagrees with its files updates badly.");
+}
+
+export async function bundleCommand(argv: string[], json: boolean): Promise<void> {
+  const [sub, ...rest] = argv;
+  switch (sub) {
+    case "status":
+      await statusCmd(rest[0], json);
+      return;
+    case "update":
+      await updateCmd(rest[0], json);
+      return;
+    case "done":
+      await doneCmd(rest[0], json);
+      return;
+    default:
+      die(
+        [
+          "Usage:",
+          "  svcloud bundle status <app>   Is this app running an out-of-date starter?",
+          "  svcloud bundle update <app>   Stage the update under sv-cloud-bundle/ for review",
+          "  svcloud bundle done <app>     Record the update after you have committed it",
+        ].join("\n"),
+      );
+  }
+}

package/src/commands/init.ts

@@ -229,8 +229,25 @@ export async function initCommand(argv: string[], json: boolean): Promise<void>
   }
 
   console.log("");
-  console.log(`Your app is at ${project.web_address ?? "(no web address yet)"} — not live yet.`);
-  console.log(
-    "Open the repo with a coding agent (it'll read SVAGENTS.md and get started), then push.",
-  );
+  // `needs_initialization` is the honest discriminator and the reason this
+  // prints two different sentences. An EMPTY target repo got the starter at
+  // its real paths, so GitHub Actions is already building it and the app
+  // comes up on its own; a repo that already had code got the starter nested
+  // inert under `sv-cloud-bundle/` and needs an agent to unpack it first.
+  // Claiming either one for both was the old message's problem.
+  if (project.needs_initialization) {
+    console.log(`Your app is at ${project.web_address ?? "(no web address yet)"} — not live yet.`);
+    console.log(
+      "Your repository already had files in it, so the starter is sitting in sv-cloud-bundle/.",
+    );
+    console.log(
+      "Open the repo with a coding agent (it'll read SVAGENTS.md and unpack it), then push.",
+    );
+  } else {
+    console.log(`Your app is at ${project.web_address ?? "(no web address yet)"}.`);
+    console.log(
+      "The starter code is committed and GitHub Actions is building it now — give it a couple of minutes.",
+    );
+    console.log(`Watch it with: svcloud status ${project.slug}`);
+  }
 }

package/src/commands/mcp-check.ts

@@ -9,10 +9,11 @@
  * found, right shape or wrong.
  */
 import { callRemote } from "./mcp";
-import { CLI_VERSION, apiBaseUrl } from "../lib/config";
+import { CLI_VERSION, PRODUCTION_API_URL, apiBaseUrl } from "../lib/config";
 import { loadTokens } from "../lib/credentials";
 import { HARNESSES, inspectHarness, type HarnessStatus } from "../lib/harnesses";
 import { printJson } from "../lib/output";
+import { bridgeCommand, isOnPath, pathHint } from "../lib/self";
 
 // The scope vocabulary svcloud-cli/svcloud-mcp currently grant by default
 // (apps/cloud/src/services/oauth.ts's OAUTH_CLIENTS, widened 2026-08-25 to
@@ -21,6 +22,20 @@ import { printJson } from "../lib/output";
 // and only refreshed by signing in again, never silently upgraded.
 const EXPECTED_SCOPE_COUNT = 6;
 
+/**
+ * A configured entry can still be pointed at a different deployment than the
+ * shell running this check — shape is right, target is wrong. That mismatch
+ * is invisible in the config file and produces an agent that silently reads
+ * and writes the wrong environment, so it is called out by name rather than
+ * folded into "configured correctly".
+ */
+function describeTarget(status: HarnessStatus): string | undefined {
+  if (status.state !== "ok") return undefined;
+  const entryUrl = status.apiUrl ?? PRODUCTION_API_URL;
+  if (entryUrl === apiBaseUrl()) return undefined;
+  return `points the bridge at ${entryUrl}, not ${apiBaseUrl()} — rerun \`svcloud mcp setup\` from this shell to repoint it`;
+}
+
 function describeStatus(status: HarnessStatus): string {
   switch (status.state) {
     case "not_found":
@@ -39,6 +54,12 @@ function describeStatus(status: HarnessStatus): string {
 export async function mcpCheckCommand(json: boolean): Promise<void> {
   const tokens = await loadTokens();
   const cwd = process.cwd();
+  // A global install whose bin directory is not on PATH is invisible until
+  // something tries to spawn `svcloud` and gets ENOENT — which, for a
+  // harness, looks exactly like "SV Cloud has no tools". Reported here
+  // rather than left for the owner to work out.
+  const onPath = isOnPath();
+  const bridge = bridgeCommand();
 
   const harnessResults = await Promise.all(
     HARNESSES.map(async (h) => ({ harness: h, status: await inspectHarness(h, cwd) })),
@@ -67,6 +88,8 @@ export async function mcpCheckCommand(json: boolean): Promise<void> {
     printJson({
       version: CLI_VERSION,
       api_base_url: apiBaseUrl(),
+      svcloud_on_path: onPath,
+      bridge_command: [bridge.command, ...bridge.args],
       signed_in: tokens !== undefined,
       scopes: tokens?.scopes ?? [],
       scopes_possibly_stale: scopeStale,
@@ -76,6 +99,7 @@ export async function mcpCheckCommand(json: boolean): Promise<void> {
         id: harness.id,
         path: status.path,
         state: status.state,
+        api_url: status.state === "ok" ? (status.apiUrl ?? PRODUCTION_API_URL) : undefined,
       })),
     });
     return;
@@ -83,6 +107,15 @@ export async function mcpCheckCommand(json: boolean): Promise<void> {
 
   console.log(`svcloud ${CLI_VERSION} (API: ${apiBaseUrl()})`);
   console.log("");
+  if (onPath) {
+    console.log("PATH: `svcloud` resolves on your PATH.");
+  } else {
+    console.log(pathHint());
+    console.log(
+      "Harness configs written by `svcloud mcp setup` use this install's absolute path, so they still work.",
+    );
+  }
+  console.log("");
   if (!tokens) {
     console.log("Sign-in: not signed in. Run `svcloud login`.");
   } else {
@@ -104,6 +137,8 @@ export async function mcpCheckCommand(json: boolean): Promise<void> {
   for (const { harness, status } of harnessResults) {
     console.log(`  ${harness.label.padEnd(14)} ${status.path}`);
     console.log(`  ${"".padEnd(14)} ${describeStatus(status)}`);
+    const target = describeTarget(status);
+    if (target) console.log(`  ${"".padEnd(14)} ${target}`);
   }
   console.log("");
   console.log("Fix a missing or wrong-shaped one with: svcloud mcp setup <harness>");

package/src/commands/mcp-setup.ts

@@ -9,8 +9,34 @@
  */
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
-import { findHarness, HARNESSES, type Harness } from "../lib/harnesses";
+import { apiBaseUrl, PRODUCTION_API_URL } from "../lib/config";
+import { findHarness, HARNESSES, type Harness, readEntryApiUrl } from "../lib/harnesses";
 import { die, hasFlag } from "../lib/output";
+import { bridgeCommand, pathHint } from "../lib/self";
+
+/**
+ * The environment the written entry should spawn the bridge with — almost
+ * always none.
+ *
+ * A harness config records a command, and the harness spawns it later from
+ * its own environment, not from the shell that ran `mcp setup`. So a bridge
+ * set up in a staging shell would still have talked to PRODUCTION every time
+ * the agent called a tool: `svcloud mcp setup` could not point an agent at
+ * anything but production at all, which is the half of the staging problem
+ * that no amount of care at the terminal could work around.
+ *
+ * Inherited rather than given a flag, deliberately. Staging is ours, not the
+ * product's, so there is no `--env` for a user to find: this reads the
+ * ambient `SVCLOUD_API_URL` and writes nothing at all when it is unset or
+ * already production, which is every real user. Their config file is
+ * byte-identical to what this command wrote before passthrough existed.
+ */
+function inheritedEnv(): Record<string, string> | undefined {
+  if (!process.env.SVCLOUD_API_URL) return undefined;
+  const base = apiBaseUrl();
+  if (base === PRODUCTION_API_URL) return undefined;
+  return { SVCLOUD_API_URL: base };
+}
 
 function usage(): string {
   const ids = HARNESSES.map((h) => h.id).join(" | ");
@@ -53,21 +79,36 @@ export async function mcpSetupCommand(argv: string[], json: boolean): Promise<vo
 
   const servers = (config[harness.serversKey] ?? {}) as Record<string, unknown>;
   const existing = servers.svcloud;
-  const entry = harness.buildEntry("svcloud", ["mcp"]);
+  // Resolved, never assumed: a config that says `svcloud` on a machine
+  // where `svcloud` is not on PATH produces a harness that silently has no
+  // SV Cloud tools at all. See lib/self.ts.
+  const bridge = bridgeCommand();
+  const env = inheritedEnv();
+  const entry = harness.buildEntry(bridge.command, bridge.args, env);
 
   if (existing !== undefined && !force) {
     if (harness.isWellFormed(existing)) {
-      if (json) {
-        console.log(JSON.stringify({ harness: harness.id, path, status: "already_configured" }));
-      } else {
-        console.log(`${harness.label} is already configured at ${path}.`);
+      // A well-formed entry pointed at a DIFFERENT deployment than this
+      // shell is not "already configured" — reporting it as such is how an
+      // agent ends up silently talking to production from a staging setup,
+      // and the reverse. Shape matches, so this is a correction of one
+      // value rather than the overwrite `--force` guards, and it falls
+      // through to the write below.
+      const desired = env?.SVCLOUD_API_URL;
+      if (readEntryApiUrl(existing) === desired) {
+        if (json) {
+          console.log(JSON.stringify({ harness: harness.id, path, status: "already_configured" }));
+        } else {
+          console.log(`${harness.label} is already configured at ${path}.`);
+        }
+        return;
       }
-      return;
+    } else {
+      die(
+        `${path} already has a "svcloud" entry under "${harness.serversKey}", but it doesn't look right for ${harness.label}.\n` +
+          `Rerun with --force to overwrite it.`,
+      );
     }
-    die(
-      `${path} already has a "svcloud" entry under "${harness.serversKey}", but it doesn't look right for ${harness.label}.\n` +
-        `Rerun with --force to overwrite it.`,
-    );
   }
 
   servers.svcloud = entry;
@@ -77,10 +118,33 @@ export async function mcpSetupCommand(argv: string[], json: boolean): Promise<vo
   await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, "utf8");
 
   if (json) {
-    console.log(JSON.stringify({ harness: harness.id, path, status: "written" }));
+    console.log(
+      JSON.stringify({
+        harness: harness.id,
+        path,
+        status: "written",
+        command: bridge.command,
+        args: bridge.args,
+        svcloud_on_path: bridge.onPath,
+        // Only when there is something to say: production writes no
+        // environment block, and reporting a key for it would imply one.
+        ...(env ? { api_url: env.SVCLOUD_API_URL } : {}),
+      }),
+    );
     return;
   }
   console.log(`Wrote ${harness.label}'s MCP config to ${path}.`);
+  if (env) {
+    console.log(`This entry points the bridge at ${env.SVCLOUD_API_URL}.`);
+  }
+  if (!bridge.onPath) {
+    console.log("");
+    console.log(
+      "Note: the config uses this install's absolute path, so your harness will find it either way.",
+    );
+    console.log(pathHint());
+    console.log("");
+  }
   console.log(`Sign in first if you haven't: svcloud login`);
   console.log(`Then restart ${harness.label} (or start a new session) to pick it up.`);
 }

package/src/commands/storage.ts

@@ -0,0 +1,108 @@
+/**
+ * `svcloud storage` — direct URLs into an app's file storage.
+ *
+ * Only presigning, deliberately. `svcloud storage put` and `get` would put the
+ * CLI in the data path for a file that may be gigabytes, which is the exact
+ * cost presigned URLs exist to avoid; the URL this hands back works with curl,
+ * a browser, or anything else, and moves bytes straight between the caller and
+ * storage.
+ *
+ * A GET URL is a shareable download link for as long as it lives. The server
+ * caps that lifetime and reports what it actually granted, which may be less
+ * than was asked for — so `expires_in` in the output is the truth, not the
+ * `--expires-in` flag.
+ */
+import { statSync } from "node:fs";
+import { apiFetch } from "../lib/api";
+import { findProjectBySlug } from "../lib/find-project";
+import { die, printJson } from "../lib/output";
+
+const USAGE = `Usage:
+  svcloud storage presign <app> <key> [--method GET|PUT] [--expires-in <seconds>]
+                                      [--size <bytes> | --file <path>] [--content-type <type>]
+
+  --method       GET (default) for a download or share link, PUT to upload.
+  --size         Required for PUT. Signed into the URL, so an upload of any
+                 other size is refused.
+  --file         Read the size from a local file instead of passing --size.
+  --expires-in   Seconds. Capped by the server; the output reports what was granted.`;
+
+interface PresignResponse {
+  project_id: string;
+  key: string;
+  method: string;
+  url: string;
+  expires_in: number;
+}
+
+function flagValue(argv: string[], name: string): string | undefined {
+  const index = argv.indexOf(name);
+  if (index === -1) return undefined;
+  const value = argv[index + 1];
+  if (value === undefined || value.startsWith("--")) die(`${name} needs a value.\n\n${USAGE}`);
+  return value;
+}
+
+export async function storageCommand(argv: string[], json: boolean): Promise<void> {
+  const [subcommand, ...rest] = argv;
+  if (subcommand !== "presign") die(USAGE);
+
+  const [slug, key] = rest;
+  if (!slug || !key) die(USAGE);
+
+  const project = await findProjectBySlug(slug);
+  if (!project) die(`No app named "${slug}".`);
+
+  const method = (flagValue(rest, "--method") ?? "GET").toUpperCase();
+  if (method !== "GET" && method !== "PUT") die(`--method must be GET or PUT.\n\n${USAGE}`);
+
+  const body: Record<string, unknown> = { key, method };
+
+  const expiresIn = flagValue(rest, "--expires-in");
+  if (expiresIn !== undefined) {
+    const seconds = Number(expiresIn);
+    if (!Number.isInteger(seconds) || seconds <= 0) die("--expires-in must be a whole number of seconds.");
+    body.expires_in = seconds;
+  }
+
+  const contentType = flagValue(rest, "--content-type");
+  if (contentType) body.content_type = contentType;
+
+  if (method === "PUT") {
+    const size = flagValue(rest, "--size");
+    const file = flagValue(rest, "--file");
+    if (size !== undefined && file !== undefined) die("Pass --size or --file, not both.");
+    if (size !== undefined) {
+      const bytes = Number(size);
+      if (!Number.isInteger(bytes) || bytes < 0) die("--size must be a whole number of bytes.");
+      body.content_length = bytes;
+    } else if (file !== undefined) {
+      try {
+        body.content_length = statSync(file).size;
+      } catch {
+        die(`Could not read "${file}".`);
+      }
+    } else {
+      die(`A PUT needs --size or --file: the size is signed into the URL.\n\n${USAGE}`);
+    }
+  }
+
+  const result = await apiFetch<PresignResponse>(
+    `/api/v1/projects/${project.id}/storage/presign`,
+    { method: "POST", body: JSON.stringify(body) },
+  );
+
+  if (json) {
+    printJson(result);
+    return;
+  }
+
+  console.log(result.url);
+  console.error("");
+  console.error(`${result.method} ${result.key} — valid for ${result.expires_in}s.`);
+  if (result.method === "GET") {
+    console.error("Anybody with this link can download the file until it expires.");
+  } else {
+    console.error(`Upload with: curl -X PUT --upload-file <file> "<url>"`);
+  }
+}

package/src/index.ts

@@ -5,6 +5,7 @@
  * few that need subcommands (`secrets`, `db`, `mcp`) do their own
  * second-level switch — no subcommand ambiguity worth a parser library yet.
  */
+import { bundleCommand } from "./commands/bundle";
 import { dbCommand } from "./commands/db";
 import { deployCommand } from "./commands/deploy";
 import { initCommand } from "./commands/init";
@@ -15,6 +16,7 @@ import { openCommand } from "./commands/open";
 import { projectsCommand } from "./commands/projects";
 import { runsCommand } from "./commands/runs";
 import { secretsCommand } from "./commands/secrets";
+import { storageCommand } from "./commands/storage";
 import { statusCommand } from "./commands/status";
 import { whoamiCommand } from "./commands/whoami";
 import { AuthRequiredError, ApiError } from "./lib/api";
@@ -33,8 +35,10 @@ Usage:
   svcloud init                  Connect a local repo as a new app
   svcloud runs <app>            Show or watch an app's provisioning run
   svcloud secrets <cmd>         Manage an app's keys & settings (list/set/remove)
+  svcloud storage presign       Get a direct URL for one file in an app's storage
   svcloud db <cmd>              Browse and edit an app's database (see 'svcloud db' for subcommands)
   svcloud deploy <app>          Push the current branch and watch the build (must be the app's default branch)
+  svcloud bundle <cmd>          Keep an app's starter current (status/update/done)
   svcloud mcp                   Run the local MCP bridge (for a coding agent's harness config)
   svcloud mcp setup <harness>   Write a coding agent harness's MCP config for svcloud
   svcloud mcp check             Diagnose sign-in state, harness configs, and live tool visibility
@@ -69,6 +73,9 @@ async function main(): Promise<void> {
     case "logout":
       await logoutCommand();
       return;
+    case "bundle":
+      await bundleCommand(rest, json);
+      return;
     case "whoami":
       await whoamiCommand(json);
       return;
@@ -93,6 +100,9 @@ async function main(): Promise<void> {
     case "secrets":
       await secretsCommand(rest, json);
       return;
+    case "storage":
+      await storageCommand(rest, json);
+      return;
     case "db":
       await dbCommand(rest, json);
       return;

package/src/lib/api.ts

@@ -169,8 +169,28 @@ export async function apiFetch<T>(path: string, options: ApiFetchOptions = {}):
       // A non-JSON error body (e.g. a 502 in front of the Worker) still surfaces as a plain ApiError below.
     }
     if (res.status === 401 && !options.unauthenticated) {
-      await clearTokens();
-      throw new AuthRequiredError();
+      // Deliberately NOT clearTokens(). Reaching here means the forced
+      // refresh above SUCCEEDED — cloud-api accepted this session's refresh
+      // token — and then rejected the access token it had just minted. A
+      // live grant is not a dead session, so destroying the stored tokens is
+      // the wrong response: the likely causes are a token held against a
+      // DIFFERENT deployment than the one being called, or a transient
+      // server-side rejection, and neither is fixed by making the user sign
+      // in again from scratch. `refreshRequest` already clears the store on
+      // the one signal that does mean the grant is gone (the refresh itself
+      // being refused), and that stays the only path that wipes it.
+      //
+      // The hint names SVCLOUD_API_URL only when it is actually set: staging
+      // is ours, and a real user must never be pointed at a variable that
+      // plays no part in their setup.
+      const misdirected = process.env.SVCLOUD_API_URL
+        ? ` The CLI is pointed at ${apiBaseUrl()} — check SVCLOUD_API_URL if that is not what you meant.`
+        : "";
+      throw new ApiError(
+        `Signed in, but ${apiBaseUrl()} rejected this session.${misdirected} Run \`svcloud login\` to sign in against it.`,
+        envelope?.error.code ?? "unauthenticated",
+        401,
+      );
     }
     throw new ApiError(
       envelope?.error.message ?? `Request failed (${res.status}).`,

package/src/lib/config.ts

@@ -1,19 +1,74 @@
 /**
  * Constants shared by every command. `SVCLOUD_API_URL` is the one env
- * override, for pointing the CLI at a local `wrangler dev` instance while
- * building it — production has no reason to ever set it.
+ * override, for pointing the CLI at a deployment that is not production — a
+ * local `wrangler dev` instance while building it, or our own staging
+ * environment. It is deliberately NOT a flag: staging is ours, not the
+ * product's, so it appears in no `--help` output and no README, and a real
+ * user's CLI behaves as though it does not exist.
  */
 import { createRequire } from "node:module";
 
 export const CLIENT_ID = "svcloud-cli";
 
+/** Service/account names the credential store (lib/credentials.ts) files this CLI's token set under. */
+export const CREDENTIAL_SERVICE = "svcloud-cli";
+
+export const PRODUCTION_API_URL = "https://api.cloud.sv-academy.org";
+
+/**
+ * The API this process talks to, normalized.
+ *
+ * Normalizing rather than returning the raw string is load-bearing: the value
+ * is interpolated straight into `fetch()` (`lib/api.ts`) and parsed by
+ * `credentialAccount()` below, and a host with no scheme — the shape a person
+ * naturally types — produces `TypeError: Failed to parse URL from
+ * api.cloud-staging.sv-academy.org/api/v1/...` several frames from the actual
+ * mistake. So a scheme-less value gets `https://`, and anything still
+ * unusable after that throws a sentence naming the variable instead of
+ * surfacing as a URL parser error.
+ *
+ * Failing loudly here also closes a real footgun in `credentialAccount()`: it
+ * used to fall back to the production slot for a value it could not parse,
+ * which is the one slot a non-production token must never land in.
+ */
 export function apiBaseUrl(): string {
-  return process.env.SVCLOUD_API_URL ?? "https://api.cloud.sv-academy.org";
+  const raw = process.env.SVCLOUD_API_URL?.trim();
+  if (!raw) return PRODUCTION_API_URL;
+
+  const candidate = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(raw) ? raw : `https://${raw}`;
+  let url: URL;
+  try {
+    url = new URL(candidate);
+  } catch {
+    throw new Error(`SVCLOUD_API_URL is not a valid URL: ${raw}`);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new Error(`SVCLOUD_API_URL must be an http(s) URL: ${raw}`);
+  }
+  if (!url.host) throw new Error(`SVCLOUD_API_URL has no host: ${raw}`);
+
+  // Every caller appends a path beginning with "/", so the base must not end
+  // with one — `${base}${path}` would otherwise produce a double slash.
+  return `${url.origin}${url.pathname.replace(/\/+$/, "")}`;
 }
 
-/** Service/account names the credential store (lib/credentials.ts) files this CLI's token set under. */
-export const CREDENTIAL_SERVICE = "svcloud-cli";
-export const CREDENTIAL_ACCOUNT = "default";
+/**
+ * The credential-store slot this CLI's token set lives in, keyed by which API
+ * it belongs to. Production keeps the literal "default" it has always used,
+ * so no existing login is invalidated; anything else (a staging deployment, a
+ * local `wrangler dev`) gets its own slot named for the host.
+ *
+ * Without this, `SVCLOUD_API_URL=… svcloud login` silently OVERWRITES the
+ * production token — same service, same account, one entry — and the next
+ * plain `svcloud` command runs against production with a token minted by a
+ * different environment, which fails in a way that looks like a session
+ * expiry rather than a footgun.
+ */
+export function credentialAccount(): string {
+  const url = apiBaseUrl();
+  if (url === PRODUCTION_API_URL) return "default";
+  return new URL(url).host;
+}
 
 /** This installed CLI's own version, from package.json — surfaced by `svcloud mcp check`. */
 export const CLI_VERSION: string = createRequire(import.meta.url)("../../package.json").version;

package/src/lib/credentials.ts

@@ -28,7 +28,7 @@ import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { promisify } from "node:util";
-import { CREDENTIAL_ACCOUNT, CREDENTIAL_SERVICE } from "./config";
+import { credentialAccount, CREDENTIAL_SERVICE } from "./config";
 
 const run = promisify(execFile);
 
@@ -41,7 +41,21 @@ export interface TokenSet {
 }
 
 const FALLBACK_DIR = join(homedir(), ".config", "svcloud");
-const FALLBACK_FILE = join(FALLBACK_DIR, "credentials.json");
+
+/**
+ * Every store below is keyed by `credentialAccount()`, not by a constant, so
+ * a token minted against one API never lands in another's slot — see that
+ * function's header. Resolved per call rather than at import: the CLI reads
+ * `SVCLOUD_API_URL` from the environment, which a test (and a user) can
+ * change between calls in one process.
+ */
+function fallbackFile(): string {
+  const account = credentialAccount();
+  return join(
+    FALLBACK_DIR,
+    account === "default" ? "credentials.json" : `credentials-${account}.json`,
+  );
+}
 
 async function macosSave(json: string): Promise<void> {
   // -U: update in place if an entry already exists, so a re-login doesn't
@@ -49,7 +63,7 @@ async function macosSave(json: string): Promise<void> {
   await run("security", [
     "add-generic-password",
     "-a",
-    CREDENTIAL_ACCOUNT,
+    credentialAccount(),
     "-s",
     CREDENTIAL_SERVICE,
     "-w",
@@ -63,7 +77,7 @@ async function macosLoad(): Promise<string | undefined> {
     const { stdout } = await run("security", [
       "find-generic-password",
       "-a",
-      CREDENTIAL_ACCOUNT,
+      credentialAccount(),
       "-s",
       CREDENTIAL_SERVICE,
       "-w",
@@ -78,7 +92,7 @@ async function macosClear(): Promise<void> {
   await run("security", [
     "delete-generic-password",
     "-a",
-    CREDENTIAL_ACCOUNT,
+    credentialAccount(),
     "-s",
     CREDENTIAL_SERVICE,
   ]).catch(() => {
@@ -96,7 +110,7 @@ async function linuxSave(json: string): Promise<void> {
     "service",
     CREDENTIAL_SERVICE,
     "account",
-    CREDENTIAL_ACCOUNT,
+    credentialAccount(),
   ]);
   pending.child.stdin?.end(json);
   await pending;
@@ -109,7 +123,7 @@ async function linuxLoad(): Promise<string | undefined> {
       "service",
       CREDENTIAL_SERVICE,
       "account",
-      CREDENTIAL_ACCOUNT,
+      credentialAccount(),
     ]);
     return stdout.replace(/\n$/, "") || undefined;
   } catch {
@@ -123,7 +137,7 @@ async function linuxClear(): Promise<void> {
     "service",
     CREDENTIAL_SERVICE,
     "account",
-    CREDENTIAL_ACCOUNT,
+    credentialAccount(),
   ]).catch(() => {});
 }
 
@@ -135,7 +149,9 @@ async function linuxClear(): Promise<void> {
  * macOS); any failure here falls back to the plaintext file below rather
  * than surfacing a build-only error to a novice.
  */
-const PS_TARGET = `${CREDENTIAL_SERVICE}/${CREDENTIAL_ACCOUNT}`;
+function psTarget(): string {
+  return `${CREDENTIAL_SERVICE}/${credentialAccount()}`;
+}
 
 const PS_PROLOGUE = `
 Add-Type -Namespace SvCloud -Name Cred -MemberDefinition @'
@@ -164,8 +180,8 @@ $bytes = [Convert]::FromBase64String("${bytes.toString("base64")}")
 $blob = [Runtime.InteropServices.Marshal]::AllocHGlobal($bytes.Length)
 [Runtime.InteropServices.Marshal]::Copy($bytes, 0, $blob, $bytes.Length)
 $cred = New-Object SvCloud.Cred+CREDENTIAL
-$cred.Type = 1; $cred.TargetName = "${PS_TARGET}"; $cred.CredentialBlobSize = $bytes.Length
-$cred.CredentialBlob = $blob; $cred.Persist = 2; $cred.UserName = "${CREDENTIAL_ACCOUNT}"
+$cred.Type = 1; $cred.TargetName = "${psTarget()}"; $cred.CredentialBlobSize = $bytes.Length
+$cred.CredentialBlob = $blob; $cred.Persist = 2; $cred.UserName = "${credentialAccount()}"
 if (-not [SvCloud.Cred]::CredWrite([ref]$cred, 0)) { throw "CredWrite failed" }
 [Runtime.InteropServices.Marshal]::FreeHGlobal($blob)`;
   await run("powershell", ["-NoProfile", "-NonInteractive", "-Command", script]);
@@ -174,7 +190,7 @@ if (-not [SvCloud.Cred]::CredWrite([ref]$cred, 0)) { throw "CredWrite failed" }
 async function windowsLoad(): Promise<string | undefined> {
   const script = `${PS_PROLOGUE}
 $ptr = [IntPtr]::Zero
-if (-not [SvCloud.Cred]::CredRead("${PS_TARGET}", 1, 0, [ref]$ptr)) { exit 1 }
+if (-not [SvCloud.Cred]::CredRead("${psTarget()}", 1, 0, [ref]$ptr)) { exit 1 }
 $cred = [Runtime.InteropServices.Marshal]::PtrToStructure($ptr, [Type][SvCloud.Cred+CREDENTIAL])
 $bytes = New-Object byte[] $cred.CredentialBlobSize
 [Runtime.InteropServices.Marshal]::Copy($cred.CredentialBlob, $bytes, 0, $cred.CredentialBlobSize)
@@ -190,15 +206,15 @@ $bytes = New-Object byte[] $cred.CredentialBlobSize
 }
 
 async function windowsClear(): Promise<void> {
-  const script = `${PS_PROLOGUE}[SvCloud.Cred]::CredDelete("${PS_TARGET}", 1, 0) | Out-Null`;
+  const script = `${PS_PROLOGUE}[SvCloud.Cred]::CredDelete("${psTarget()}", 1, 0) | Out-Null`;
   await run("powershell", ["-NoProfile", "-NonInteractive", "-Command", script]).catch(() => {});
 }
 
 async function fallbackSave(json: string): Promise<void> {
   await mkdir(FALLBACK_DIR, { recursive: true, mode: 0o700 });
-  await writeFile(FALLBACK_FILE, json, { mode: 0o600 });
+  await writeFile(fallbackFile(), json, { mode: 0o600 });
   console.error(
-    `Note: your SV Cloud sign-in is stored in plain text at ${FALLBACK_FILE} ` +
+    `Note: your SV Cloud sign-in is stored in plain text at ${fallbackFile()} ` +
       "because no system keychain was available. Anyone who can read that " +
       "file can act as you until you run `svcloud logout`.",
   );
@@ -206,14 +222,14 @@ async function fallbackSave(json: string): Promise<void> {
 
 async function fallbackLoad(): Promise<string | undefined> {
   try {
-    return await readFile(FALLBACK_FILE, "utf-8");
+    return await readFile(fallbackFile(), "utf-8");
   } catch {
     return undefined;
   }
 }
 
 async function fallbackClear(): Promise<void> {
-  await rm(FALLBACK_FILE, { force: true });
+  await rm(fallbackFile(), { force: true });
 }
 
 async function platformSave(json: string): Promise<boolean> {

package/src/lib/harnesses.ts

@@ -14,6 +14,14 @@
  * Codex's entry is carried over from the README as it stood before this
  * change (`~/.codex/config.json`, `mcpServers`) — not independently
  * re-verified here; only OpenCode's shape was reported wrong.
+ *
+ * `buildEntry` takes the command and args rather than hardcoding
+ * `"svcloud" ["mcp"]`, because what is spawnable depends on the machine:
+ * `lib/self.ts` resolves the bare name against PATH and falls back to this
+ * install's own absolute paths when it does not resolve. `isWellFormed`
+ * deliberately does NOT check the command's value, only its shape — an
+ * absolute-path entry a previous `mcp setup` wrote is correct, and so is a
+ * bare-name one somebody wrote by hand.
  */
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -25,6 +33,10 @@ export interface HarnessEntry {
   command: string | string[];
   args?: string[];
   type?: string;
+  /** Claude-style harnesses. Present only when there are variables to pass. */
+  env?: Record<string, string>;
+  /** OpenCode's spelling of the same thing — verified against opencode.ai/docs/mcp-servers/. */
+  environment?: Record<string, string>;
 }
 
 export interface Harness {
@@ -35,8 +47,13 @@ export interface Harness {
   configPath: (cwd: string) => string;
   /** The top-level object key an entry for svcloud lives under. */
   serversKey: string;
-  /** Build this harness's shape of the svcloud server entry. */
-  buildEntry: (command: string, args: string[]) => HarnessEntry;
+  /**
+   * Build this harness's shape of the svcloud server entry. `env` is omitted
+   * far more often than not — see `mcp-setup.ts`'s `inheritedEnv` — and when
+   * it is, the entry written must be byte-identical to what this table
+   * produced before environment passthrough existed.
+   */
+  buildEntry: (command: string, args: string[], env?: Record<string, string>) => HarnessEntry;
   /** True if an existing entry (already parsed as JSON) has this harness's expected shape. */
   isWellFormed: (entry: unknown) => boolean;
 }
@@ -45,7 +62,11 @@ function isStringArray(v: unknown): v is string[] {
   return Array.isArray(v) && v.every((x) => typeof x === "string");
 }
 
-const claudeStyleEntry = (command: string, args: string[]): HarnessEntry => ({ command, args });
+const claudeStyleEntry = (
+  command: string,
+  args: string[],
+  env?: Record<string, string>,
+): HarnessEntry => ({ command, args, ...(env ? { env } : {}) });
 const claudeStyleWellFormed = (entry: unknown): boolean =>
   typeof entry === "object" &&
   entry !== null &&
@@ -104,7 +125,15 @@ export const HARNESSES: Harness[] = [
     scope: "global",
     configPath: () => join(homedir(), ".config", "opencode", "opencode.json"),
     serversKey: "mcp",
-    buildEntry: (command, args) => ({ type: "local", command: [command, ...args] }),
+    // OpenCode spells the environment block `environment`, not `env` — the
+    // one shape difference in this table, verified against
+    // https://opencode.ai/docs/mcp-servers/ the same way its file path and
+    // `mcp` key were.
+    buildEntry: (command, args, env) => ({
+      type: "local",
+      command: [command, ...args],
+      ...(env ? { environment: env } : {}),
+    }),
     isWellFormed: (entry: unknown): boolean =>
       typeof entry === "object" &&
       entry !== null &&
@@ -118,12 +147,42 @@ export function findHarness(id: string): Harness | undefined {
   return HARNESSES.find((h) => h.id === id);
 }
 
+/**
+ * The API deployment an already-written entry spawns the bridge against, or
+ * undefined for the default (production). Reads both spellings of the
+ * environment block, so one caller covers the whole table.
+ *
+ * Kept out of `isWellFormed`, which checks an entry's SHAPE and deliberately
+ * not its values (see this file's header): an entry naming a different
+ * deployment is well-formed, it is just pointed somewhere else, and telling
+ * those two cases apart is what lets `mcp setup` correct the second without
+ * demanding `--force` for the first.
+ */
+export function readEntryApiUrl(entry: unknown): string | undefined {
+  if (typeof entry !== "object" || entry === null) return undefined;
+  const record = entry as Record<string, unknown>;
+  for (const key of ["env", "environment"]) {
+    const block = record[key];
+    if (typeof block !== "object" || block === null) continue;
+    const value = (block as Record<string, unknown>).SVCLOUD_API_URL;
+    if (typeof value === "string" && value) return value;
+  }
+  return undefined;
+}
+
 export type HarnessStatus =
   | { state: "not_found"; path: string }
   | { state: "unreadable"; path: string; detail: string }
   | { state: "missing_entry"; path: string }
   | { state: "wrong_shape"; path: string }
-  | { state: "ok"; path: string };
+  /**
+   * `apiUrl` is the deployment the recorded entry spawns the bridge against,
+   * undefined meaning the default (production). Carried on the status so
+   * `mcp check` can report an entry that is correctly shaped but pointed
+   * somewhere other than the shell doing the checking — the one failure this
+   * command exists to make visible that shape alone cannot show.
+   */
+  | { state: "ok"; path: string; apiUrl?: string };
 
 /** Reads and inspects a harness's config file — never throws. */
 export async function inspectHarness(harness: Harness, cwd: string): Promise<HarnessStatus> {
@@ -144,5 +203,5 @@ export async function inspectHarness(harness: Harness, cwd: string): Promise<Har
   const entry = (servers as Record<string, unknown> | undefined)?.svcloud;
   if (entry === undefined) return { state: "missing_entry", path };
   if (!harness.isWellFormed(entry)) return { state: "wrong_shape", path };
-  return { state: "ok", path };
+  return { state: "ok", path, apiUrl: readEntryApiUrl(entry) };
 }

package/src/lib/self.ts

@@ -0,0 +1,88 @@
+/**
+ * How to spawn THIS CLI again, from a config file another program reads.
+ *
+ * `svcloud mcp setup` writes a harness config whose `command` is whatever
+ * that harness will later exec. Writing the bare name `svcloud` is right
+ * whenever the npm global bin directory is on PATH, and silently useless
+ * whenever it is not: the harness spawns, fails with ENOENT, and shows the
+ * owner an MCP server that is simply never there. That was a real report
+ * (2026-09-05) from someone who had run `npm install -g svcloud`
+ * successfully and still had to invoke `npx svcloud` for everything,
+ * because their shell's PATH did not include `$(npm prefix -g)/bin`.
+ *
+ * So the command is resolved rather than assumed. If a `svcloud`
+ * executable is genuinely reachable on PATH, that is what gets written —
+ * it survives a CLI upgrade that moves the install directory. If it is
+ * not, the config gets this process's own absolute paths instead, which
+ * works no matter what the harness's PATH looks like. Node's own binary is
+ * used rather than the npm shim: the shim's exec bit and its `.cmd`
+ * wrapper on Windows are two more things that can be wrong, and
+ * `process.execPath` is neither.
+ */
+import { accessSync, constants } from "node:fs";
+import { delimiter, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** `bin/svcloud.js` in this installed package, absolute. */
+export function ownBinPath(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return join(here, "..", "..", "bin", "svcloud.js");
+}
+
+/**
+ * Whether a bare `svcloud` resolves to an executable on this PATH.
+ *
+ * Deliberately not `which`/`where`: spawning a shell to answer a question
+ * about the environment we are already in is slower and less predictable
+ * than reading PATH ourselves. On Windows a bare name is resolved against
+ * PATHEXT, so the shim's real filename there is `svcloud.cmd`.
+ */
+export function isOnPath(name = "svcloud", env: NodeJS.ProcessEnv = process.env): boolean {
+  const raw = env.PATH ?? env.Path ?? "";
+  if (!raw) return false;
+  const suffixes = process.platform === "win32" ? [".cmd", ".exe", ".bat", ""] : [""];
+  for (const dir of raw.split(delimiter)) {
+    if (!dir) continue;
+    for (const suffix of suffixes) {
+      try {
+        accessSync(join(dir, `${name}${suffix}`), constants.X_OK);
+        return true;
+      } catch {
+        /* Not here; keep looking. */
+      }
+    }
+  }
+  return false;
+}
+
+export interface BridgeCommand {
+  command: string;
+  args: string[];
+  /** True when the bare name resolved, so the config is portable. */
+  onPath: boolean;
+}
+
+/** The `command` + `args` a harness config should use to run `svcloud mcp`. */
+export function bridgeCommand(): BridgeCommand {
+  if (isOnPath()) return { command: "svcloud", args: ["mcp"], onPath: true };
+  return { command: process.execPath, args: [ownBinPath(), "mcp"], onPath: false };
+}
+
+/**
+ * What to tell somebody whose npm global bin is not on PATH.
+ *
+ * The directory is derived from where this file actually is rather than
+ * from `npm prefix -g`, so the sentence names the path that would really
+ * work for this install, including inside a version manager's per-version
+ * prefix.
+ */
+export function pathHint(): string {
+  const binDir = dirname(ownBinPath());
+  return (
+    `\`svcloud\` is not on your PATH, so your shell can only reach it through \`npx\`.\n` +
+    `Add it with:\n` +
+    `  echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc\n` +
+    `(use ~/.bashrc on Linux). This install's own binary is at:\n` +
+    `  ${join(binDir, "svcloud.js")}`
+  );
+}