@mesh-tech/mesh-cli 0.20.4 → 0.22.0

package/dist/bin/mesh.js

@@ -838,6 +838,7 @@ var init_seed = __esm({
 
 // libs/mesh-cli/src/commands/local/helpers.ts
 import * as net from "net";
+import { execFileSync as execFileSync3 } from "child_process";
 async function upsertLocalSecret(secretId, value, client) {
   const { SecretsManagerClient: SecretsManagerClient10, CreateSecretCommand: CreateSecretCommand4, PutSecretValueCommand: PutSecretValueCommand4 } = await import("@aws-sdk/client-secrets-manager");
   const sm = client ?? new SecretsManagerClient10(LOCAL_AWS_CONFIG);
@@ -867,10 +868,91 @@ function probeTcp(port, opts = {}) {
     });
   });
 }
+function hostPortsOf(endpoints) {
+  const ports = /* @__PURE__ */ new Set();
+  const fromUrl = (raw) => {
+    try {
+      const u = new URL(raw.includes("://") ? raw : `tcp://${raw}`);
+      const port = Number(u.port || (u.protocol === "https:" ? 443 : u.protocol === "http:" ? 80 : NaN));
+      if (Number.isInteger(port) && port > 0) ports.add(port);
+    } catch {
+    }
+  };
+  for (const e of endpoints) {
+    if (e.probe.kind === "tcp") ports.add(e.probe.port);
+    else if (e.probe.kind === "http") fromUrl(e.probe.url);
+    fromUrl(e.url);
+  }
+  return [...ports].sort((a, b) => a - b);
+}
+function parseDockerPsPorts(output, ignorePrefix) {
+  const held = /* @__PURE__ */ new Map();
+  for (const line of output.split("\n")) {
+    const tab = line.indexOf("	");
+    if (tab < 0) continue;
+    const name = line.slice(0, tab).trim();
+    if (!name || name.startsWith(ignorePrefix)) continue;
+    for (const m of line.slice(tab + 1).matchAll(/:(\d+)->\d+\/(?:tcp|udp)/g)) {
+      const port = Number(m[1]);
+      if (!held.has(port)) held.set(port, name);
+    }
+  }
+  return held;
+}
+async function findPortConflicts(ports, ignorePrefix, io = defaultPortConflictIo) {
+  const unique = [...new Set(ports)].sort((a, b) => a - b);
+  const bound = (await Promise.all(unique.map(async (port) => await io.listening(port) ? port : null))).filter(
+    (p) => p !== null
+  );
+  if (bound.length === 0) return [];
+  const containers = parseDockerPsPorts(io.dockerPs(), ignorePrefix);
+  return bound.map((port) => {
+    const container = containers.get(port);
+    if (container) return { port, holder: { kind: "container", name: container } };
+    const process2 = io.processOn(port);
+    return { port, holder: process2 ? { kind: "process", name: process2 } : null };
+  });
+}
+function describePortConflicts(conflicts, moveHints = /* @__PURE__ */ new Map()) {
+  const lines = conflicts.flatMap(({ port, holder }) => {
+    const remedy = holder?.kind === "container" ? `docker stop ${holder.name}` : `lsof -nP -iTCP:${port} -sTCP:LISTEN, then stop what it names`;
+    const what = holder ? `held by ${holder.kind} ${holder.name}` : "held by something lsof would not name";
+    const move = moveHints.get(port);
+    return move ? [`  ${String(port).padEnd(5)} ${what.padEnd(38)} (${remedy})`, `  ${"".padEnd(5)} or: ${move}`] : [`  ${String(port).padEnd(5)} ${what.padEnd(38)} (${remedy})`];
+  });
+  return `Cannot start the local platform \u2014 ${conflicts.length === 1 ? "a host port it needs is" : "host ports it needs are"} already in use:
+` + lines.join("\n") + '\nStop what holds the port (or move it), then run mesh start again. A port lost this way does not fail as "port in use": the container never joins the network and a later service reports an unrelated error.\nIf the port is held by something you cannot stop and the stack can live without it: mesh start --skip-port-check';
+}
+var defaultPortConflictIo;
 var init_helpers = __esm({
   "libs/mesh-cli/src/commands/local/helpers.ts"() {
     "use strict";
     init_seed();
+    defaultPortConflictIo = {
+      dockerPs: () => {
+        try {
+          return execFileSync3("docker", ["ps", "--format", "{{.Names}}	{{.Ports}}"], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"]
+          });
+        } catch {
+          return "";
+        }
+      },
+      processOn: (port) => {
+        try {
+          const out = execFileSync3("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-Fc"], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"]
+          });
+          const cmd = out.split("\n").find((l) => l.startsWith("c"));
+          return cmd ? cmd.slice(1) : null;
+        } catch {
+          return null;
+        }
+      },
+      listening: (port) => probeTcp(port, { timeoutMs: 300 })
+    };
   }
 });
 
@@ -922,7 +1004,7 @@ __export(stack_exports, {
   summarizeComposeFailure: () => summarizeComposeFailure,
   writeAppServiceProbes: () => writeAppServiceProbes
 });
-import { execFileSync as execFileSync3, spawn, spawnSync } from "child_process";
+import { execFileSync as execFileSync4, spawn, spawnSync } from "child_process";
 import * as fs4 from "fs";
 import * as path4 from "path";
 import { fileURLToPath } from "url";
@@ -1028,7 +1110,7 @@ function stackOwnedElsewhere() {
   try {
     const first = compose(["ps", "-q"]).trim().split("\n").filter(Boolean)[0];
     if (!first) return void 0;
-    const label = execFileSync3(
+    const label = execFileSync4(
       "docker",
       ["inspect", first, "--format", '{{ index .Config.Labels "com.docker.compose.project.working_dir" }}'],
       { encoding: "utf-8" }
@@ -1061,7 +1143,7 @@ function compose(args, opts = {}) {
   const files = ["-f", path4.join(dir, "docker-compose.yml")];
   if (opts.hub) files.push("-f", path4.join(dir, "docker-compose.hub.yml"));
   const fullArgs = ["compose", "-p", COMPOSE_PROJECT, ...files, ...args];
-  return execFileSync3("docker", fullArgs, {
+  return execFileSync4("docker", fullArgs, {
     cwd: dir,
     encoding: "utf-8",
     // MESH_LOCAL_LOGS on every call: the compose file mounts it into the
@@ -1320,10 +1402,10 @@ var init_stack = __esm({
 // libs/mesh-cli/src/commands/skills.ts
 import * as fs5 from "fs";
 import * as path5 from "path";
-import { execFileSync as execFileSync4 } from "child_process";
+import { execFileSync as execFileSync5 } from "child_process";
 function resolveTargetRoot(startDir = process.cwd()) {
   try {
-    return execFileSync4("git", ["rev-parse", "--show-toplevel"], {
+    return execFileSync5("git", ["rev-parse", "--show-toplevel"], {
       cwd: startDir,
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "pipe"]
@@ -1686,7 +1768,7 @@ var init_pid = __esm({
 });
 
 // libs/mesh-cli/src/utils/tailscale-targets.ts
-import { execFileSync as execFileSync5 } from "node:child_process";
+import { execFileSync as execFileSync6 } from "node:child_process";
 import * as fs6 from "node:fs";
 import * as path6 from "node:path";
 function tenantPortIndex(tenant, registryPath) {
@@ -1723,7 +1805,7 @@ function resolveTunnelTargets(services, resolveIp, portOffset = 0) {
 }
 function resolveElbIp(host) {
   try {
-    const out = execFileSync5("dig", ["+short", host, "@1.1.1.1"], {
+    const out = execFileSync6("dig", ["+short", host, "@1.1.1.1"], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"]
     });
@@ -1830,7 +1912,7 @@ import * as crypto from "node:crypto";
 import * as fs7 from "node:fs";
 import * as net3 from "node:net";
 import * as path7 from "node:path";
-import { execFileSync as execFileSync6 } from "node:child_process";
+import { execFileSync as execFileSync7 } from "node:child_process";
 function mintRunnerToken() {
   return crypto.randomBytes(16).toString("hex");
 }
@@ -1855,7 +1937,7 @@ function clearRunnerManifest(file, token) {
 }
 function getProcessGroupId(pid) {
   try {
-    const out = execFileSync6("ps", ["-o", "pgid=", "-p", String(pid)], {
+    const out = execFileSync7("ps", ["-o", "pgid=", "-p", String(pid)], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"]
     }).trim();
@@ -1881,7 +1963,7 @@ function parseRunnerPidsFromPs(psOutput, tenant, exclude) {
 }
 function discoverRunnerPids(tenant, exclude) {
   try {
-    const out = execFileSync6("ps", ["ax", "-o", "pid=,command="], {
+    const out = execFileSync7("ps", ["ax", "-o", "pid=,command="], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"]
     });
@@ -1973,7 +2055,7 @@ async function pollOwnership(check, deadlineMs) {
 }
 function describePortOwner(port) {
   try {
-    const out = execFileSync6("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-Fcp"], {
+    const out = execFileSync7("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-Fcp"], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"]
     });
@@ -2022,7 +2104,7 @@ import * as fs8 from "node:fs";
 import * as net4 from "node:net";
 import * as os2 from "node:os";
 import * as path8 from "node:path";
-import { spawn as spawn2, execFileSync as execFileSync7 } from "node:child_process";
+import { spawn as spawn2, execFileSync as execFileSync8 } from "node:child_process";
 function tenantStateDir(tenant) {
   return path8.join(CONFIG_DIR, "tailscale", tenant);
 }
@@ -2097,7 +2179,7 @@ function resolveBrewBin(name) {
   const brew = `/opt/homebrew/bin/${name}`;
   if (fs8.existsSync(brew)) return brew;
   try {
-    const p = execFileSync7("which", [name], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    const p = execFileSync8("which", [name], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
     if (p) return p;
   } catch {
   }
@@ -2106,7 +2188,7 @@ function resolveBrewBin(name) {
 function daemonState(tenant) {
   if (!fs8.existsSync(socketPath(tenant))) return { backendState: "Down" };
   try {
-    const out = execFileSync7(
+    const out = execFileSync8(
       tailscaleBinPath(),
       ["--socket", socketPath(tenant), "status", "--json"],
       { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }
@@ -2126,7 +2208,7 @@ function findRunningDaemon(tenant) {
   const sock = socketPath(tenant);
   let out;
   try {
-    out = execFileSync7("ps", ["ax", "-o", "pid=,command="], {
+    out = execFileSync8("ps", ["ax", "-o", "pid=,command="], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"]
     });
@@ -2290,7 +2372,7 @@ async function joinHeadscale(tenant, loginServer, opts = {}) {
 }
 function logout(tenant) {
   try {
-    execFileSync7(tailscaleBinPath(), ["--socket", socketPath(tenant), "logout"], { stdio: "ignore" });
+    execFileSync8(tailscaleBinPath(), ["--socket", socketPath(tenant), "logout"], { stdio: "ignore" });
   } catch {
   }
 }
@@ -2531,8 +2613,8 @@ function guiDomain() {
 function launchdAvailable() {
   if (_launchdAvailable !== void 0) return _launchdAvailable;
   try {
-    execFileSync7("which", ["launchctl"], { stdio: "ignore" });
-    execFileSync7("launchctl", ["print", guiDomain()], { stdio: "ignore" });
+    execFileSync8("which", ["launchctl"], { stdio: "ignore" });
+    execFileSync8("launchctl", ["print", guiDomain()], { stdio: "ignore" });
     _launchdAvailable = true;
   } catch {
     _launchdAvailable = false;
@@ -2564,10 +2646,10 @@ function installLaunchAgent(tenant, meshBin) {
       })
     );
     try {
-      execFileSync7("launchctl", ["bootout", guiDomain(), plistPath], { stdio: "ignore" });
+      execFileSync8("launchctl", ["bootout", guiDomain(), plistPath], { stdio: "ignore" });
     } catch {
     }
-    execFileSync7("launchctl", ["bootstrap", guiDomain(), plistPath], { stdio: "ignore" });
+    execFileSync8("launchctl", ["bootstrap", guiDomain(), plistPath], { stdio: "ignore" });
     return true;
   } catch {
     return false;
@@ -2576,7 +2658,7 @@ function installLaunchAgent(tenant, meshBin) {
 function uninstallLaunchAgent(tenant) {
   const plistPath = launchAgentPath(tenant);
   try {
-    execFileSync7("launchctl", ["bootout", guiDomain(), plistPath], { stdio: "ignore" });
+    execFileSync8("launchctl", ["bootout", guiDomain(), plistPath], { stdio: "ignore" });
   } catch {
   }
   try {
@@ -2816,7 +2898,7 @@ var init_tunnel = __esm({
 });
 
 // libs/mesh-cli/src/commands/vpn/index.ts
-import { execFileSync as execFileSync8 } from "child_process";
+import { execFileSync as execFileSync9 } from "child_process";
 import * as net6 from "node:net";
 function defaultNamespace(tenant, env) {
   return `${tenant}-${env}-headscale`;
@@ -2834,7 +2916,7 @@ function headscaleExec(namespace, args, opts) {
     stdio: ["pipe", "pipe", "pipe"]
   };
   try {
-    const result = execFileSync8(
+    const result = execFileSync9(
       "kubectl",
       [
         "exec",
@@ -2863,7 +2945,7 @@ function clusterName(tenant, env) {
 }
 function assertPodReady(namespace, options) {
   try {
-    const output = execFileSync8(
+    const output = execFileSync9(
       "kubectl",
       [
         "get",
@@ -2898,7 +2980,7 @@ async function vpnStatus(options) {
   const ns = resolveNamespace(options);
   logInfo(`Checking Headscale in namespace ${ns}...`);
   assertPodReady(ns, options);
-  const podJson = execFileSync8(
+  const podJson = execFileSync9(
     "kubectl",
     [
       "get",
@@ -2920,7 +3002,7 @@ async function vpnStatus(options) {
   const restarts = container?.restartCount ?? 0;
   let endpoint = "unknown";
   try {
-    endpoint = execFileSync8(
+    endpoint = execFileSync9(
       "kubectl",
       [
         "get",
@@ -3075,7 +3157,7 @@ function findFreePort2() {
 }
 function findTailscale() {
   try {
-    return execFileSync8("which", ["tailscale"], {
+    return execFileSync9("which", ["tailscale"], {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
     }).trim() || null;
@@ -3085,7 +3167,7 @@ function findTailscale() {
 }
 function tailscaleStatus() {
   try {
-    const json = execFileSync8("tailscale", ["status", "--json"], {
+    const json = execFileSync9("tailscale", ["status", "--json"], {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
     });
@@ -3166,7 +3248,7 @@ async function vpnConnectSystem(endpoint) {
     "--accept-routes"
   ];
   try {
-    execFileSync8("tailscale", upArgs, { stdio: "inherit" });
+    execFileSync9("tailscale", upArgs, { stdio: "inherit" });
     console.log("");
     logSuccess("VPN connected.");
   } catch (error) {
@@ -3193,7 +3275,7 @@ async function vpnDisconnect(opts) {
     }
     logInfo("Disconnecting system VPN\u2026");
     try {
-      execFileSync8("tailscale", ["down"], { stdio: "inherit" });
+      execFileSync9("tailscale", ["down"], { stdio: "inherit" });
       logSuccess("VPN disconnected.");
     } catch (error) {
       const code = error.status;
@@ -3278,6 +3360,7 @@ __export(login_exports, {
   getContextConfig: () => getContextConfig,
   getValidToken: () => getValidToken,
   isRemoteEnvironment: () => isRemoteEnvironment,
+  loginTimeoutMessage: () => loginTimeoutMessage,
   probeCredentials: () => probeCredentials,
   readAllContextConfigs: () => readAllContextConfigs,
   readAllCredentials: () => readAllCredentials,
@@ -3298,7 +3381,7 @@ import * as http from "http";
 import * as crypto2 from "crypto";
 import * as fs9 from "fs";
 import * as path9 from "path";
-import { execFileSync as execFileSync9 } from "child_process";
+import { execFileSync as execFileSync10 } from "child_process";
 function readConfig() {
   if (!fs9.existsSync(CONFIG_FILE)) return {};
   try {
@@ -3613,9 +3696,9 @@ function login(context, config) {
       const url = authUrl.toString();
       try {
         if (process.platform === "darwin") {
-          execFileSync9("open", [url], { stdio: "ignore" });
+          execFileSync10("open", [url], { stdio: "ignore" });
         } else if (process.platform === "linux") {
-          execFileSync9("xdg-open", [url], { stdio: "ignore" });
+          execFileSync10("xdg-open", [url], { stdio: "ignore" });
         } else {
           logInfo(`Open this URL in your browser:
 ${url}`);
@@ -3627,7 +3710,7 @@ ${url}`);
     });
     timeoutId = setTimeout(() => {
       teardown();
-      reject(new Error("Login timed out (2 minutes)"));
+      reject(new Error(loginTimeoutMessage(context)));
     }, 12e4);
   });
 }
@@ -3668,9 +3751,9 @@ async function attemptDeviceCode(context, config) {
   logInfo("Waiting for authorization...");
   try {
     if (process.platform === "darwin") {
-      execFileSync9("open", [openUrl], { stdio: "ignore" });
+      execFileSync10("open", [openUrl], { stdio: "ignore" });
     } else if (process.platform === "linux") {
-      execFileSync9("xdg-open", [openUrl], { stdio: "ignore" });
+      execFileSync10("xdg-open", [openUrl], { stdio: "ignore" });
     }
   } catch {
   }
@@ -3731,6 +3814,11 @@ async function attemptDeviceCode(context, config) {
   }
   return "expired";
 }
+function loginTimeoutMessage(context) {
+  const base = "Login timed out (2 minutes)";
+  if (context !== "local") return base;
+  return `${base}. The local platform already has a signed-up user \u2014 sign in as dev@local.mesh / LocalDev1! instead of registering. If you did register, its confirmation email is in the local mailbox at http://localhost:8025; confirm it there and run the command again.`;
+}
 function isRemoteEnvironment() {
   if (process.env.REMOTE_CONTAINERS || process.env.CODESPACES) return true;
   if (fs9.existsSync("/.dockerenv")) return true;
@@ -5306,7 +5394,7 @@ var init_kubeconfig = __esm({
 });
 
 // libs/mesh-cli/src/utils/temporal-auth.ts
-import { execFileSync as execFileSync10 } from "node:child_process";
+import { execFileSync as execFileSync11 } from "node:child_process";
 async function resolveTemporalAuth(tenant, env, platformName = tenant) {
   const { SSMClient: SSMClient5, GetParameterCommand: GetParameterCommand2 } = await import("@aws-sdk/client-ssm");
   const ssm = new SSMClient5({ region: process.env.AWS_REGION || "us-east-2" });
@@ -5350,7 +5438,7 @@ async function resolveTemporalAuth(tenant, env, platformName = tenant) {
     }
     if (!results.ZITADEL_ISSUER) {
       try {
-        const podEnv = execFileSync10(
+        const podEnv = execFileSync11(
           "kubectl",
           [
             "get",
@@ -5625,7 +5713,7 @@ var init_dev_launch = __esm({
 });
 
 // libs/mesh-cli/src/commands/local/mocks.ts
-import { execFileSync as execFileSync11 } from "child_process";
+import { execFileSync as execFileSync12 } from "child_process";
 import * as fs14 from "fs";
 import * as path14 from "path";
 function externalMode(name, decl) {
@@ -5778,7 +5866,7 @@ async function composeExternalUp(appRoot, sessionName, name, decl, probes = dock
   if (plan.action === "adopt-stopped") {
     const { container } = plan;
     logInfo(`External '${name}': container '${container}' exists from another checkout \u2014 starting and adopting it.`);
-    execFileSync11("docker", ["start", container], { stdio: ["ignore", "ignore", "inherit"] });
+    execFileSync12("docker", ["start", container], { stdio: ["ignore", "ignore", "inherit"] });
     if (!await waitForPort2(decl.port, 3e5)) {
       throw new MeshCliError(
         `External '${name}': adopted container '${container}' never served localhost:${decl.port}.`,
@@ -5787,7 +5875,7 @@ async function composeExternalUp(appRoot, sessionName, name, decl, probes = dock
     }
     return void 0;
   }
-  execFileSync11(
+  execFileSync12(
     "docker",
     ["compose", "-p", project, "-f", composeFile, "up", "-d", "--wait", "--wait-timeout", "300"],
     { stdio: ["ignore", "inherit", "inherit"] }
@@ -5796,7 +5884,7 @@ async function composeExternalUp(appRoot, sessionName, name, decl, probes = dock
 }
 function ownsRunningRealization(composeFile, project) {
   try {
-    const out = execFileSync11(
+    const out = execFileSync12(
       "docker",
       ["compose", "-p", project, "-f", composeFile, "ps", "--format", "json"],
       { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }
@@ -5809,7 +5897,7 @@ function ownsRunningRealization(composeFile, project) {
 function composeServices(composeFile) {
   try {
     const config = JSON.parse(
-      execFileSync11("docker", ["compose", "-f", composeFile, "config", "--format", "json"], {
+      execFileSync12("docker", ["compose", "-f", composeFile, "config", "--format", "json"], {
         encoding: "utf-8",
         stdio: ["ignore", "pipe", "ignore"]
       })
@@ -5822,7 +5910,7 @@ function composeServices(composeFile) {
 }
 function portPublisher(port) {
   try {
-    const out = execFileSync11(
+    const out = execFileSync12(
       "docker",
       [
         "ps",
@@ -5869,7 +5957,7 @@ function foreignPinnedContainer(composeFile, project) {
     const pinned = svc?.container_name;
     if (!pinned) continue;
     try {
-      const owner = execFileSync11(
+      const owner = execFileSync12(
         "docker",
         ["inspect", pinned, "--format", '{{ index .Config.Labels "com.docker.compose.project" }}'],
         { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }
@@ -5883,7 +5971,7 @@ function foreignPinnedContainer(composeFile, project) {
 function composeExternalsDown(refs) {
   for (const ref of refs ?? []) {
     try {
-      execFileSync11("docker", ["compose", "-p", ref.project, "-f", ref.composeFile, "down", "--remove-orphans"], {
+      execFileSync12("docker", ["compose", "-p", ref.project, "-f", ref.composeFile, "down", "--remove-orphans"], {
         stdio: ["ignore", "inherit", "inherit"]
       });
     } catch {
@@ -6212,7 +6300,11 @@ var init_src = __esm({
       description: z.string().optional(),
       surfaces: apiSurfaceSchema,
       credentials: z.object({ keyedBy: z.string().nullish() }).optional(),
-      docs: z.object({ url: z.string().min(1), contentHash: z.string().min(1) }),
+      docs: z.object({
+        url: z.string().min(1),
+        contentHash: z.string().min(1),
+        siteUrl: z.string().min(1).optional()
+      }),
       enabledOps: z.array(z.string()),
       // The consumer schema strips unknown keys, so a producer-side field that is
       // not mirrored here never reaches a consumer — mirror every addition.
@@ -7409,7 +7501,7 @@ var init_dev_local = __esm({
 });
 
 // libs/mesh-cli/src/commands/local/docker-runner.ts
-import { execFileSync as execFileSync12 } from "child_process";
+import { execFileSync as execFileSync13 } from "child_process";
 import * as fs18 from "fs";
 import * as path18 from "path";
 function sessionDir(sessionName) {
@@ -7467,29 +7559,29 @@ function composeArgs(sessionName, args) {
   return ["compose", "-p", sessionName, "-f", path18.join(sessionDir(sessionName), "compose.yml"), ...args];
 }
 function dockerDevUp(sessionName) {
-  execFileSync12("docker", composeArgs(sessionName, ["up", "-d"]), {
+  execFileSync13("docker", composeArgs(sessionName, ["up", "-d"]), {
     stdio: ["ignore", "inherit", "inherit"]
   });
 }
 function dockerDevDown(sessionName) {
-  execFileSync12("docker", composeArgs(sessionName, ["down", "--remove-orphans"]), {
+  execFileSync13("docker", composeArgs(sessionName, ["down", "--remove-orphans"]), {
     stdio: ["ignore", "inherit", "inherit"]
   });
 }
 function dockerDevPs(sessionName) {
-  return execFileSync12("docker", composeArgs(sessionName, ["ps", "--format", "table {{.Service}}	{{.State}}	{{.Status}}"]), {
+  return execFileSync13("docker", composeArgs(sessionName, ["ps", "--format", "table {{.Service}}	{{.State}}	{{.Status}}"]), {
     encoding: "utf-8",
     stdio: ["ignore", "pipe", "pipe"]
   });
 }
 function dockerDevLogs(sessionName, service, tail) {
-  return execFileSync12("docker", composeArgs(sessionName, ["logs", "--tail", String(tail), service]), {
+  return execFileSync13("docker", composeArgs(sessionName, ["logs", "--tail", String(tail), service]), {
     encoding: "utf-8",
     stdio: ["ignore", "pipe", "pipe"]
   });
 }
 function dockerDevRestart(sessionName, service) {
-  execFileSync12("docker", composeArgs(sessionName, ["restart", service]), {
+  execFileSync13("docker", composeArgs(sessionName, ["restart", service]), {
     stdio: ["ignore", "inherit", "inherit"]
   });
 }
@@ -7558,7 +7650,7 @@ var init_peer_addressing = __esm({
 });
 
 // libs/mesh-cli/src/utils/worktree-identity.ts
-import { execFileSync as execFileSync13 } from "node:child_process";
+import { execFileSync as execFileSync14 } from "node:child_process";
 import * as crypto3 from "node:crypto";
 import * as path19 from "node:path";
 function sanitizeSlug(name) {
@@ -7630,7 +7722,7 @@ var init_worktree_identity = __esm({
     PORT_BLOCK_SIZE = 40;
     PORT_BLOCK_SERVICE_SUBRANGE = 24;
     STACK_SLUG_MAX = 16;
-    defaultGitRunner = (args, cwd) => execFileSync13("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    defaultGitRunner = (args, cwd) => execFileSync14("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
   }
 });
 
@@ -7692,7 +7784,7 @@ var init_dev_token_server = __esm({
 });
 
 // libs/mesh-cli/src/commands/dev.ts
-import { execFileSync as execFileSync14, spawn as spawn3, spawnSync as spawnSync2 } from "child_process";
+import { execFileSync as execFileSync15, spawn as spawn3, spawnSync as spawnSync2 } from "child_process";
 import * as fs19 from "fs";
 import * as net8 from "net";
 import * as os6 from "os";
@@ -8023,7 +8115,7 @@ function detectStack(appRoot, stageArg) {
   if (stageArg) return stageArg;
   if (process.env.MESH_STAGE) return process.env.MESH_STAGE;
   try {
-    const result = execFileSync14("pulumi", ["stack", "--show-name"], {
+    const result = execFileSync15("pulumi", ["stack", "--show-name"], {
       cwd: appRoot,
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "ignore"]
@@ -8046,7 +8138,7 @@ function detectStack(appRoot, stageArg) {
 }
 function stackArgs(appRoot, stack) {
   try {
-    const selected = execFileSync14("pulumi", ["stack", "--show-name"], {
+    const selected = execFileSync15("pulumi", ["stack", "--show-name"], {
       cwd: appRoot,
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "ignore"]
@@ -8055,7 +8147,7 @@ function stackArgs(appRoot, stack) {
   } catch {
   }
   try {
-    execFileSync14("pulumi", ["stack", "select", stack], {
+    execFileSync15("pulumi", ["stack", "select", stack], {
       cwd: appRoot,
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "ignore"]
@@ -8084,7 +8176,7 @@ function getDevOutput(appRoot, stack, awsEnv) {
 }
 function hasTmux() {
   try {
-    execFileSync14("which", ["tmux"], { stdio: "ignore" });
+    execFileSync15("which", ["tmux"], { stdio: "ignore" });
     return true;
   } catch {
     return false;
@@ -8092,7 +8184,7 @@ function hasTmux() {
 }
 function sessionExists(name) {
   try {
-    execFileSync14("tmux", ["has-session", "-t", name], { stdio: "ignore" });
+    execFileSync15("tmux", ["has-session", "-t", name], { stdio: "ignore" });
     return true;
   } catch {
     return false;
@@ -8100,7 +8192,7 @@ function sessionExists(name) {
 }
 function killSession(name) {
   try {
-    execFileSync14("tmux", ["kill-session", "-t", name], { stdio: "ignore" });
+    execFileSync15("tmux", ["kill-session", "-t", name], { stdio: "ignore" });
     return true;
   } catch {
     return false;
@@ -8240,7 +8332,7 @@ function getServiceEnvVars(service, tunnels) {
 }
 function setTmuxEnv(sessionName, vars) {
   for (const [key, value] of Object.entries(vars)) {
-    execFileSync14("tmux", ["set-environment", "-t", sessionName, key, value], { stdio: "ignore" });
+    execFileSync15("tmux", ["set-environment", "-t", sessionName, key, value], { stdio: "ignore" });
   }
 }
 function envPrefix(vars) {
@@ -8281,7 +8373,7 @@ function resolveTemporalEncodingKey(tenant, env, appName) {
   const namespace = `${tenant}-${env}-${appName}`;
   const secretName = `${namespace}-temporal-encoding-key`;
   try {
-    const b64 = execFileSync14(
+    const b64 = execFileSync15(
       "kubectl",
       [
         "get",
@@ -8486,7 +8578,7 @@ async function allocateSsmLocalPort(remotePort, reservedPorts) {
 }
 function hasSessionManagerPlugin() {
   try {
-    execFileSync14("which", ["session-manager-plugin"], { stdio: "ignore" });
+    execFileSync15("which", ["session-manager-plugin"], { stdio: "ignore" });
     return true;
   } catch {
     return false;
@@ -8585,13 +8677,13 @@ async function startSsmTunnels(sessionName, devOutput) {
         localPortNumber: [String(localPort)]
       })}'`
     ].join(" ");
-    execFileSync14("tmux", ["new-window", "-t", sessionName, "-n", windowName]);
-    execFileSync14(
+    execFileSync15("tmux", ["new-window", "-t", sessionName, "-n", windowName]);
+    execFileSync15(
       "tmux",
       ["set-option", "-t", `${sessionName}:${windowName}`, "remain-on-exit", "on"],
       { stdio: "ignore" }
     );
-    execFileSync14("tmux", ["send-keys", "-t", `${sessionName}:${windowName}`, ssmCmd, "Enter"]);
+    execFileSync15("tmux", ["send-keys", "-t", `${sessionName}:${windowName}`, ssmCmd, "Enter"]);
     rewritten.tunnels[tunnelName] = {
       host: "localhost",
       port: localPort
@@ -8635,7 +8727,7 @@ async function updateDevboxProxy(devOutput, appRoot) {
     lines.push("");
   }
   const caddyfile = lines.join("\n");
-  execFileSync14(
+  execFileSync15(
     "docker",
     [
       "run",
@@ -8651,7 +8743,7 @@ CADDYEOF`
     ],
     { stdio: "pipe" }
   );
-  execFileSync14(
+  execFileSync15(
     "docker",
     [
       "run",
@@ -8722,13 +8814,13 @@ async function setupSubdomainRouting(devOutput, appRoot) {
   fs19.writeFileSync(caddyfile, caddyLines.join("\n"));
   let caddyRunning = false;
   try {
-    execFileSync14("pgrep", ["-f", "caddy run.*mesh-dev-caddy"], { stdio: "pipe" });
+    execFileSync15("pgrep", ["-f", "caddy run.*mesh-dev-caddy"], { stdio: "pipe" });
     caddyRunning = true;
   } catch {
   }
   if (caddyRunning) {
     try {
-      execFileSync14("caddy", ["reload", "--config", caddyfile, "--adapter", "caddyfile"], {
+      execFileSync15("caddy", ["reload", "--config", caddyfile, "--adapter", "caddyfile"], {
         stdio: "pipe"
       });
     } catch {
@@ -8737,7 +8829,7 @@ async function setupSubdomainRouting(devOutput, appRoot) {
     }
   } else {
     try {
-      execFileSync14("which", ["caddy"], { stdio: "pipe" });
+      execFileSync15("which", ["caddy"], { stdio: "pipe" });
     } catch {
       logWarn(
         "Caddy not found. Install for subdomain routing: curl -fsSL https://caddyserver.com/api/download?os=linux&arch=arm64 -o /usr/local/bin/caddy && chmod +x /usr/local/bin/caddy"
@@ -8779,7 +8871,7 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
     return devOutput;
   }
   logInfo(`Creating tmux session: ${sessionName}`);
-  execFileSync14("tmux", ["new-session", "-d", "-s", sessionName, "-n", "status", "-c", appRoot]);
+  execFileSync15("tmux", ["new-session", "-d", "-s", sessionName, "-n", "status", "-c", appRoot]);
   setTmuxEnv(sessionName, awsEnv);
   const hasTunnels = Object.keys(devOutput.tunnels).length > 0;
   let effectiveTransport = tunnelPlan.transport;
@@ -8890,13 +8982,13 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
     const tokenPort = await findFreePort3();
     const tokenUrl = `http://127.0.0.1:${tokenPort}`;
     setTmuxEnv(sessionName, { DEV_USER_TOKEN_URL: tokenUrl });
-    execFileSync14("tmux", ["new-window", "-t", sessionName, "-n", "token-server"]);
-    execFileSync14(
+    execFileSync15("tmux", ["new-window", "-t", sessionName, "-n", "token-server"]);
+    execFileSync15(
       "tmux",
       ["set-option", "-t", `${sessionName}:token-server`, "remain-on-exit", "on"],
       { stdio: "ignore" }
     );
-    execFileSync14("tmux", [
+    execFileSync15("tmux", [
       "send-keys",
       "-t",
       `${sessionName}:token-server`,
@@ -8972,11 +9064,11 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
       cmd,
       service.env?.OTEL_RESOURCE_ATTRIBUTES ? logShipperPath() : void 0
     );
-    execFileSync14("tmux", ["new-window", "-t", sessionName, "-n", name, "-c", serviceDir]);
-    execFileSync14("tmux", ["set-option", "-t", `${sessionName}:${name}`, "remain-on-exit", "on"], {
+    execFileSync15("tmux", ["new-window", "-t", sessionName, "-n", name, "-c", serviceDir]);
+    execFileSync15("tmux", ["set-option", "-t", `${sessionName}:${name}`, "remain-on-exit", "on"], {
       stdio: "ignore"
     });
-    execFileSync14("tmux", ["send-keys", "-t", `${sessionName}:${name}`, launchCmd, "Enter"]);
+    execFileSync15("tmux", ["send-keys", "-t", `${sessionName}:${name}`, launchCmd, "Enter"]);
     logSuccess(`Started: ${name} (${serviceDir}, port ${service.port})`);
   }
   if (process.env.DEVCONTAINER === "1") {
@@ -8987,7 +9079,7 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
     }
   }
   const statusCmd = `watch -n2 -t npx mesh dev --status --session '${sessionName}'`;
-  execFileSync14("tmux", ["send-keys", "-t", `${sessionName}:status`, statusCmd, "Enter"]);
+  execFileSync15("tmux", ["send-keys", "-t", `${sessionName}:status`, statusCmd, "Enter"]);
   console.log("");
   logSuccess(`Dev session started: ${sessionName}`);
   console.log("");
@@ -9044,7 +9136,7 @@ async function showStatus2(sessionName, devOutput, asJson) {
   }
   let windows = [];
   try {
-    const raw = execFileSync14(
+    const raw = execFileSync15(
       "tmux",
       ["list-windows", "-t", sessionName, "-F", "#{window_name} #{pane_dead}"],
       { encoding: "utf-8" }
@@ -9166,7 +9258,7 @@ async function restartService(sessionName, serviceName, appRoot, devOutput, awsE
   }
   const target = `${sessionName}:${serviceName}`;
   try {
-    execFileSync14("tmux", ["respawn-pane", "-k", "-t", target], { stdio: "ignore" });
+    execFileSync15("tmux", ["respawn-pane", "-k", "-t", target], { stdio: "ignore" });
   } catch {
     logError(`Window '${serviceName}' not found in session.`);
     process.exit(1);
@@ -9191,7 +9283,7 @@ async function restartService(sessionName, serviceName, appRoot, devOutput, awsE
     const serviceVars = getServiceEnvVars(service, devOutput.tunnels);
     restartCmd = `${envPrefix(serviceVars)}${cmd}`;
   }
-  execFileSync14("tmux", ["send-keys", "-t", target, restartCmd, "Enter"]);
+  execFileSync15("tmux", ["send-keys", "-t", target, restartCmd, "Enter"]);
   logSuccess(`Restarted: ${serviceName}`);
 }
 function showLogs(sessionName, serviceName, tail) {
@@ -9201,7 +9293,7 @@ function showLogs(sessionName, serviceName, tail) {
   }
   const target = `${sessionName}:${serviceName}`;
   try {
-    const result = execFileSync14("tmux", ["capture-pane", "-t", target, "-p", "-S", `-${tail}`], {
+    const result = execFileSync15("tmux", ["capture-pane", "-t", target, "-p", "-S", `-${tail}`], {
       encoding: "utf-8"
     });
     process.stdout.write(result);
@@ -10084,7 +10176,7 @@ var init_dev = __esm({
 });
 
 // libs/mesh-cli/src/commands/dev-doctor.ts
-import { execFileSync as execFileSync15 } from "node:child_process";
+import { execFileSync as execFileSync16 } from "node:child_process";
 import * as fs20 from "node:fs";
 import * as net9 from "node:net";
 import * as path21 from "node:path";
@@ -10221,7 +10313,7 @@ function collectSessionPids(panePids, psOut) {
 }
 function whoHasPort(port) {
   try {
-    const lsof = execFileSync15("lsof", ["-ti", `:${port}`], {
+    const lsof = execFileSync16("lsof", ["-ti", `:${port}`], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"]
     });
@@ -10229,7 +10321,7 @@ function whoHasPort(port) {
     if (!pid) return null;
     let ps = "";
     try {
-      ps = execFileSync15("ps", ["-o", "comm=", "-p", pid], {
+      ps = execFileSync16("ps", ["-o", "comm=", "-p", pid], {
         encoding: "utf8",
         stdio: ["ignore", "pipe", "ignore"]
       });
@@ -10243,7 +10335,7 @@ function whoHasPort(port) {
 function sessionProcessTree(sessionName) {
   let panePids;
   try {
-    const out = execFileSync15(
+    const out = execFileSync16(
       "tmux",
       ["list-panes", "-s", "-t", sessionName, "-F", "#{pane_pid}"],
       { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }
@@ -10255,7 +10347,7 @@ function sessionProcessTree(sessionName) {
   if (panePids.length === 0) return /* @__PURE__ */ new Set();
   let psOut = "";
   try {
-    psOut = execFileSync15("ps", ["-eo", "pid=,ppid="], {
+    psOut = execFileSync16("ps", ["-eo", "pid=,ppid="], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"]
     });
@@ -10377,7 +10469,7 @@ var init_dev_doctor = __esm({
       phases: ["preflight", "ondemand"],
       async run() {
         try {
-          execFileSync15("which", ["tmux"], { stdio: "ignore" });
+          execFileSync16("which", ["tmux"], { stdio: "ignore" });
           return { status: "ok", summary: "installed" };
         } catch {
           return {
@@ -10482,7 +10574,7 @@ var init_dev_doctor = __esm({
         }
         let repoRoot2;
         try {
-          repoRoot2 = execFileSync15("git", ["rev-parse", "--show-toplevel"], {
+          repoRoot2 = execFileSync16("git", ["rev-parse", "--show-toplevel"], {
             cwd: ctx.appRoot,
             encoding: "utf8",
             stdio: ["ignore", "pipe", "ignore"]
@@ -10705,6 +10797,209 @@ function authzSurface(app) {
   walk2(app);
   return hits;
 }
+function balancedSpan(text, open) {
+  const closers = { "(": ")", "{": "}", "[": "]" };
+  const stack = [];
+  let quote;
+  for (let i = open; i < text.length; i++) {
+    const ch = text[i];
+    if (quote) {
+      if (ch === "\\") i++;
+      else if (ch === quote) quote = void 0;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      quote = ch;
+      continue;
+    }
+    if (ch === "/" && text[i + 1] === "/") {
+      const eol = text.indexOf("\n", i);
+      if (eol === -1) return "";
+      i = eol;
+      continue;
+    }
+    if (ch === "/" && text[i + 1] === "*") {
+      const end = text.indexOf("*/", i + 2);
+      if (end === -1) return "";
+      i = end + 1;
+      continue;
+    }
+    if (closers[ch]) stack.push(closers[ch]);
+    else if (ch === ")" || ch === "}" || ch === "]") {
+      if (stack.pop() !== ch) return "";
+      if (stack.length === 0) return text.slice(open, i + 1);
+    }
+  }
+  return "";
+}
+function splitTopLevel(inner) {
+  const parts = [];
+  let depth = 0;
+  let quote;
+  let start = 0;
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i];
+    if (quote) {
+      if (ch === "\\") i++;
+      else if (ch === quote) quote = void 0;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      quote = ch;
+      continue;
+    }
+    if (ch === "/" && inner[i + 1] === "/") {
+      const eol = inner.indexOf("\n", i);
+      if (eol === -1) break;
+      i = eol;
+      continue;
+    }
+    if (ch === "/" && inner[i + 1] === "*") {
+      const end = inner.indexOf("*/", i + 2);
+      if (end === -1) break;
+      i = end + 1;
+      continue;
+    }
+    if (ch === "(" || ch === "{" || ch === "[") depth++;
+    else if (ch === ")" || ch === "}" || ch === "]") depth--;
+    else if (ch === "," && depth === 0) {
+      parts.push(inner.slice(start, i));
+      start = i + 1;
+    }
+  }
+  const last = inner.slice(start);
+  if (last.trim()) parts.push(last);
+  return parts;
+}
+function stripLeadingComments(entry) {
+  let text = entry;
+  for (; ; ) {
+    const next = text.replace(/^\s*(?:\/\/[^\n]*(?:\n|$)|\/\*[\s\S]*?\*\/)/, "");
+    if (next === text) return text;
+    text = next;
+  }
+}
+function stripTrailingComments(value) {
+  let out = "";
+  let depth = 0;
+  let quote;
+  for (let i = 0; i < value.length; i++) {
+    const ch = value[i];
+    if (quote) {
+      out += ch;
+      if (ch === "\\") {
+        out += value[i + 1] ?? "";
+        i++;
+      } else if (ch === quote) quote = void 0;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      quote = ch;
+      out += ch;
+      continue;
+    }
+    if (depth === 0 && ch === "/" && value[i + 1] === "/") {
+      const eol = value.indexOf("\n", i);
+      if (eol === -1) break;
+      i = eol;
+      out += "\n";
+      continue;
+    }
+    if (depth === 0 && ch === "/" && value[i + 1] === "*") {
+      const end = value.indexOf("*/", i + 2);
+      if (end === -1) break;
+      i = end + 1;
+      continue;
+    }
+    if (ch === "(" || ch === "{" || ch === "[") depth++;
+    else if (ch === ")" || ch === "}" || ch === "]") depth--;
+    out += ch;
+  }
+  return out.trim();
+}
+function topLevelProperties(objectText) {
+  const props = /* @__PURE__ */ new Map();
+  if (!objectText.startsWith("{") || !objectText.endsWith("}")) return props;
+  for (const entry of splitTopLevel(objectText.slice(1, -1))) {
+    const text = stripLeadingComments(entry).trim();
+    if (!text || text.startsWith("...")) continue;
+    const m = RE_PROPERTY.exec(text);
+    if (!m) continue;
+    const key = m[1] ?? m[2] ?? m[3];
+    props.set(key, stripTrailingComments(m[4] ?? key));
+  }
+  return props;
+}
+function objectLiteralOf(value, program2) {
+  if (!value) return void 0;
+  if (value.startsWith("{")) return balancedSpan(value, 0) || void 0;
+  const id = /^[A-Za-z_$][\w$]*$/.exec(value)?.[0];
+  if (!id) return void 0;
+  const decl = new RegExp(`\\bconst\\s+${id}\\s*(?::[^=]+)?=\\s*\\{`).exec(program2);
+  return decl ? balancedSpan(program2, decl.index + decl[0].length - 1) || void 0 : void 0;
+}
+function optionsObject(body) {
+  for (const arg of splitTopLevel(body.slice(1, -1))) {
+    const trimmed = arg.trim();
+    if (trimmed.startsWith("{")) return balancedSpan(trimmed, 0) || void 0;
+  }
+  return void 0;
+}
+function surfaceDeclarations(text, pattern = RE_SURFACE_NEW) {
+  const out = [];
+  for (const m of text.matchAll(pattern)) {
+    const body = balancedSpan(text, m.index + m[0].length - 1);
+    if (!body) continue;
+    out.push({ ctor: m[1] ?? "ApiDocs", body, line: text.slice(0, m.index).split("\n").length });
+  }
+  return out;
+}
+function isClientAuth(value) {
+  return value !== void 0 && value !== "undefined" && !RE_DEV_BYPASS.test(value);
+}
+function docsSiteFindings(text) {
+  const findings = [];
+  for (const decl of surfaceDeclarations(text)) {
+    const options = optionsObject(decl.body);
+    if (!options) continue;
+    const args = topLevelProperties(options);
+    const docsText = objectLiteralOf(args.get("docs"), text);
+    if (!docsText) continue;
+    const docs = topLevelProperties(docsText);
+    if (docs.get("site") === "false") continue;
+    if (docs.get("site") !== "true" && !DOCS_SITE_FIELDS.some((f) => docs.has(f))) continue;
+    const httpText = objectLiteralOf(topLevelProperties(objectLiteralOf(args.get("surfaces"), text) ?? "{}").get("http"), text);
+    const hasClient = isClientAuth(docs.get("auth")) || isClientAuth(topLevelProperties(httpText ?? "{}").get("auth"));
+    if (!hasClient) {
+      findings.push({
+        code: "DOCS_SITE_UNAUTHED",
+        line: decl.line,
+        why: `mesh.apps.${decl.ctor} declares a docs site with no OIDC client \u2014 the site is served behind the platform sign-in proxy, which needs one (docs.auth, or a client on surfaces.http.auth)`
+      });
+    }
+    const kindStated = decl.ctor === "AppApiSurface" || decl.ctor === "VendorApiSurface" || args.has("kind");
+    if (!kindStated && !docs.has("audience")) {
+      findings.push({
+        code: "DOCS_AUDIENCE_IMPLICIT",
+        line: decl.line,
+        why: `mesh.apps.${decl.ctor} declares a docs site but neither its kind nor its audience \u2014 who may read it would fall out of the name heuristic, and a vendor surface must never default to partner-readable that way`
+      });
+    }
+  }
+  for (const decl of surfaceDeclarations(text, RE_APIDOCS_NEW)) {
+    const options = optionsObject(decl.body);
+    if (!options) continue;
+    const args = topLevelProperties(options);
+    if (!args.has("ingress") || args.get("ingress") === "undefined") continue;
+    if (isClientAuth(args.get("auth"))) continue;
+    findings.push({
+      code: "DOCS_SITE_UNAUTHED",
+      line: decl.line,
+      why: `mesh.apps.ApiDocs is published on an ingress with no auth \u2014 the site (reference and playground) is reachable by anyone; put the platform sign-in proxy in front of it, or drop the ingress`
+    });
+  }
+  return findings;
+}
 function listApps(root) {
   const apps = [];
   const appsDir = path22.join(root, "apps");
@@ -10753,6 +11048,7 @@ function scanApp(root, appRel) {
     if (!/env\.register\(|\.annotate\(/.test(readText(index))) {
       hit("NO_REGISTER", indexRel, "never calls env.register({\u2026}) \u2014 the Hub cannot list this app");
     }
+    for (const f of docsSiteFindings(readText(index))) hit(f.code, `${indexRel}:${f.line}`, f.why);
     for (const svc of serviceDirs(app)) {
       for (const f of srcFiles(svc)) {
         const text = readText(f);
@@ -10909,7 +11205,7 @@ function registerAppCommands(program2) {
     }
   });
 }
-var APP_CHECK_RULES, APP_CHECK_CODES, SRC_EXT, SKIP_DIRS, NON_SERVICE_DIRS, RE_HTML, RE_OIDC, RE_COOKIE, RE_LOGGER, RE_EXPOSURE, RE_POINTER, RE_METADATA, RE_IAC_GRANT, RE_POINTER_OVERRIDE, RE_PASSWORD, RE_ALLOWLIST, RE_USERS_TABLE;
+var APP_CHECK_RULES, APP_CHECK_CODES, SRC_EXT, SKIP_DIRS, NON_SERVICE_DIRS, RE_HTML, RE_OIDC, RE_COOKIE, RE_LOGGER, RE_EXPOSURE, RE_POINTER, RE_METADATA, RE_IAC_GRANT, RE_POINTER_OVERRIDE, RE_PASSWORD, RE_ALLOWLIST, RE_USERS_TABLE, RE_SURFACE_NEW, RE_APIDOCS_NEW, DOCS_SITE_FIELDS, RE_DEV_BYPASS, RE_PROPERTY;
 var init_app_check = __esm({
   "libs/mesh-cli/src/commands/app-check.ts"() {
     "use strict";
@@ -11008,6 +11304,20 @@ var init_app_check = __esm({
         severity: "block",
         remediation: "drop the table; people and roles live in Zitadel and are administered from the Hub",
         scope: "app"
+      },
+      DOCS_SITE_UNAUTHED: {
+        gate: "0.3",
+        title: "Docs site behind the platform sign-in",
+        severity: "block",
+        remediation: 'on an API surface: docs: { auth: { clientId, clientSecret } } (or a client on surfaces.http.auth), or opt out with docs: { site: false }; on a mesh.apps.ApiDocs: auth: { provider: "mesh", clientId, clientSecret }, or drop the ingress (an in-cluster site is reachable through mesh dev)',
+        scope: "app"
+      },
+      DOCS_AUDIENCE_IMPLICIT: {
+        gate: "H",
+        title: "Docs audience stated, not derived",
+        severity: "block",
+        remediation: 'declare the surface as mesh.apps.AppApiSurface or VendorApiSurface (or pass kind: "app" | "vendor"), or state docs: { audience: { roles: [\u2026] } }',
+        scope: "app"
       }
     };
     APP_CHECK_CODES = Object.keys(APP_CHECK_RULES);
@@ -11039,6 +11349,11 @@ var init_app_check = __esm({
     RE_PASSWORD = /(^|[^a-z])(bcrypt|argon2)|password_hash|passwordHash|hashPassword|temporaryPassword.*(send|mail)|(send|mail).*temporaryPassword/;
     RE_ALLOWLIST = /ADMIN_EMAILS|ALLOWED_EMAILS|allowedEmails|adminEmails/;
     RE_USERS_TABLE = /create table (if not exists )?"?(users|roles|user_roles|permissions)"?/i;
+    RE_SURFACE_NEW = /new\s+mesh\.apps\.(ApiSurface|AppApiSurface|VendorApiSurface|Integration)\s*\(/g;
+    RE_APIDOCS_NEW = /new\s+mesh\.apps\.ApiDocs\s*\(/g;
+    DOCS_SITE_FIELDS = ["pages", "playground", "audience", "basePath", "ingress", "auth"];
+    RE_DEV_BYPASS = /^["']dev-bypass["']$/;
+    RE_PROPERTY = /^(?:"([^"]+)"|'([^']+)'|([A-Za-z_$][\w$]*))\s*(?::\s*([\s\S]*))?$/;
   }
 });
 
@@ -12229,7 +12544,7 @@ var init_conversations = __esm({
 });
 
 // libs/mesh-cli/src/utils/scaffold-versions.ts
-import { execFileSync as execFileSync16 } from "child_process";
+import { execFileSync as execFileSync17 } from "child_process";
 function isPrerelease(range) {
   return /[-+]/.test(range.replace(/^\^/, ""));
 }
@@ -12239,7 +12554,7 @@ function toCaretRange(version) {
 }
 function resolvePublishedRange(pkg, cwd) {
   try {
-    const out = execFileSync16("npm", ["view", pkg, "version"], {
+    const out = execFileSync17("npm", ["view", pkg, "version"], {
       cwd,
       encoding: "utf-8",
       timeout: 15e3,
@@ -12273,6 +12588,7 @@ __export(create_app_exports, {
   NO_REGISTRY_ACCESS_MESSAGE: () => NO_REGISTRY_ACCESS_MESSAGE,
   PLATFORM_MONOREPO_NAME: () => PLATFORM_MONOREPO_NAME,
   bootstrapAppsRepo: () => bootstrapAppsRepo,
+  composableNextSteps: () => composableNextSteps,
   copyTemplate: () => copyTemplate,
   describeNoAppsHome: () => describeNoAppsHome,
   ensureRegistryAccess: () => ensureRegistryAccess,
@@ -12786,15 +13102,30 @@ function printComposableNextSteps(appDir, context) {
     console.log("  api/src/storage.ts  S3 helpers");
   }
   console.log("");
-  console.log("Next steps:");
-  console.log(`  cd ${appDir}`);
-  console.log("  pnpm install");
-  console.log("  mesh skills sync         # re-run once deps are installed: picks up package skills + Intent");
-  console.log("  pnpm install             # again only if skills sync reports it added @tanstack/intent");
-  console.log("  mesh stack init          # personal dev stack (deploy: false)");
-  console.log("  mesh deploy up --yes     # deploy via the stack's deployer role");
-  console.log("  mesh dev                 # run locally");
-  console.log("");
+  for (const line of composableNextSteps(appDir, findMeshJson(process.cwd())?.data.platform ?? null)) {
+    console.log(line);
+  }
+}
+function composableNextSteps(appDir, platform) {
+  const common = [
+    "Next steps:",
+    `  cd ${appDir}`,
+    "  pnpm install",
+    "  mesh skills sync         # re-run once deps are installed: picks up package skills + Intent",
+    "  pnpm install             # again only if skills sync reports it added @tanstack/intent"
+  ];
+  const local = [
+    "  mesh start               # the local Mesh platform (once; Docker \u2014 from anywhere)",
+    "  mesh dev                 # run the app against it"
+  ];
+  const deploy = [
+    "  mesh stack init          # personal dev stack (deploy: false)",
+    "  mesh deploy up --yes     # deploy via the stack's deployer role"
+  ];
+  if (platform === null || platform === "local") {
+    return [...common, ...local, "", "When you deploy to a Mesh platform:", ...deploy];
+  }
+  return [...common, ...deploy, "  mesh dev                 # run locally against the platform"];
 }
 var __filename, __dirname, packageRoot, TEMPLATES, REMOVED_TEMPLATES, PRIMITIVES, HUB_ACCOUNTS, PLATFORM_MONOREPO_NAME, VALID_PRIMITIVES, NO_REGISTRY_ACCESS_MESSAGE;
 var init_create_app = __esm({
@@ -13558,7 +13889,7 @@ var init_deploy_preflight = __esm({
 });
 
 // libs/mesh-cli/src/commands/deploy.ts
-import { execFileSync as execFileSync17 } from "child_process";
+import { execFileSync as execFileSync18 } from "child_process";
 function buildPulumiArgs(pulumiArgs, stack) {
   const base = pulumiArgs.length === 0 || pulumiArgs[0]?.startsWith("-") ? ["up", ...pulumiArgs] : [...pulumiArgs];
   const op = base[0];
@@ -13621,7 +13952,7 @@ function registerDeployCommand(program2) {
     delete env.AWS_PROFILE;
     const finalArgs = buildPulumiArgs(pulumiArgs, stack);
     try {
-      execFileSync17("pulumi", finalArgs, {
+      execFileSync18("pulumi", finalArgs, {
         cwd: appRoot,
         env,
         stdio: "inherit"
@@ -13914,7 +14245,7 @@ var init_discover = __esm({
 });
 
 // libs/mesh-cli/src/docs/assemble.ts
-import { execFileSync as execFileSync18 } from "node:child_process";
+import { execFileSync as execFileSync19 } from "node:child_process";
 import { mkdirSync as mkdirSync11, readFileSync as readFileSync23, rmSync as rmSync5, writeFileSync as writeFileSync15 } from "node:fs";
 import path28 from "node:path";
 import { parse as parseYaml4 } from "yaml";
@@ -14405,7 +14736,7 @@ function renderVersionJson(args) {
 }
 function currentCommit(repoRoot2) {
   try {
-    return execFileSync18("git", ["rev-parse", "--short", "HEAD"], {
+    return execFileSync19("git", ["rev-parse", "--short", "HEAD"], {
       cwd: repoRoot2,
       encoding: "utf-8"
     }).trim();
@@ -14424,7 +14755,7 @@ function currentBaseline(repoRoot2) {
   }
 }
 function publishSetAtRef(repoRoot2, ref) {
-  const git = (gitArgs) => execFileSync18("git", gitArgs, {
+  const git = (gitArgs) => execFileSync19("git", gitArgs, {
     cwd: repoRoot2,
     encoding: "utf-8",
     maxBuffer: 64 * 1024 * 1024
@@ -14912,7 +15243,7 @@ var init_portal = __esm({
 });
 
 // libs/mesh-cli/src/utils/build-info.ts
-import { execFileSync as execFileSync19 } from "child_process";
+import { execFileSync as execFileSync20 } from "child_process";
 import * as fs25 from "fs";
 import * as path30 from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
@@ -14970,7 +15301,7 @@ function resolveCliRuntime(opts) {
   }
   if (!vcs) return info;
   try {
-    const git = (args) => execFileSync19("git", args, {
+    const git = (args) => execFileSync20("git", args, {
       cwd: root,
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "pipe"]
@@ -15067,7 +15398,7 @@ var init_serve = __esm({
 });
 
 // libs/mesh-cli/src/docs/registry-docs.ts
-import { execFileSync as execFileSync20 } from "node:child_process";
+import { execFileSync as execFileSync21 } from "node:child_process";
 import { existsSync as existsSync23, mkdirSync as mkdirSync13, readFileSync as readFileSync26, renameSync as renameSync3, rmSync as rmSync6, writeFileSync as writeFileSync17 } from "node:fs";
 import { tmpdir as tmpdir7 } from "node:os";
 import path31 from "node:path";
@@ -15159,7 +15490,7 @@ async function fetchDocsArtifact(auth, version, cacheRoot = docsCacheRoot(), fet
   rmSync6(staging, { recursive: true, force: true });
   mkdirSync13(staging, { recursive: true });
   try {
-    execFileSync20("tar", ["-xzf", tgzPath, "-C", staging, "--strip-components", "1"], {
+    execFileSync21("tar", ["-xzf", tgzPath, "-C", staging, "--strip-components", "1"], {
       stdio: ["pipe", "pipe", "pipe"]
     });
   } finally {
@@ -15197,7 +15528,7 @@ __export(start_exports, {
   tmuxInstallHint: () => tmuxInstallHint,
   tmuxServeArgs: () => tmuxServeArgs
 });
-import { execFileSync as execFileSync21 } from "node:child_process";
+import { execFileSync as execFileSync22 } from "node:child_process";
 import { appendFileSync as appendFileSync2, existsSync as existsSync24, writeFileSync as writeFileSync18 } from "node:fs";
 import path32 from "node:path";
 function registryAuthOrThrow() {
@@ -15230,7 +15561,7 @@ function tmuxInstallHint(platform = process.platform) {
 }
 function tmuxAvailable() {
   try {
-    execFileSync21("tmux", ["-V"], { stdio: ["pipe", "pipe", "pipe"] });
+    execFileSync22("tmux", ["-V"], { stdio: ["pipe", "pipe", "pipe"] });
     return true;
   } catch {
     return false;
@@ -15241,7 +15572,7 @@ function shouldDetach(args) {
 }
 function docsSessionExists() {
   try {
-    execFileSync21("tmux", ["has-session", "-t", DOCS_TMUX_SESSION], { stdio: ["pipe", "pipe", "pipe"] });
+    execFileSync22("tmux", ["has-session", "-t", DOCS_TMUX_SESSION], { stdio: ["pipe", "pipe", "pipe"] });
     return true;
   } catch {
     return false;
@@ -15265,12 +15596,12 @@ Or run in the foreground instead: mesh docs start --foreground`
   if (docsSessionExists()) {
     logInfo(`Replacing the docs server already running in tmux session "${DOCS_TMUX_SESSION}".`);
     try {
-      execFileSync21("tmux", ["kill-session", "-t", DOCS_TMUX_SESSION], { stdio: ["pipe", "pipe", "pipe"] });
+      execFileSync22("tmux", ["kill-session", "-t", DOCS_TMUX_SESSION], { stdio: ["pipe", "pipe", "pipe"] });
     } catch {
     }
   }
   const { command, cwd } = tmuxServeArgs(args);
-  execFileSync21(
+  execFileSync22(
     "tmux",
     ["new-session", "-d", "-s", DOCS_TMUX_SESSION, "-c", cwd, "--", ...command],
     { stdio: ["pipe", "pipe", "pipe"] }
@@ -15308,7 +15639,7 @@ function printReady(url, label) {
 }
 function runDocsStop() {
   try {
-    execFileSync21("tmux", ["kill-session", "-t", DOCS_TMUX_SESSION], { stdio: ["pipe", "pipe", "pipe"] });
+    execFileSync22("tmux", ["kill-session", "-t", DOCS_TMUX_SESSION], { stdio: ["pipe", "pipe", "pipe"] });
     logSuccess(`Stopped the docs server (tmux session "${DOCS_TMUX_SESSION}").`);
   } catch {
     logInfo(`No docs server is running (no tmux session named "${DOCS_TMUX_SESSION}").`);
@@ -15681,7 +16012,7 @@ var init_docs = __esm({
 });
 
 // libs/mesh-cli/src/commands/hub/index.ts
-import { execFileSync as execFileSync22 } from "node:child_process";
+import { execFileSync as execFileSync23 } from "node:child_process";
 import * as fs27 from "node:fs";
 import * as net12 from "node:net";
 import * as os9 from "node:os";
@@ -15747,7 +16078,7 @@ function parseTmuxEnv(output) {
 }
 function readTmuxSessionEnv(sessionName) {
   try {
-    const out = execFileSync22("tmux", ["show-environment", "-t", sessionName], {
+    const out = execFileSync23("tmux", ["show-environment", "-t", sessionName], {
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "ignore"]
     });
@@ -15758,7 +16089,7 @@ function readTmuxSessionEnv(sessionName) {
 }
 function tmuxSessionExists(sessionName) {
   try {
-    execFileSync22("tmux", ["has-session", "-t", sessionName], { stdio: "ignore" });
+    execFileSync23("tmux", ["has-session", "-t", sessionName], { stdio: "ignore" });
     return true;
   } catch {
     return false;
@@ -15927,7 +16258,7 @@ function redactEnv(env) {
 async function hubDevAction(opts) {
   if (opts.kill) {
     if (tmuxSessionExists(HUB_SESSION)) {
-      execFileSync22("tmux", ["kill-session", "-t", HUB_SESSION], { stdio: "ignore" });
+      execFileSync23("tmux", ["kill-session", "-t", HUB_SESSION], { stdio: "ignore" });
       fs27.rmSync(hubEnvDir(), { recursive: true, force: true });
       logSuccess(`Killed Hub session '${HUB_SESSION}'.`);
     } else {
@@ -15981,17 +16312,17 @@ async function hubDevAction(opts) {
   for (const warning of assembled.warnings) logWarn(warning);
   const apiDir = path34.join(platformDir, "apps", "hub", "api");
   const uiDir = path34.join(platformDir, "apps", "hub", "ui");
-  execFileSync22("tmux", ["new-session", "-d", "-s", HUB_SESSION, "-n", "api", "-c", apiDir]);
+  execFileSync23("tmux", ["new-session", "-d", "-s", HUB_SESSION, "-n", "api", "-c", apiDir]);
   if (!assembled.apiEnv.DEV_USER_TOKEN_URL && assembled.apiEnv.DEV_USER_ID_TOKEN) {
     const platform = session.state.devOutput.platform;
     const credContext = `mesh.${platform.env}`;
     const tokenPort = await findFreePort4();
     const tokenUrl = `http://127.0.0.1:${tokenPort}`;
-    execFileSync22("tmux", ["new-window", "-t", HUB_SESSION, "-n", "token-server", "-c", platformDir]);
-    execFileSync22("tmux", ["set-option", "-t", `${HUB_SESSION}:token-server`, "remain-on-exit", "on"], {
+    execFileSync23("tmux", ["new-window", "-t", HUB_SESSION, "-n", "token-server", "-c", platformDir]);
+    execFileSync23("tmux", ["set-option", "-t", `${HUB_SESSION}:token-server`, "remain-on-exit", "on"], {
       stdio: "ignore"
     });
-    execFileSync22("tmux", [
+    execFileSync23("tmux", [
       "send-keys",
       "-t",
       `${HUB_SESSION}:token-server`,
@@ -16009,12 +16340,12 @@ async function hubDevAction(opts) {
     const envFile = path34.join(hubEnvDir(), `${window}.env.sh`);
     writeEnvFile(envFile, env);
     if (createWindow) {
-      execFileSync22("tmux", ["new-window", "-t", HUB_SESSION, "-n", window, "-c", dir]);
+      execFileSync23("tmux", ["new-window", "-t", HUB_SESSION, "-n", window, "-c", dir]);
     }
-    execFileSync22("tmux", ["set-option", "-t", `${HUB_SESSION}:${window}`, "remain-on-exit", "on"], {
+    execFileSync23("tmux", ["set-option", "-t", `${HUB_SESSION}:${window}`, "remain-on-exit", "on"], {
       stdio: "ignore"
     });
-    execFileSync22("tmux", ["send-keys", "-t", `${HUB_SESSION}:${window}`, buildLaunchCommand(envFile, dir, cmd), "Enter"]);
+    execFileSync23("tmux", ["send-keys", "-t", `${HUB_SESSION}:${window}`, buildLaunchCommand(envFile, dir, cmd), "Enter"]);
   };
   launch("api", apiDir, assembled.apiEnv, "pnpm dev", false);
   launch("ui", uiDir, assembled.uiEnv, `pnpm dev --port ${uiPort} --strictPort`, true);
@@ -16093,7 +16424,7 @@ var init_hub = __esm({
 });
 
 // libs/mesh-cli/src/commands/registry-publish.ts
-import { execFileSync as execFileSync23, execSync } from "child_process";
+import { execFileSync as execFileSync24, execSync } from "child_process";
 import * as fs28 from "fs";
 import * as path35 from "path";
 function repoRoot() {
@@ -16177,14 +16508,14 @@ function registerRegistryPublish(registry) {
         ...opts.dryRun ? ["--dry-run"] : []
       ];
       logInfo(`Publishing ${selected.length} package(s)...`);
-      execFileSync23("bash", args, { cwd: root, stdio: "inherit", env: env ?? process.env });
+      execFileSync24("bash", args, { cwd: root, stdio: "inherit", env: env ?? process.env });
     } finally {
       for (const b of backups) fs28.writeFileSync(b.file, b.content);
       logInfo("Restored source package.json versions.");
       const collateral = [...dirtyPackageJsons(root)].filter((f) => !preDirty.has(f));
       if (collateral.length) {
         try {
-          execFileSync23("git", ["checkout", "--", ...collateral], { cwd: root, stdio: "inherit" });
+          execFileSync24("git", ["checkout", "--", ...collateral], { cwd: root, stdio: "inherit" });
           logInfo(`Reverted ${collateral.length} package.json file(s) re-vendored by build:publish.`);
         } catch {
           logError(
@@ -16236,12 +16567,12 @@ __export(registry_exports, {
   shouldRemintAfter: () => shouldRemintAfter,
   shouldRepairUserNpmrc: () => shouldRepairUserNpmrc
 });
-import { execFileSync as execFileSync24 } from "child_process";
+import { execFileSync as execFileSync25 } from "child_process";
 import * as fs29 from "fs";
 import * as path36 from "path";
 function getEndpoint(env) {
   try {
-    const result = execFileSync24("aws", [
+    const result = execFileSync25("aws", [
       "codeartifact",
       "get-repository-endpoint",
       "--domain",
@@ -16268,7 +16599,7 @@ function getEndpoint(env) {
 }
 function codeartifactLogin(env) {
   try {
-    execFileSync24("aws", [
+    execFileSync25("aws", [
       "codeartifact",
       "login",
       "--tool",
@@ -16323,7 +16654,7 @@ function resolvePublisherRoleArn({
 }
 function assumeRole2(roleArn) {
   try {
-    const result = execFileSync24("aws", [
+    const result = execFileSync25("aws", [
       "sts",
       "assume-role",
       "--role-arn",
@@ -16345,7 +16676,7 @@ function assumeRole2(roleArn) {
 }
 function assumeRoleWithWebIdentity2(roleArn, idToken, sessionName) {
   try {
-    const result = execFileSync24("aws", [
+    const result = execFileSync25("aws", [
       "sts",
       "assume-role-with-web-identity",
       "--role-arn",
@@ -16681,7 +17012,7 @@ region = us-east-2`,
       { remediation: { command: `aws configure sso --profile ${profile}` } }
     );
   }
-  const probe = () => execFileSync24("aws", ["sts", "get-caller-identity", "--profile", profile], {
+  const probe = () => execFileSync25("aws", ["sts", "get-caller-identity", "--profile", profile], {
     stdio: ["ignore", "pipe", "pipe"],
     timeout: 2e4
   });
@@ -16692,7 +17023,7 @@ region = us-east-2`,
   } catch {
     logInfo(`AWS SSO session for profile '${profile}' is stale \u2014 opening browser login\u2026`);
   }
-  execFileSync24("aws", ["sso", "login", "--profile", profile], { stdio: "inherit" });
+  execFileSync25("aws", ["sso", "login", "--profile", profile], { stdio: "inherit" });
   try {
     probe();
   } catch (err) {
@@ -16922,7 +17253,7 @@ __export(wizard_exports, {
 });
 import * as fs30 from "fs";
 import * as path37 from "path";
-import { execFileSync as execFileSync25 } from "child_process";
+import { execFileSync as execFileSync26 } from "child_process";
 import chalk4 from "chalk";
 function wizardExitCode(steps) {
   return steps.some((s) => s.status === "fail") ? 1 : 0;
@@ -16989,7 +17320,7 @@ function classifyRepo(cwd) {
   return { kind: "other-repo", root };
 }
 function gitInit(dir) {
-  execFileSync25("git", ["init", "-q"], { cwd: dir, stdio: ["ignore", "ignore", "pipe"] });
+  execFileSync26("git", ["init", "-q"], { cwd: dir, stdio: ["ignore", "ignore", "pipe"] });
 }
 async function runWizardSteps(ctx, steps) {
   const results = [];
@@ -17584,7 +17915,7 @@ var init_init = __esm({
 });
 
 // libs/mesh-cli/src/commands/install-shim.ts
-import { execFileSync as execFileSync26 } from "child_process";
+import { execFileSync as execFileSync27 } from "child_process";
 import * as fs32 from "fs";
 import * as os10 from "os";
 import * as path39 from "path";
@@ -17697,7 +18028,7 @@ function registerInstallShimCommand(program2) {
     let status = 0;
     let ok = true;
     try {
-      stdout = execFileSync26(target, ["--help"], {
+      stdout = execFileSync27(target, ["--help"], {
         cwd: process.cwd(),
         encoding: "utf8",
         stdio: ["ignore", "pipe", "pipe"]
@@ -17744,7 +18075,7 @@ var init_install_shim = __esm({
 });
 
 // libs/mesh-cli/src/commands/local/hub-local.ts
-import { execFile as execFile3, execFileSync as execFileSync27 } from "child_process";
+import { execFile as execFile3, execFileSync as execFileSync28 } from "child_process";
 import * as fs33 from "fs";
 import * as os11 from "os";
 import * as path40 from "path";
@@ -17764,7 +18095,7 @@ function npmrcPath() {
 }
 function imageExists(tag) {
   try {
-    execFileSync27("docker", ["image", "inspect", tag], { stdio: ["ignore", "pipe", "pipe"] });
+    execFileSync28("docker", ["image", "inspect", tag], { stdio: ["ignore", "pipe", "pipe"] });
     return true;
   } catch {
     return false;
@@ -17774,7 +18105,7 @@ function ensureHubAuthImage() {
   if (imageExists(HUB_AUTH_IMAGE)) return;
   logInfo(`Building ${HUB_AUTH_IMAGE} (Hub auth proxy)\u2026`);
   const hubStackDir = path40.join(findPackageRoot(), "stack", "hub");
-  execFileSync27(
+  execFileSync28(
     "docker",
     ["build", "-f", path40.join(hubStackDir, "Dockerfile.auth"), "-t", HUB_AUTH_IMAGE, hubStackDir],
     { stdio: ["ignore", "inherit", "inherit"], env: { ...process.env, DOCKER_BUILDKIT: "1" } }
@@ -17788,7 +18119,7 @@ function hasRegistryAuth() {
 function localHubVersion() {
   const versions = HUB_IMAGES.map((name) => {
     try {
-      const out = execFileSync27("docker", ["images", name, "--format", "{{.Tag}}"], {
+      const out = execFileSync28("docker", ["images", name, "--format", "{{.Tag}}"], {
         encoding: "utf-8",
         stdio: ["ignore", "pipe", "pipe"]
       });
@@ -17867,7 +18198,7 @@ async function ensureHubImages() {
   const context = path40.join(cacheDir(), `context-${version}`);
   fs33.rmSync(context, { recursive: true, force: true });
   fs33.mkdirSync(context, { recursive: true });
-  execFileSync27("tar", ["-xzf", tarball, "-C", context, "--strip-components", "1"], {
+  execFileSync28("tar", ["-xzf", tarball, "-C", context, "--strip-components", "1"], {
     stdio: ["ignore", "pipe", "pipe"]
   });
   const hubStackDir = path40.join(findPackageRoot(), "stack", "hub");
@@ -17878,7 +18209,7 @@ async function ensureHubImages() {
     const tag = `${name}:${version}`;
     if (imageExists(tag)) continue;
     logInfo(`Building ${tag} from the published tarball\u2026`);
-    execFileSync27(
+    execFileSync28(
       "docker",
       [
         "build",
@@ -17908,7 +18239,7 @@ function readHubCompiledAuthz(version) {
     if (!tarball || !fs33.existsSync(path40.join(cacheDir(), tarball))) return null;
     fs33.mkdirSync(context, { recursive: true });
     try {
-      execFileSync27(
+      execFileSync28(
         "tar",
         ["-xzf", path40.join(cacheDir(), tarball), "-C", context, "--strip-components", "1", `package/${HUB_COMPILED_AUTHZ_REL}`],
         { stdio: ["ignore", "pipe", "pipe"] }
@@ -18002,7 +18333,7 @@ async function buildHubImagesFromSource(repoRoot2) {
   await execFileAsync2("pnpm", ["pack", "--pack-destination", context], { cwd: hubDir, maxBuffer: 64 * 1024 * 1024 });
   const tarball = fs33.readdirSync(context).find((f) => f.endsWith(".tgz"));
   if (!tarball) throw new MeshCliError("pnpm pack produced no tarball for apps/hub");
-  execFileSync27("tar", ["-xzf", path40.join(context, tarball), "-C", context, "--strip-components", "1"], {
+  execFileSync28("tar", ["-xzf", path40.join(context, tarball), "-C", context, "--strip-components", "1"], {
     stdio: ["ignore", "pipe", "pipe"]
   });
   const rewritten = normalizeHubManifests(context, readWorkspaceCatalog(repoRoot2));
@@ -18014,7 +18345,7 @@ async function buildHubImagesFromSource(repoRoot2) {
   ]) {
     const tag = `${name}:${version}`;
     logInfo(`Building ${tag} from source\u2026`);
-    execFileSync27(
+    execFileSync28(
       "docker",
       ["build", "-f", path40.join(hubStackDir, dockerfile), "-t", tag, "--secret", `id=npmrc,src=${npmrc}`, context],
       { stdio: ["ignore", "inherit", "inherit"], env: { ...process.env, DOCKER_BUILDKIT: "1" } }
@@ -18185,8 +18516,42 @@ function printEndpoints(hubRunning) {
   console.log(
     `  ${chalk6.dim(`test users: ${TEST_USERS.map((u) => u.email).join(", ")} (password: ${TEST_USERS[0].password})`)}`
   );
-  console.log("");
-  logInfo("Next: `mesh dev` in an apps repo wires services to this stack automatically.");
+  printStartHere(hubRunning);
+}
+function startHereLines(hubRunning, up) {
+  const dev = TEST_USERS[0];
+  const mailbox = STACK_ENDPOINTS.find((e) => e.service === "mailpit");
+  const flag = (service) => up?.get(service) === false ? chalk6.red("  (not responding \u2014 see Endpoints below)") : "";
+  const lines = ["", chalk6.bold.cyan("\u2605 Start here")];
+  if (hubRunning) {
+    lines.push(
+      `  ${"Hub".padEnd(10)} ${chalk6.bold.cyan(`http://localhost:${hubPort()}`)}${flag("hub-ui")}`,
+      `  ${"".padEnd(10)} ${chalk6.dim(`sign in as ${dev.email} / ${dev.password} \u2014 an account already exists; do not Register`)}`
+    );
+  }
+  if (mailbox) {
+    lines.push(
+      `  ${"Mailbox".padEnd(10)} ${chalk6.cyan(mailbox.url)}${flag("mailpit")}`,
+      `  ${"".padEnd(10)} ${chalk6.dim("every email the local platform sends (sign-up, verification, password reset) lands here \u2014 nothing leaves your machine")}`
+    );
+  }
+  lines.push(
+    `  ${"Your app".padEnd(10)} ${chalk6.cyan("cd apps/<name> && mesh dev")}   ${chalk6.dim("no app yet? mesh create-app")}`,
+    `  ${"Check-up".padEnd(10)} ${chalk6.cyan("mesh status")}`,
+    ""
+  );
+  return lines;
+}
+function printStartHere(hubRunning, up) {
+  for (const line of startHereLines(hubRunning, up)) console.log(line);
+}
+function portMoveHints() {
+  return /* @__PURE__ */ new Map([
+    [
+      Number(hubPort()),
+      "MESH_HUB_PORT=<free port> mesh start   (or mesh start --no-hub, which starts everything else)"
+    ]
+  ]);
 }
 function repoRootForHubSource() {
   for (let dir = process.cwd(); ; ) {
@@ -18208,6 +18573,10 @@ function registerLocalCommands(program2) {
     "--takeover",
     "re-own a stack that another checkout started (may recreate shared containers with THIS checkout's config)",
     false
+  ).option(
+    "--skip-port-check",
+    "start even though a host port the stack wants is already held (the service that loses the bind will be broken \u2014 use when the holder is something you cannot stop)",
+    false
   ).action(async (opts) => {
     ensureDockerAvailable();
     const foreign = stackOwnedElsewhere();
@@ -18226,6 +18595,15 @@ Re-running start from here may recreate shared containers with this checkout's c
     if (foreign && opts.takeover) {
       logWarn(`Taking over the running stack (previously driven from ${foreign}).`);
     }
+    if (!opts.skipPortCheck && !stackServices().some((s) => s.state === "running")) {
+      const ports = hostPortsOf([...STACK_ENDPOINTS, ...opts.hub ? hubEndpoints() : []]);
+      const conflicts = await findPortConflicts(ports, `${COMPOSE_PROJECT}-`);
+      if (conflicts.length > 0) {
+        throw new MeshCliError(describePortConflicts(conflicts, portMoveHints()), {
+          remediation: { command: "mesh start   # once the port is free" }
+        });
+      }
+    }
     let hubVersion;
     if (opts.hub) {
       if (opts.hubFromSource) {
@@ -18406,6 +18784,7 @@ Re-running start from here may recreate shared containers with this checkout's c
       if (fabric && !fabric.ok) process.exitCode = 1;
       return;
     }
+    printStartHere(hasHub, new Map(probes.map((p) => [p.service, p.up])));
     console.log(chalk6.bold("Containers"));
     for (const service of services) {
       const ok = service.state === "running" && (service.health === void 0 || service.health === "healthy");
@@ -18452,6 +18831,7 @@ var init_local = __esm({
     init_seed();
     init_seed_zitadel();
     init_seed_hub_catalog();
+    init_helpers();
     WAIT_TIMEOUT_MS = 18e4;
     WAIT_POLL_MS = 3e3;
   }
@@ -19646,7 +20026,7 @@ var init_site = __esm({
 });
 
 // libs/mesh-cli/src/commands/stack.ts
-import { execFileSync as execFileSync28 } from "child_process";
+import { execFileSync as execFileSync29 } from "child_process";
 import * as path42 from "path";
 import * as fs35 from "fs";
 import { parse as parseYaml5 } from "yaml";
@@ -19739,7 +20119,7 @@ function readBaseConfigFromYaml(appRoot, stack) {
 }
 function getGitHubUsername() {
   try {
-    const result = execFileSync28("gh", ["api", "user", "--jq", ".login"], {
+    const result = execFileSync29("gh", ["api", "user", "--jq", ".login"], {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
     });
@@ -19748,7 +20128,7 @@ function getGitHubUsername() {
   } catch {
   }
   try {
-    const result = execFileSync28("git", ["config", "user.email"], {
+    const result = execFileSync29("git", ["config", "user.email"], {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
     });
@@ -19834,7 +20214,7 @@ Specify which to base on: mesh stack init --from <stack>`
     if (!opts.adopt) {
       let existing = [];
       try {
-        const raw = execFileSync28("pulumi", ["stack", "ls", "--json"], {
+        const raw = execFileSync29("pulumi", ["stack", "ls", "--json"], {
           cwd: appRoot,
           encoding: "utf-8",
           env: pulumiEnv,
@@ -19858,7 +20238,7 @@ Specify which to base on: mesh stack init --from <stack>`
       logInfo(`Using KMS secrets provider: ${secretsProvider}`);
     }
     try {
-      execFileSync28("pulumi", initArgs, {
+      execFileSync29("pulumi", initArgs, {
         cwd: appRoot,
         env: pulumiEnv,
         stdio: "inherit"
@@ -19875,7 +20255,7 @@ Specify which to base on: mesh stack init --from <stack>`
       }
     }
     try {
-      execFileSync28("pulumi", ["stack", "select", newStack], {
+      execFileSync29("pulumi", ["stack", "select", newStack], {
         cwd: appRoot,
         env: pulumiEnv,
         stdio: ["pipe", "pipe", "pipe"]
@@ -19885,7 +20265,7 @@ Specify which to base on: mesh stack init --from <stack>`
     if (!configExists) {
       let baseConfig = {};
       try {
-        const raw = execFileSync28(
+        const raw = execFileSync29(
           "pulumi",
           ["config", "--json", "--stack", baseStack],
           { cwd: appRoot, env: pulumiEnv, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }
@@ -19903,19 +20283,19 @@ Specify which to base on: mesh stack init --from <stack>`
         if (key === "mesh:deploy") continue;
         try {
           if (entry.objectValue !== void 0) {
-            execFileSync28(
+            execFileSync29(
               "pulumi",
               ["config", "set", key, JSON.stringify(entry.objectValue)],
               { cwd: appRoot, env: pulumiEnv, stdio: ["pipe", "pipe", "pipe"] }
             );
           } else if (entry.value === "true" || entry.value === "false") {
-            execFileSync28(
+            execFileSync29(
               "pulumi",
               ["config", "set", "--type", "bool", key, entry.value],
               { cwd: appRoot, env: pulumiEnv, stdio: ["pipe", "pipe", "pipe"] }
             );
           } else {
-            execFileSync28(
+            execFileSync29(
               "pulumi",
               ["config", "set", key, entry.value],
               { cwd: appRoot, env: pulumiEnv, stdio: ["pipe", "pipe", "pipe"] }
@@ -19928,7 +20308,7 @@ Specify which to base on: mesh stack init --from <stack>`
         const baseEnv = readConfigBlockKey(appRoot, baseStack, "mesh:coreEnv") ?? (baseTenant && baseStack.startsWith(`${baseTenant}-`) ? baseStack.slice(baseTenant.length + 1) : baseStack);
         const setCfg = (args) => {
           try {
-            execFileSync28("pulumi", ["config", "set", ...args], {
+            execFileSync29("pulumi", ["config", "set", ...args], {
               cwd: appRoot,
               env: pulumiEnv,
               stdio: ["pipe", "pipe", "pipe"]
@@ -19977,7 +20357,7 @@ Specify which to base on: mesh stack init --from <stack>`
           `Configured Pulumi.${newStack}.yaml (personal platform env on core '${baseEnv}'${opts.parentZone ? `, DNS zone ${newStack.startsWith(`${baseTenant}-`) ? newStack.slice(baseTenant.length + 1) : newStack}.${opts.parentZone}` : ""})`
         );
       } else {
-        execFileSync28("pulumi", ["config", "set", "--type", "bool", "mesh:deploy", "false"], {
+        execFileSync29("pulumi", ["config", "set", "--type", "bool", "mesh:deploy", "false"], {
           cwd: appRoot,
           env: pulumiEnv,
           stdio: ["pipe", "pipe", "pipe"]
@@ -20007,7 +20387,7 @@ Specify which to base on: mesh stack init --from <stack>`
     const args = ["stack", "rm", name];
     if (opts.yes) args.push("--yes");
     try {
-      execFileSync28("pulumi", args, { cwd: appRoot, env: pulumiEnv, stdio: "inherit" });
+      execFileSync29("pulumi", args, { cwd: appRoot, env: pulumiEnv, stdio: "inherit" });
       logSuccess(`Removed stack ${name}`);
     } catch (err) {
       process.exit(err.status ?? 1);
@@ -20219,12 +20599,12 @@ var init_recover_conversation = __esm({
 });
 
 // libs/mesh-cli/src/utils/temporal-codec.ts
-import { execFileSync as execFileSync29 } from "child_process";
+import { execFileSync as execFileSync30 } from "child_process";
 import { webcrypto as crypto4 } from "node:crypto";
 function resolveTemporalEncodingKeyFromK8s(namespace) {
   const secretName = `${namespace}-temporal-encoding-key`;
   try {
-    const b64 = execFileSync29(
+    const b64 = execFileSync30(
       "kubectl",
       [
         "get",
@@ -23564,7 +23944,7 @@ var init_src4 = __esm({
 import * as fs38 from "fs";
 import * as path45 from "path";
 import { createRequire as createRequire2 } from "module";
-import { execFileSync as execFileSync30 } from "child_process";
+import { execFileSync as execFileSync31 } from "child_process";
 function resolveExtractorPath() {
   try {
     const require2 = createRequire2(import.meta.url);
@@ -23619,7 +23999,7 @@ for (const file of files) {
 process.stdout.write(JSON.stringify(results));
 `;
   try {
-    const result = execFileSync30("npx", ["tsx", "--eval", script], {
+    const result = execFileSync31("npx", ["tsx", "--eval", script], {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "inherit"],
       maxBuffer: 10 * 1024 * 1024
@@ -23661,7 +24041,7 @@ for (const file of files) {
 process.stdout.write(JSON.stringify(results));
 `;
   try {
-    const result = execFileSync30("npx", ["tsx", "--eval", script], {
+    const result = execFileSync31("npx", ["tsx", "--eval", script], {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "inherit"],
       maxBuffer: 10 * 1024 * 1024
@@ -23716,7 +24096,7 @@ for (const file of files) {
 process.stdout.write(JSON.stringify(results));
 `;
   try {
-    const result = execFileSync30("npx", ["tsx", "--eval", script], {
+    const result = execFileSync31("npx", ["tsx", "--eval", script], {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "inherit"],
       maxBuffer: 10 * 1024 * 1024