@devrouter/cli 0.0.22 → 0.0.23

package/dist/dev.js

@@ -161,6 +161,7 @@ This folder is managed by the devrouter CLI.
 - dev init [--write-agents] [--write-skill] [--with-linear]
 - dev -V [--repo <path>] (installed/local version + next upgrade)
 - dev upgrade [version] [--repo <path>]
+- dev setup --yes [--repo <path>] [--json]
 - dev up
 - dev down
 - dev status
@@ -169,10 +170,13 @@ This folder is managed by the devrouter CLI.
 - dev open <name>
 - dev logs [-f] [--tail N]
 - dev repo init
+- dev repo inspect [--repo <path>] [--json]
+- dev repo devcontainer write [--repo <path>] [--dry-run] [--yes] [--json]
+- dev repo devcontainer verify [--repo <path>] [--live] [--yes] [--json]
 - dev repo agents [--with-linear]
 - dev app add --name <name> --host <host.localhost> --protocol <http|tcp> --runtime <host|docker>
 - dev app run <name>
-- dev app exec <name> [--shell] [--env-map TARGET=SOURCE] -- <command>
+- dev app exec <name> [--shell] [--env <env>] -- <command>
 - dev app ls
 - dev app rm <name>
 - dev tls install
@@ -340,6 +344,45 @@ var init_router = __esm({
   }
 });
 
+// src/core/capabilities.ts
+function formatSupportedTcpProtocols() {
+  return SUPPORTED_TCP_PROTOCOLS.join(", ");
+}
+function formatSupportedProtocolsForRuntime(runtime) {
+  return RUNTIME_PROTOCOL_COMPATIBILITY[runtime].join(", ");
+}
+function buildPostgresDependencyUrl(port) {
+  return POSTGRES_DEPENDENCY_URL_TEMPLATE.replace("<port>", String(port));
+}
+function buildPostgresDependencyShadowUrl(port) {
+  return POSTGRES_DEPENDENCY_SHADOW_URL_TEMPLATE.replace("<port>", String(port));
+}
+var SUPPORTED_RUNTIMES, SUPPORTED_PROTOCOLS, SUPPORTED_TCP_PROTOCOLS, DEPENDENCY_ONLY_RUNTIME, RUNTIME_PROTOCOL_COMPATIBILITY, WORKSPACE_PLACEHOLDER, SECRET_MANAGER_ENV_PLACEHOLDER, DEP_ENV_SUFFIXES, POSTGRES_DEPENDENCY_USER, POSTGRES_DEPENDENCY_PASSWORD, POSTGRES_DEPENDENCY_DATABASE, POSTGRES_DEPENDENCY_SHADOW_DATABASE, POSTGRES_DEPENDENCY_URL_TEMPLATE, POSTGRES_DEPENDENCY_SHADOW_URL_TEMPLATE;
+var init_capabilities = __esm({
+  "src/core/capabilities.ts"() {
+    "use strict";
+    init_router();
+    SUPPORTED_RUNTIMES = ["host", "docker", "proxy"];
+    SUPPORTED_PROTOCOLS = ["http", "tcp"];
+    SUPPORTED_TCP_PROTOCOLS = Object.freeze(Object.keys(TCP_PROTOCOL_REGISTRY));
+    DEPENDENCY_ONLY_RUNTIME = "docker";
+    RUNTIME_PROTOCOL_COMPATIBILITY = {
+      host: ["http"],
+      docker: ["http", "tcp"],
+      proxy: ["http", "tcp"]
+    };
+    WORKSPACE_PLACEHOLDER = "${WORKSPACE}";
+    SECRET_MANAGER_ENV_PLACEHOLDER = "{env}";
+    DEP_ENV_SUFFIXES = ["HOST", "PORT", "URL", "SHADOW_URL"];
+    POSTGRES_DEPENDENCY_USER = "prisma";
+    POSTGRES_DEPENDENCY_PASSWORD = "prisma";
+    POSTGRES_DEPENDENCY_DATABASE = "prisma";
+    POSTGRES_DEPENDENCY_SHADOW_DATABASE = "shadow";
+    POSTGRES_DEPENDENCY_URL_TEMPLATE = `postgres://${POSTGRES_DEPENDENCY_USER}:${POSTGRES_DEPENDENCY_PASSWORD}@localhost:<port>/${POSTGRES_DEPENDENCY_DATABASE}`;
+    POSTGRES_DEPENDENCY_SHADOW_URL_TEMPLATE = `postgres://${POSTGRES_DEPENDENCY_USER}:${POSTGRES_DEPENDENCY_PASSWORD}@localhost:<port>/${POSTGRES_DEPENDENCY_SHADOW_DATABASE}`;
+  }
+});
+
 // src/core/host-routes.ts
 function parseUpstream(upstream) {
   const match = UPSTREAM_RE.exec(upstream.trim());
@@ -351,8 +394,8 @@ function parseUpstream(upstream) {
   if (port < 1 || port > 65535) {
     throw new Error(`upstream port must be between 1 and 65535 (got ${port}).`);
   }
-  const upstreamHost = LOOPBACK_HOSTS.has(host) ? "host.docker.internal" : host;
-  return { host, port, upstreamHost };
+  const upstreamHost2 = LOOPBACK_HOSTS.has(host) ? "host.docker.internal" : host;
+  return { host, port, upstreamHost: upstreamHost2 };
 }
 function isPidRunning(pid) {
   if (!pid || pid <= 0) {
@@ -553,31 +596,16 @@ function removeHostRouteById(id) {
     return true;
   });
 }
-function removeHostRouteByName(name, repoPath) {
+function removeHostRoutesWhere(predicate) {
   return withStateLock(() => {
     const routes = listHostRouteState();
-    const matches = routes.filter((route) => {
-      if (route.name !== name) {
-        return false;
-      }
-      if (repoPath && route.repoPath !== repoPath) {
-        return false;
-      }
-      return true;
-    });
-    if (matches.length === 0) {
-      throw new Error(`No host route named '${name}' found.`);
-    }
-    if (matches.length > 1 && !repoPath) {
-      const refs = matches.map((route) => `${route.name} (${route.repoPath})`).join(", ");
-      throw new Error(
-        `Multiple host routes named '${name}' exist. Re-run with --repo to disambiguate: ${refs}`
-      );
+    const removed = routes.filter(predicate);
+    if (removed.length === 0) {
+      return [];
     }
-    const match = matches[0];
-    const next = routes.filter((route) => route.id !== match.id);
-    writeState(next);
-    return match;
+    const removedIds = new Set(removed.map((route) => route.id));
+    writeState(routes.filter((route) => !removedIds.has(route.id)));
+    return removed;
   });
 }
 function listHostRoutes(tlsEnabled) {
@@ -759,6 +787,19 @@ function parseEnvMap(value, pathLabel) {
   }
   return result;
 }
+function isSupportedProtocol(value) {
+  return SUPPORTED_PROTOCOLS.includes(value);
+}
+function isSupportedRuntime(value) {
+  return SUPPORTED_RUNTIMES.includes(value);
+}
+function isSupportedTcpProtocol(value) {
+  return SUPPORTED_TCP_PROTOCOLS.includes(value);
+}
+function runtimeSupportsProtocol(runtime, protocol) {
+  const supportedProtocols = RUNTIME_PROTOCOL_COMPATIBILITY[runtime];
+  return supportedProtocols.includes(protocol);
+}
 function parseDependencies(value, pathLabel) {
   if (value === void 0) {
     return [];
@@ -807,21 +848,21 @@ function parseHostStrategy(value, pathLabel) {
 function parseDockerConfig(value, pathLabel) {
   const objectValue = ensureObject(value, pathLabel);
   ensureAllowedKeys(objectValue, ["service", "internalPort", "composeFiles", "router"], pathLabel);
-  const composeFiles = toStringArray(objectValue.composeFiles, `${pathLabel}.composeFiles`);
+  const composeFiles2 = toStringArray(objectValue.composeFiles, `${pathLabel}.composeFiles`);
   return {
     service: toStringOrThrow(objectValue.service, `${pathLabel}.service`),
     internalPort: toIntegerOrThrow(objectValue.internalPort, `${pathLabel}.internalPort`),
-    composeFiles: composeFiles.length > 0 ? composeFiles : ["docker-compose.yml"],
+    composeFiles: composeFiles2.length > 0 ? composeFiles2 : ["docker-compose.yml"],
     router: objectValue.router === void 0 ? void 0 : toStringOrThrow(objectValue.router, `${pathLabel}.router`)
   };
 }
 function parseDependencyDockerConfig(value, pathLabel) {
   const objectValue = ensureObject(value, pathLabel);
   ensureAllowedKeys(objectValue, ["service", "composeFiles"], pathLabel);
-  const composeFiles = toStringArray(objectValue.composeFiles, `${pathLabel}.composeFiles`);
+  const composeFiles2 = toStringArray(objectValue.composeFiles, `${pathLabel}.composeFiles`);
   return {
     service: toStringOrThrow(objectValue.service, `${pathLabel}.service`),
-    composeFiles: composeFiles.length > 0 ? composeFiles : ["docker-compose.yml"]
+    composeFiles: composeFiles2.length > 0 ? composeFiles2 : ["docker-compose.yml"]
   };
 }
 function parseHostOrThrow(value, pathLabel) {
@@ -863,13 +904,13 @@ function parseApp(value, index) {
       throw new Error(`${pathLabel}.hostRun is not supported when kind=dependency.`);
     }
     const runtime2 = toStringOrThrow(objectValue.runtime, `${pathLabel}.runtime`);
-    if (runtime2 !== "docker") {
-      throw new Error(`${pathLabel}.runtime must be 'docker' when kind=dependency.`);
+    if (runtime2 !== DEPENDENCY_ONLY_RUNTIME) {
+      throw new Error(`${pathLabel}.runtime must be '${DEPENDENCY_ONLY_RUNTIME}' when kind=dependency.`);
     }
     return {
       kind: "dependency",
       name,
-      runtime: "docker",
+      runtime: DEPENDENCY_ONLY_RUNTIME,
       dependencies,
       docker: parseDependencyDockerConfig(objectValue.docker, `${pathLabel}.docker`)
     };
@@ -877,8 +918,14 @@ function parseApp(value, index) {
   const host = parseHostOrThrow(objectValue.host, `${pathLabel}.host`);
   const protocol = toStringOrThrow(objectValue.protocol, `${pathLabel}.protocol`);
   const runtime = toStringOrThrow(objectValue.runtime, `${pathLabel}.runtime`);
+  if (!isSupportedProtocol(protocol)) {
+    throw new Error(`${pathLabel}.protocol must be one of: ${SUPPORTED_PROTOCOLS.join(", ")}.`);
+  }
+  if (!isSupportedRuntime(runtime)) {
+    throw new Error(`${pathLabel}.runtime must be one of: ${SUPPORTED_RUNTIMES.join(", ")}.`);
+  }
   if (runtime === "host") {
-    if (protocol !== "http") {
+    if (!runtimeSupportsProtocol("host", protocol)) {
       throw new Error(`${pathLabel}: host runtime currently supports only protocol=http.`);
     }
     const hostRun = ensureObject(objectValue.hostRun, `${pathLabel}.hostRun`);
@@ -916,10 +963,9 @@ function parseApp(value, index) {
     }
     if (protocol === "tcp") {
       const tcpProtocol = toStringOrThrow(objectValue.tcpProtocol, `${pathLabel}.tcpProtocol`);
-      const supportedProtocols = Object.keys(TCP_PROTOCOL_REGISTRY);
-      if (!supportedProtocols.includes(tcpProtocol)) {
+      if (!isSupportedTcpProtocol(tcpProtocol)) {
         throw new Error(
-          `${pathLabel}.tcpProtocol must be one of: ${supportedProtocols.join(", ")}.`
+          `${pathLabel}.tcpProtocol must be one of: ${formatSupportedTcpProtocols()}.`
         );
       }
       return {
@@ -934,7 +980,7 @@ function parseApp(value, index) {
     }
   }
   if (runtime === "proxy") {
-    if (protocol !== "http" && protocol !== "tcp") {
+    if (!runtimeSupportsProtocol("proxy", protocol)) {
       throw new Error(`${pathLabel}: proxy runtime supports protocol=http or protocol=tcp.`);
     }
     if (objectValue.hostRun !== void 0) {
@@ -950,9 +996,8 @@ function parseApp(value, index) {
     assertUpstreamSpec(upstream, `${pathLabel}.upstream`);
     if (protocol === "tcp") {
       const tcpProtocol = toStringOrThrow(objectValue.tcpProtocol, `${pathLabel}.tcpProtocol`);
-      const supportedProtocols = Object.keys(TCP_PROTOCOL_REGISTRY);
-      if (!supportedProtocols.includes(tcpProtocol)) {
-        throw new Error(`${pathLabel}.tcpProtocol must be one of: ${supportedProtocols.join(", ")}.`);
+      if (!isSupportedTcpProtocol(tcpProtocol)) {
+        throw new Error(`${pathLabel}.tcpProtocol must be one of: ${formatSupportedTcpProtocols()}.`);
       }
       return {
         name,
@@ -987,11 +1032,11 @@ function parseConfig(raw, configPath) {
     const metadata = ensureObject(root.devrouter, `${configPath}.devrouter`);
     ensureAllowedKeys(metadata, ["version"], `${configPath}.devrouter`);
     if (metadata.version !== void 0) {
-      const devrouterVersion = toStringOrThrow(metadata.version, `${configPath}.devrouter.version`);
-      if (!DEVROUTER_VERSION_RE.test(devrouterVersion)) {
+      const devrouterVersion2 = toStringOrThrow(metadata.version, `${configPath}.devrouter.version`);
+      if (!DEVROUTER_VERSION_RE.test(devrouterVersion2)) {
         throw new Error(`${configPath}.devrouter.version must be a semantic version like 0.0.14.`);
       }
-      devrouter = { version: devrouterVersion };
+      devrouter = { version: devrouterVersion2 };
     } else {
       devrouter = {};
     }
@@ -1021,8 +1066,10 @@ function parseConfig(raw, configPath) {
         throw new Error(`${configPath}.secretManager.defaultEnv must be alphanumeric with hyphens.`);
       }
     }
-    if (command.includes("{env}") && !defaultEnv) {
-      throw new Error(`${configPath}.secretManager.defaultEnv is required when command contains {env}.`);
+    if (command.includes(SECRET_MANAGER_ENV_PLACEHOLDER) && !defaultEnv) {
+      throw new Error(
+        `${configPath}.secretManager.defaultEnv is required when command contains ${SECRET_MANAGER_ENV_PLACEHOLDER}.`
+      );
     }
     secretManager = { command, ...defaultEnv ? { defaultEnv } : {} };
   }
@@ -1122,8 +1169,8 @@ function buildAppFromOptions(options) {
   }
   const dependencies = options.dependsOn.map((app) => ({ app }));
   if (kind === "dependency") {
-    if (options.runtime !== void 0 && options.runtime !== "docker") {
-      throw new Error("--runtime must be docker when --kind dependency");
+    if (options.runtime !== void 0 && options.runtime !== DEPENDENCY_ONLY_RUNTIME) {
+      throw new Error(`--runtime must be ${DEPENDENCY_ONLY_RUNTIME} when --kind dependency`);
     }
     if (options.host !== void 0) {
       throw new Error("--host is not supported when --kind dependency");
@@ -1152,7 +1199,7 @@ function buildAppFromOptions(options) {
     return {
       kind: "dependency",
       name: options.name,
-      runtime: "docker",
+      runtime: DEPENDENCY_ONLY_RUNTIME,
       dependencies,
       docker: {
         service: options.service,
@@ -1219,10 +1266,9 @@ function buildAppFromOptions(options) {
     assertUpstreamSpec(options.upstream, "--upstream");
     if (options.protocol === "tcp") {
       const tcpProtocol2 = options.tcpProtocol;
-      const supportedProtocols2 = Object.keys(TCP_PROTOCOL_REGISTRY);
-      if (!tcpProtocol2 || !supportedProtocols2.includes(tcpProtocol2)) {
+      if (!tcpProtocol2 || !isSupportedTcpProtocol(tcpProtocol2)) {
         throw new Error(
-          `--tcp-protocol must be one of: ${supportedProtocols2.join(", ")} when --runtime proxy --protocol tcp`
+          `--tcp-protocol must be one of: ${formatSupportedTcpProtocols()} when --runtime proxy --protocol tcp`
         );
       }
       return {
@@ -1266,10 +1312,9 @@ function buildAppFromOptions(options) {
       docker
     };
   }
-  const tcpProtocol = options.tcpProtocol ?? "postgres";
-  const supportedProtocols = Object.keys(TCP_PROTOCOL_REGISTRY);
-  if (!supportedProtocols.includes(tcpProtocol)) {
-    throw new Error(`--tcp-protocol must be one of: ${supportedProtocols.join(", ")}`);
+  const tcpProtocol = options.tcpProtocol ?? DEFAULT_TCP_PROTOCOL;
+  if (!isSupportedTcpProtocol(tcpProtocol)) {
+    throw new Error(`--tcp-protocol must be one of: ${formatSupportedTcpProtocols()}`);
   }
   return {
     name: options.name,
@@ -1410,7 +1455,7 @@ function resolveAppDependencies(config, app) {
   }
   return results;
 }
-var import_node_fs4, import_node_path4, import_yaml2, CONFIG_FILE_NAME, VALID_HOSTNAME_RE, DEVROUTER_VERSION_RE, VALID_ENV_NAME_RE, VALID_ENV_VAR_RE, WORKSPACE_PLACEHOLDER, UPSTREAM_TEMPLATE_RE, MAX_COMMAND_LENGTH, DEFAULT_HOST_STRATEGY;
+var import_node_fs4, import_node_path4, import_yaml2, CONFIG_FILE_NAME, DEFAULT_TCP_PROTOCOL, VALID_HOSTNAME_RE, DEVROUTER_VERSION_RE, VALID_ENV_NAME_RE, VALID_ENV_VAR_RE, UPSTREAM_TEMPLATE_RE, MAX_COMMAND_LENGTH, DEFAULT_HOST_STRATEGY;
 var init_repo_config = __esm({
   "src/core/repo-config.ts"() {
     "use strict";
@@ -1418,14 +1463,14 @@ var init_repo_config = __esm({
     import_node_path4 = __toESM(require("path"));
     import_yaml2 = __toESM(require("yaml"));
     init_host_routes();
-    init_router();
     init_workspace();
+    init_capabilities();
     CONFIG_FILE_NAME = ".devrouter.yml";
+    DEFAULT_TCP_PROTOCOL = "postgres";
     VALID_HOSTNAME_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*\.localhost$/;
     DEVROUTER_VERSION_RE = /^\d+\.\d+\.\d+$/;
     VALID_ENV_NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/i;
     VALID_ENV_VAR_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
-    WORKSPACE_PLACEHOLDER = "${WORKSPACE}";
     UPSTREAM_TEMPLATE_RE = /^(?:\$\{WORKSPACE\}|[a-zA-Z0-9._-])+:\d{1,5}$/;
     MAX_COMMAND_LENGTH = 4096;
     DEFAULT_HOST_STRATEGY = {
@@ -1458,6 +1503,15 @@ function renderCommandIntentSection() {
   );
   return ["Command intent reference:", ...lines].join("\n");
 }
+function quotedUnion(values) {
+  return values.map((value) => `"${value}"`).join(" | ");
+}
+function formatDepEnvNames() {
+  return DEP_ENV_SUFFIXES.map((suffix) => `\`{PREFIX}_${suffix}\``).join(", ");
+}
+function formatProtocolRule(runtime) {
+  return formatSupportedProtocolsForRuntime(runtime).replace(", ", " or ");
+}
 function buildOnboardingPrompt(options = {}) {
   const repoPath = resolveRepoPath(options.repo);
   const entriesJson = normalizeEntriesJson(options.entriesJson);
@@ -1484,8 +1538,8 @@ function buildOnboardingPrompt(options = {}) {
     "- version: 1 (required)",
     "- devrouter.version: semantic version string (recommended; required for `dev -V`/`dev upgrade`)",
     "- project.name: string (optional)",
-    "- secretManager.command: string (optional; SM command including trailing `--` boundary; supports `{env}` template placeholder)",
-    "- secretManager.defaultEnv: string (optional; fallback env for `{env}` template; required when command contains `{env}`)",
+    `- secretManager.command: string (optional; SM command including trailing \`--\` boundary; supports \`${SECRET_MANAGER_ENV_PLACEHOLDER}\` template placeholder)`,
+    `- secretManager.defaultEnv: string (optional; fallback env for \`${SECRET_MANAGER_ENV_PLACEHOLDER}\` template; required when command contains \`${SECRET_MANAGER_ENV_PLACEHOLDER}\`)`,
     "- apps: array (required)",
     "",
     "Canonical valid skeleton:",
@@ -1502,8 +1556,8 @@ function buildOnboardingPrompt(options = {}) {
     '- dependencies: [{ app: "<name>", envMap: { TARGET: "SOURCE" } }] (optional; envMap aliases per-dep vars to app-expected names)',
     "- if kind=app:",
     "  - host: <name>.localhost (single-label or multi-segment, for example `api.v2.app.localhost`)",
-    '  - protocol: "http" | "tcp"',
-    '  - runtime: "host" | "docker" | "proxy"',
+    `  - protocol: ${quotedUnion(SUPPORTED_PROTOCOLS)}`,
+    `  - runtime: ${quotedUnion(SUPPORTED_RUNTIMES)}`,
     "- if kind=app and runtime=host:",
     "  - hostRun.command: string",
     "  - hostRun.cwd: string",
@@ -1517,32 +1571,32 @@ function buildOnboardingPrompt(options = {}) {
     "  - optional docker.router: string",
     "- if kind=app and runtime=proxy:",
     '  - upstream: "host:port" (an already-running port, e.g. a devcontainer published on 127.0.0.1:3000, or a container reachable by name on a shared Docker network such as `derivatives-db:5432`)',
-    "  - upstream may use the `${WORKSPACE}` placeholder (e.g. `${WORKSPACE}-app:3000`) to target a per-workspace devcontainer alias; it is substituted with the resolved workspace token at runtime and re-validated. Do NOT put `${WORKSPACE}` in `host` (rejected) \u2014 the host is auto-namespaced.",
+    `  - upstream may use the \`${WORKSPACE_PLACEHOLDER}\` placeholder (e.g. \`${WORKSPACE_PLACEHOLDER}-app:3000\`) to target a per-workspace devcontainer alias; it is substituted with the resolved workspace token at runtime and re-validated. Do NOT put \`${WORKSPACE_PLACEHOLDER}\` in \`host\` (rejected) \u2014 the host is auto-namespaced.`,
     "  - protocol=http registers an HTTP route; protocol=tcp registers a TLS-SNI TCP route and additionally requires tcpProtocol",
     "  - do not set hostRun/docker/dependencies (proxy only registers a route to the upstream)",
     "  - loopback hosts (localhost/127.0.0.1/0.0.0.0) are rewritten to host.docker.internal for Traefik",
     "- if kind=app and protocol=tcp:",
-    '  - tcpProtocol: "postgres" | "redis" | "mariadb" | "mysql"',
+    `  - tcpProtocol: ${quotedUnion(SUPPORTED_TCP_PROTOCOLS)}`,
     "- if kind=dependency:",
-    '  - runtime: "docker"',
+    `  - runtime: "${DEPENDENCY_ONLY_RUNTIME}"`,
     "  - docker.service: string",
     "  - docker.composeFiles: string[]",
     "  - do not set host/protocol/tcpProtocol/hostRun/docker.internalPort/docker.router",
     "",
     "Validation rules to enforce:",
     "- kind=app host must end with .localhost",
-    "- kind=app runtime=host supports protocol=http only",
-    "- kind=app runtime=proxy supports protocol=http or tcp, requires upstream (host:port), and has no dependencies; protocol=tcp also requires tcpProtocol",
-    "- kind=app protocol=tcp requires runtime=docker or proxy, and tcpProtocol (postgres, redis, mariadb, mysql)",
-    "- kind=dependency requires runtime=docker and non-routed docker config only",
+    `- kind=app runtime=host supports protocol=${formatProtocolRule("host")} only`,
+    `- kind=app runtime=proxy supports protocol=${formatProtocolRule("proxy")}, requires upstream (host:port), and has no dependencies; protocol=tcp also requires tcpProtocol`,
+    `- kind=app protocol=tcp requires runtime=docker or proxy, and tcpProtocol (${formatSupportedTcpProtocols()})`,
+    `- kind=dependency requires runtime=${DEPENDENCY_ONLY_RUNTIME} and non-routed docker config only`,
     "- unknown keys are not allowed (strict schema)",
     "",
     "Docker compose file requirements:",
     "- Every service that acts as a dependency MUST define a healthcheck \u2014 devrouter uses `docker compose up --wait` which blocks until healthy; without a healthcheck the wait returns immediately and the dependent app may start before the service is ready.",
     "- Services MUST NOT publish host ports (`ports:` mapping) for any port owned by devrouter (80, 443, 5432) \u2014 Traefik owns these; conflicts cause bind failures.",
     "- Services SHOULD NOT publish host ports at all \u2014 devrouter handles external routing via Traefik labels; publishing ports creates conflicts when running multiple repos.",
-    '- For TCP dependencies of host apps, devrouter automatically publishes a random host port and injects per-dep deterministic env vars: `{PREFIX}_HOST`, `{PREFIX}_PORT`, `{PREFIX}_URL` (protocol-specific), and `{PREFIX}_SHADOW_URL` (postgres only). `{PREFIX} = dep.name.toUpperCase().replace(/-/g, "_")`.',
-    "- For postgres deps, `{PREFIX}_URL=postgres://prisma:prisma@localhost:<port>/prisma` and `{PREFIX}_SHADOW_URL=postgres://prisma:prisma@localhost:<port>/shadow`. Use config-level `envMap` on the dependency reference to alias these to app-expected names (e.g. `DATABASE_URL: DB_URL`).",
+    `- For TCP dependencies of host apps, devrouter automatically publishes a random host port and injects per-dep deterministic env vars: ${formatDepEnvNames()}. \`{PREFIX}_URL\` is protocol-specific, \`{PREFIX}_SHADOW_URL\` is postgres only. \`{PREFIX} = dep.name.toUpperCase().replace(/-/g, "_")\`.`,
+    `- For postgres deps, \`{PREFIX}_URL=${POSTGRES_DEPENDENCY_URL_TEMPLATE}\` and \`{PREFIX}_SHADOW_URL=${POSTGRES_DEPENDENCY_SHADOW_URL_TEMPLATE}\`. Use config-level \`envMap\` on the dependency reference to alias these to app-expected names (e.g. \`DATABASE_URL: DB_URL\`).`,
     "- The Postgres service in docker-compose must use matching credentials (`POSTGRES_USER=prisma`, `POSTGRES_PASSWORD=prisma`, `POSTGRES_DB=prisma`) and create the shadow database (e.g. via an init script or the app's migration tool). If existing credentials differ, either update them to match or override via `envMap` aliasing.",
     "- If you changed postgres credentials/database defaults on an existing persistent volume, startup may still fail due to stale data. Recommend reconciling credentials or recreating volumes (for example `docker compose down -v`) when safe.",
     "- The TLS/SNI route on :5432 remains available for tools supporting `sslnegotiation=direct` (psql 17+, pgAdmin).",
@@ -1556,7 +1610,7 @@ function buildOnboardingPrompt(options = {}) {
     "- Host-runtime dependencies are NOT auto-started in v1 (must be started manually).",
     "- kind=dependency entries are dependency-only: they do not create routes and cannot be direct targets for `dev app run`, `dev app exec`, or `dev open`.",
     "- kind=dependency services are started/stopped as declared in compose (no Traefik labels added, no env/port injection).",
-    '- For TCP dependencies of host apps, devrouter publishes a random host port and injects per-dep deterministic vars: `{PREFIX}_HOST=localhost`, `{PREFIX}_PORT=<port>`, `{PREFIX}_URL` (protocol-specific), `{PREFIX}_SHADOW_URL` (postgres only). `{PREFIX} = dep.name.toUpperCase().replace(/-/g, "_")`.',
+    `- For TCP dependencies of host apps, devrouter publishes a random host port and injects per-dep deterministic vars: \`{PREFIX}_HOST=localhost\`, \`{PREFIX}_PORT=<port>\`, \`{PREFIX}_URL\` (protocol-specific), \`{PREFIX}_SHADOW_URL\` (postgres only). \`{PREFIX} = dep.name.toUpperCase().replace(/-/g, "_")\`.`,
     "- Config-level `envMap` on dependency references aliases per-dep vars to app-expected names. Example: `envMap: { DATABASE_URL: DB_URL }` maps per-dep `DB_URL` to `DATABASE_URL` in the app process.",
     "- If the repo's Postgres docker-compose service uses different credentials than the injected defaults (`prisma:prisma`), flag this to the user and recommend aligning the compose env vars or using `envMap` aliasing.",
     "- Postgres multiplexing on shared :5432 requires TLS/SNI (useful for psql 17+, pgAdmin, not standard app clients).",
@@ -1566,17 +1620,17 @@ function buildOnboardingPrompt(options = {}) {
     "- `envMap` on dependency references (config-level) aliases per-dep vars after dependency env resolution. `envMap` fails fast when source var is missing.",
     "",
     "Workspace isolation (parallel git worktrees / agents):",
-    '- A "workspace token" lets several worktrees of one repo run in parallel without host/route collisions. It is a single identity spanning three layers: the devpod workspace id (`devpod up --id <ws>`), the routes devrouter registers, and the `${WORKSPACE}` placeholder in `.devrouter.yml` upstreams + the devcontainer compose network alias.',
+    `- A "workspace token" lets several worktrees of one repo run in parallel without host/route collisions. It is a single identity spanning three layers: the devpod workspace id (\`devpod up --id <ws>\`), the routes devrouter registers, and the \`${WORKSPACE_PLACEHOLDER}\` placeholder in \`.devrouter.yml\` upstreams + the devcontainer compose network alias.`,
     "- Token resolution precedence: `--workspace <slug>` flag > `DEVROUTER_WORKSPACE` env var > auto-derived from a linked git worktree branch (sanitized: lowercase, non-alphanumeric \u2192 `-`, capped at 32 chars) > none. The primary checkout resolves to no token and routes exactly as before (fully back-compatible).",
-    "- When a workspace is active: hosts auto-namespace (`web.localhost` \u2192 `web.<ws>.localhost`), `${WORKSPACE}` in `upstream` is substituted with the token, and the docker `router` key is suffixed per workspace. The runtime config is computed in memory only \u2014 the committed `.devrouter.yml` is never rewritten.",
+    `- When a workspace is active: hosts auto-namespace (\`web.localhost\` \u2192 \`web.<ws>.localhost\`), \`${WORKSPACE_PLACEHOLDER}\` in \`upstream\` is substituted with the token, and the docker \`router\` key is suffixed per workspace. The runtime config is computed in memory only \u2014 the committed \`.devrouter.yml\` is never rewritten.`,
     "- TLS: namespaced hosts (`web.<ws>.localhost`) are not covered by the `*.localhost` wildcard; devrouter auto-extends the mkcert cert SANs for active hosts when TLS is enabled.",
-    "- Lifecycle: `dev workspace up <branch>` (create worktree + devpod + routes), `dev workspace ls` (list worktrees/tokens/route counts), `dev workspace down <workspace|branch>` (free routes + stop devpod + remove worktree). `dev doctor` reclaims orphaned workspace proxy routes whose worktree dir was removed without `dev workspace down`.",
-    "- devcontainer integration: the devcontainer compose service exposes a devnet alias `${WORKSPACE}-app` (default `WORKSPACE=<project>` in `devcontainer.env`), and the proxy app uses `upstream: ${WORKSPACE}-app:<port>`. Spinning up workspace `feat-a` \u2192 alias `feat-a-app`, host `app.feat-a.localhost`.",
+    "- Lifecycle: `dev workspace up <branch>` (create worktree + devpod + routes), `dev workspace ls` (list worktrees/tokens/route counts), `dev workspace down <workspace|branch>` (free routes + stop devpod + remove worktree). `dev doctor` reports orphaned workspace proxy routes whose worktree dir was removed without `dev workspace down`.",
+    `- devcontainer integration: the devcontainer compose service exposes a devnet alias \`${WORKSPACE_PLACEHOLDER}-app\` (default \`WORKSPACE=<project>\` in \`devcontainer.env\`), and the proxy app uses \`upstream: ${WORKSPACE_PLACEHOLDER}-app:<port>\`. Spinning up workspace \`feat-a\` \u2192 alias \`feat-a-app\`, host \`app.feat-a.localhost\`.`,
     "",
     "Secret Manager Integration (config-based):",
     "- Optional top-level `secretManager.command` in `.devrouter.yml` wraps `dev app run` and `dev app exec` commands with the SM command and re-applies devrouter-injected dep env vars after the SM boundary via `env KEY=VAL` prefix.",
-    '- Example config: `secretManager: { command: "infisical run --env {env} --", defaultEnv: "dev" }`.',
-    "- `{env}` template placeholder in `secretManager.command` is resolved at runtime. `defaultEnv` provides the fallback; `--env` CLI flag overrides it.",
+    `- Example config: \`secretManager: { command: "infisical run --env ${SECRET_MANAGER_ENV_PLACEHOLDER} --", defaultEnv: "dev" }\`.`,
+    `- \`${SECRET_MANAGER_ENV_PLACEHOLDER}\` template placeholder in \`secretManager.command\` is resolved at runtime. \`defaultEnv\` provides the fallback; \`--env\` CLI flag overrides it.`,
     "- When configured, the effective command becomes: `<secretManager.command> env {PREFIX}_URL=<val> ... <user-command>`.",
     "- This ensures devrouter-injected vars take precedence over SM-defined values without manual forwarding.",
     "- Config-level `envMap` targets are also included in the re-injection set.",
@@ -1596,21 +1650,30 @@ function buildOnboardingPrompt(options = {}) {
     "- Warning: Do not run migration/seed until env probe confirms expected DB variables and values.",
     "",
     "Required workflow:",
-    "1) Inspect repository structure first (compose files, scripts, app folders, existing dev docs).",
-    "2) Create/update REPO_PATH/.devrouter.yml. If required for compliance, make only minimal related edits (for example docker-compose.yml, db init scripts, or existing dev script wiring).",
-    "3) For host apps, prefer existing repo dev scripts (pnpm dev/npm run dev/etc.) over handcrafted command chains.",
-    "4) If any tcp/postgres app is configured, run `dev up` and `dev tls install` before runtime validation.",
-    "5) Keep edits minimal, explicit, and idempotent. Do not modify unrelated services.",
-    "6) If required info is missing or ambiguous, stop and ask targeted questions.",
+    "1) Run `dev setup --yes --json` for devrouter-owned machine state; use `dev doctor --repo <REPO_PATH> --json` to diagnose missing prerequisites without mutation.",
+    "2) Run `dev repo inspect --repo <REPO_PATH> --json` before editing files.",
+    "3) For the supported Node/pnpm/Postgres devcontainer shape, run `dev repo devcontainer write --repo <REPO_PATH> --dry-run --json`, review the plan, then run `dev repo devcontainer write --repo <REPO_PATH> --yes`.",
+    "4) For unsupported shapes or custom existing files, make minimal manual edits and explain the assumptions.",
+    "5) Verify static evidence with `dev repo devcontainer verify --repo <REPO_PATH> --json`; after the devcontainer is running, use `dev repo devcontainer verify --repo <REPO_PATH> --live --yes --json` for route probes.",
+    "6) Keep edits minimal, explicit, and idempotent. Do not modify unrelated services.",
+    "7) If required info is missing or ambiguous, stop and ask targeted questions.",
+    "",
+    "Validation commands to run/report for the devcontainer path:",
+    "- dev setup --yes --json",
+    "- dev doctor --repo <REPO_PATH> --json",
+    "- dev repo inspect --repo <REPO_PATH> --json",
+    "- dev repo devcontainer write --repo <REPO_PATH> --dry-run --json",
+    "- dev repo devcontainer write --repo <REPO_PATH> --yes",
+    "- dev repo devcontainer verify --repo <REPO_PATH> --json",
+    "- After `devpod up <REPO_PATH>`: dev repo devcontainer verify --repo <REPO_PATH> --live --yes --json",
     "",
-    "Validation commands to run/report:",
-    "- dev up",
-    "- If tcp/postgres exists: dev tls install",
+    "Validation commands to run/report for host/docker runtime apps:",
+    "- dev setup --yes --json",
+    "- dev doctor --repo <REPO_PATH> --json",
     "- dev app ls --repo <REPO_PATH>",
     "- For each entry (when safe): dev app run <name> --repo <REPO_PATH> --yes",
     "- Run one-shot commands with dep env: dev app exec <name> --repo <REPO_PATH> --yes -- <command>",
     "- Probe effective env before migration/seed: dev app exec <name> --repo <REPO_PATH> --yes -- printenv DB_URL DB_HOST DB_PORT DB_SHADOW_URL",
-    "- dev doctor --repo <REPO_PATH> --json",
     "- dev ls",
     "- For HTTP entries: curl -I http://<host>",
     '- For TCP postgres entries: provide connection hint (example: psql "... sslmode=require")',
@@ -1654,6 +1717,7 @@ var COMMAND_INTENTS;
 var init_ai_prompt = __esm({
   "src/core/ai-prompt.ts"() {
     "use strict";
+    init_capabilities();
     init_repo_config();
     COMMAND_INTENTS = [
       {
@@ -1668,6 +1732,10 @@ var init_ai_prompt = __esm({
         command: "dev upgrade [version]",
         purpose: "Show upgrade targets from .devrouter.yml devrouter.version and print target adaptation prompt."
       },
+      {
+        command: "dev setup",
+        purpose: "Run first-time devrouter machine setup and report structured diagnostics."
+      },
       {
         command: "dev up",
         purpose: "Start shared Traefik and ensure the shared devnet network."
@@ -1697,6 +1765,18 @@ var init_ai_prompt = __esm({
         command: "dev repo init",
         purpose: "Create `.devrouter.yml` in a target repository."
       },
+      {
+        command: "dev repo inspect",
+        purpose: "Inspect package, scripts, compose services, env names, devcontainer, devrouter config, and agent guidance for onboarding."
+      },
+      {
+        command: "dev repo devcontainer write",
+        purpose: "Dry-run or write conservative managed Node/pnpm/Postgres devcontainer/devrouter scaffold files."
+      },
+      {
+        command: "dev repo devcontainer verify",
+        purpose: "Emit static onboarding evidence, or live route probes with --live --yes."
+      },
       {
         command: "dev app add",
         purpose: "Add or update one app entry in `.devrouter.yml`."
@@ -1954,51 +2034,76 @@ Local dev routing via a shared Traefik reverse proxy. Provides stable \`*.localh
 \`\`\`yaml
 version: 1
 devrouter:
-  version: <semver>         # required for dev -V / dev upgrade
+  version: <semver> # required for dev -V / dev upgrade
 project:
-  name: <string>            # optional
+  name: <string> # optional
 apps:
-  - name: <string>          # unique within repo
-    kind: app | dependency   # optional, default: app
-    dependencies:            # optional
+  - name: <string> # unique within repo
+    kind: app | dependency # optional, default: app
+    dependencies: # optional
       - app: <other-name>
+        envMap: # optional; maps target env var name -> per-dep source var name
+          DATABASE_URL: <UPPER_DEP_NAME>_URL
 
     # if kind=app:
     host: <name>.localhost
     protocol: http | tcp
-    runtime: host | docker
+    runtime: host | docker | proxy
+
+    # if kind=app and runtime=proxy (protocol http or tcp):
+    upstream: 127.0.0.1:3000 # already-running port to route to; no lifecycle/deps
+    # Loopback (127.0.0.1/localhost) -> host.docker.internal (a published host
+    # port). A non-loopback name is passed verbatim and resolved over devnet \u2014
+    # so a devcontainer container ON devnet (with a network alias) can be fronted
+    # by NAME with NO published host port: upstream: <alias>:3000. This is the
+    # collision-free way to run many apps at once (each its own *.localhost).
+    # upstream may use the \${WORKSPACE} placeholder (e.g. \${WORKSPACE}-app:3000)
+    # to target a per-workspace devcontainer alias \u2014 substituted with the resolved
+    # workspace token at runtime. See "Workspace isolation" below. Do NOT put
+    # \${WORKSPACE} in \`host\` (rejected); the host is auto-namespaced.
+    #
+    # proxy + tcp (front a DB in an externally-managed container, e.g. a
+    # devcontainer's Postgres on devnet) \u2014 no per-DB host port:
+    #   protocol: tcp
+    #   tcpProtocol: postgres        # selects shared entrypoint :5432
+    #   upstream: <db-alias>:5432    # devnet alias of the DB container
+    # Requires \`dev tls install\` (SNI is read from the TLS ClientHello). Connect
+    # with direct-SSL so the ClientHello carries SNI, e.g.:
+    #   psql "host=db.<app>.localhost port=5432 sslmode=require sslnegotiation=direct ..."
 
     # if kind=app and runtime=host (protocol must be http):
     hostRun:
       command: <string>
-      cwd: <string>          # relative to repo root, must not escape it
-      portTimeout: 120       # seconds, optional
+      cwd: <string> # relative to repo root, must not escape it
+      portTimeout: 120 # seconds, optional
       strategy:
         type: auto
         denyPorts: [80, 443, 5432]
-        allowPortRange: "1024-65535"
+        allowPortRange: '1024-65535'
 
     # if kind=app and runtime=docker:
     docker:
       service: <string>
       internalPort: <number>
-      composeFiles: [<string>]  # relative to repo root
-      router: <string>          # optional
+      composeFiles: [<string>] # relative to repo root
+      router: <string> # optional
 
     # if kind=app and protocol=tcp:
-    tcpProtocol: postgres    # required; one of: postgres, redis, mariadb, mysql
+    tcpProtocol: postgres # required; runtime must be docker OR proxy
 
     # if kind=dependency:
     runtime: docker
     docker:
       service: <string>
-      composeFiles: [<string>]  # relative to repo root
+      composeFiles: [<string>] # relative to repo root
 \`\`\`
 
 Validation rules:
+
 - \`kind=app\`: \`host\` must end with \`.localhost\`
 - \`kind=app\`: \`runtime=host\` supports \`protocol=http\` only
-- \`kind=app\`: \`protocol=tcp\` requires \`runtime=docker\` and \`tcpProtocol\` (postgres, redis, mariadb, mysql)
+- \`kind=app\`: \`runtime=proxy\` supports \`protocol=http\` or \`protocol=tcp\`, requires \`upstream\` (\`host:port\`), and forbids \`hostRun\`/\`docker\`/\`dependencies\` (it only registers a route to an externally-managed upstream). \`protocol=tcp\` additionally requires \`tcpProtocol\` and TLS (\`dev tls install\`)
+- \`kind=app\`: \`protocol=tcp\` requires \`runtime=docker\` (devrouter-managed container) or \`runtime=proxy\` (externally-managed upstream), plus a supported \`tcpProtocol\` (postgres/redis/mariadb/mysql)
 - \`kind=dependency\`: must use \`runtime=docker\` and does not allow routed fields (\`host\`/\`protocol\`/\`tcpProtocol\`/\`hostRun\`/\`docker.internalPort\`/\`docker.router\`)
 - Unknown keys rejected (strict schema)
 
@@ -2006,13 +2111,14 @@ Validation rules:
 
 - **Healthcheck required**: every dependency service must define a \`healthcheck\`. \`docker compose up --wait\` blocks until healthy; without one, wait returns immediately.
 - **No published ports**: services must not publish host ports for devrouter-owned ports (80, 443, 5432). Avoid publishing ports at all -- devrouter handles routing via Traefik.
-- **Postgres credentials**: use \`POSTGRES_USER=prisma\`, \`POSTGRES_PASSWORD=prisma\`, \`POSTGRES_DB=prisma\` and create a \`shadow\` database. devrouter injects \`DATABASE_URL\` / \`SHADOW_DATABASE_URL\` with these fixed credentials.
+- **Postgres credentials**: use \`POSTGRES_USER=prisma\`, \`POSTGRES_PASSWORD=prisma\`, \`POSTGRES_DB=prisma\` and create a \`shadow\` database. devrouter injects per-dep \`{PREFIX}_URL\` / \`{PREFIX}_SHADOW_URL\` with these credentials.
 - **Persistent volume warning**: if postgres defaults changed on an existing volume, reconcile credentials/data or recreate volumes when safe (for example \`docker compose down -v\`).
 
 Example healthcheck:
+
 \`\`\`yaml
 healthcheck:
-  test: ["CMD-SHELL", "pg_isready -U prisma -d prisma"]
+  test: ['CMD-SHELL', 'pg_isready -U prisma -d prisma']
   interval: 5s
   timeout: 3s
   retries: 20
@@ -2020,40 +2126,61 @@ healthcheck:
 
 ## Env var injection
 
-When a host app depends on a TCP/Postgres Docker service, \`dev app run\` and \`dev app exec\` inject:
+When a host app depends on a TCP Docker service, \`dev app run\` and \`dev app exec\` inject per-dep deterministic vars (where \`{PREFIX} = dep.name.toUpperCase().replace(/-/g, "_")\`):
 
-| Variable | Value |
-|---|---|
-| \`<UPPER_NAME>_HOST\` | \`localhost\` |
-| \`<UPPER_NAME>_PORT\` | random mapped port |
-| \`DATABASE_URL\` | \`postgres://prisma:prisma@localhost:<port>/prisma\` (postgres deps only) |
-| \`SHADOW_DATABASE_URL\` | \`postgres://prisma:prisma@localhost:<port>/shadow\` (postgres deps only) |
+| Variable                | Value                                                       |
+| ----------------------- | ----------------------------------------------------------- |
+| \`{PREFIX}_HOST\`         | \`localhost\`                                                 |
+| \`{PREFIX}_PORT\`         | random mapped port                                          |
+| \`{PREFIX}_URL\`          | protocol-specific URL (postgres, redis, mysql/mariadb)      |
+| \`{PREFIX}_SHADOW_URL\`   | \`postgres://prisma:prisma@localhost:<port>/shadow\` (postgres only) |
 
 Host apps also receive \`PORT\` (random free port), \`HOSTNAME=0.0.0.0\`, \`HOST=0.0.0.0\`.
 
-\`dev app exec --env-map TARGET=SOURCE\` applies deterministic alias mapping after dependency env injection (for example \`DATABASE_URI=DATABASE_URL\`).
+Config-level \`envMap\` on dependency references aliases per-dep vars to app-expected names (for example \`DATABASE_URL: DB_URL\` maps the per-dep \`DB_URL\` to \`DATABASE_URL\`).
+
+## Workspace isolation (parallel git worktrees / agents)
+
+Run several worktrees of one repo in parallel without host/route collisions. A **workspace token** is a single identity spanning three layers: the devpod workspace id (\`devpod up --id <ws>\`), the routes devrouter registers, and the \`\${WORKSPACE}\` placeholder in \`.devrouter.yml\` upstreams + the devcontainer compose network alias.
+
+- **Token resolution** (precedence): \`--workspace <slug>\` flag > \`DEVROUTER_WORKSPACE\` env var > auto-derived from a linked git worktree branch (sanitized: lowercase, non-alphanumeric \u2192 \`-\`, capped at 32 chars) > none. The primary checkout resolves to no token and routes exactly as before (back-compatible).
+- **When active**: hosts auto-namespace (\`web.localhost\` \u2192 \`web.<ws>.localhost\`), \`\${WORKSPACE}\` in \`upstream\` is substituted with the token, and the docker \`router\` key is suffixed per workspace. The runtime config is computed in memory only \u2014 the committed \`.devrouter.yml\` is never rewritten.
+- **TLS**: namespaced hosts (\`web.<ws>.localhost\`) are not covered by the \`*.localhost\` wildcard; devrouter auto-extends the mkcert cert SANs for active hosts when TLS is enabled.
+- **devcontainer integration**: the devcontainer compose service exposes a devnet alias \`\${WORKSPACE}-app\` (default \`WORKSPACE=<project>\` in \`devcontainer.env\`); the proxy app uses \`upstream: \${WORKSPACE}-app:<port>\`. Workspace \`feat-a\` \u2192 alias \`feat-a-app\`, host \`app.feat-a.localhost\`.
+- **Lifecycle**: \`dev workspace up <branch>\` (create worktree + devpod + routes), \`dev workspace ls\` (list worktrees/tokens/route counts), \`dev workspace down <workspace|branch>\` (free routes by state-file workspace tag + stop devpod + remove worktree). \`dev doctor\` reports orphaned workspace proxy routes whose worktree dir was removed without \`dev workspace down\`.
 
 ## Secret manager interop (Infisical/Doppler)
 
+- Config-based SM integration: set \`secretManager.command\` in \`.devrouter.yml\` (include trailing \`--\`). devrouter wraps commands and re-injects dep env vars after the SM boundary.
+- \`secretManager.defaultEnv\`: optional fallback environment for \`{env}\` template in command string.
+- \`{env}\` template placeholder: \`secretManager.command: "infisical run --env {env} --"\` resolved at runtime. \`--env <env>\` CLI flag overrides \`defaultEnv\`.
+- Example config:
+  \`\`\`yaml
+  secretManager:
+    command: infisical run --env {env} --
+    defaultEnv: dev
+  \`\`\`
+- Use \`envMap\` on dependency references to alias per-dep vars to app-expected names:
+  \`\`\`yaml
+  dependencies:
+    - app: db
+      envMap:
+        DATABASE_URL: DB_URL
+        DIRECT_URL: DB_URL
+        SHADOW_DATABASE_URL: DB_SHADOW_URL
+  \`\`\`
 - Prefer argv-safe command forms. Do not wrap \`infisical run\` or \`doppler run\` in \`sh -lc\` unless shell expansion is strictly required.
 - Canonical Infisical migrate command:
-\`dev app exec <app> --yes --env-map DATABASE_URI=DATABASE_URL -- infisical run --projectId <id> --env=<env> -- pnpm payload migrate\`
-- Canonical Infisical seed command:
-\`dev app exec <app> --yes --env-map DATABASE_URI=DATABASE_URL -- infisical run --projectId <id> --env=<env> -- pnpm payload seed\`
+  \`dev app exec <app> --yes -- infisical run --projectId <id> --env=<env> -- pnpm payload migrate\`
 - Canonical env probe command (run before migrate/seed):
-\`dev app exec <app> --yes --env-map DATABASE_URI=DATABASE_URL -- printenv DATABASE_URL DATABASE_URI DB_HOST DB_PORT SHADOW_DATABASE_URL\`
+  \`dev app exec <app> --yes -- printenv DB_URL DB_HOST DB_PORT DB_SHADOW_URL\`
 - Canonical Doppler migrate command:
-\`dev app exec <app> --yes --env-map DATABASE_URI=DATABASE_URL -- doppler run -- pnpm payload migrate\`
-- Precedence best practice: avoid defining local \`DATABASE_URL\` / \`DATABASE_URI\` in Infisical/Doppler when you expect devrouter local DB injection.
-- Precedence best practice: store remote/prod URLs under non-conflicting names (for example \`PROD_DATABASE_URL\`) and map intentionally in app config/scripts.
-- Precedence best practice: if secret manager must define \`DATABASE_URL\`, run the env probe and verify values before any migration/seed.
-- Avoid pre-wrapper DB assignments such as \`DATABASE_URI=... <wrapper> run -- ...\`; wrapper-managed env may override those values.
-- Safe host-run override pattern when wrapper also defines \`DATABASE_URI\`:
-\`infisical run --projectId <id> --env=<env> -- env DATABASE_URI=\${DATABASE_URL:?missing DATABASE_URL} pnpm dev\`
-- \`dev app run\` does not currently expose \`--env-map\`; if an app only accepts \`DATABASE_URI\`, prefer app-level fallback (\`DATABASE_URI\` then \`DATABASE_URL\`) or a small repo-local wrapper script.
-- \`dev doctor --repo .\` warns on risky pre-wrapper DB assignments before \`run --\` for host apps that depend on postgres.
+  \`dev app exec <app> --yes -- doppler run -- pnpm payload migrate\`
+- Precedence best practice: avoid defining per-dep var names in Infisical/Doppler when you expect devrouter local DB injection.
+- Precedence best practice: store remote/prod URLs under non-conflicting names (for example \`PROD_DATABASE_URL\`) and map intentionally via \`envMap\`.
+- Precedence best practice: if secret manager must define DB vars, run the env probe and verify values before any migration/seed.
 - Use \`dev app exec --shell -- "<single command string>"\` only when shell expansion is required.
-- \`--env-map\` fails fast when SOURCE is missing so migrations do not run with partial mapping.
+- \`envMap\` fails fast when source var is missing so migrations do not run with partial mapping.
 
 ## Upgrade handling (required)
 
@@ -2080,6 +2207,7 @@ Host apps also receive \`PORT\` (random free port), \`HOSTNAME=0.0.0.0\`, \`HOST
 - \`dev init [--write-agents] [--write-skill] [--with-linear]\`: print AI onboarding prompt (non-mutating by default)
 - \`dev -V [--repo .]\`: show installed CLI version, local repo version, and next upgrade target
 - \`dev upgrade [version] [--repo .]\`: list upgrade targets or print target Agent Adaptation Prompt
+- \`dev setup --yes [--repo .] [--json]\`: first-run machine setup plus structured diagnostics
 - \`dev up\` / \`dev down\`: start/stop shared Traefik router
 - \`dev status\`: router/container/network/TLS health
 - \`dev doctor [--repo .]\`: deep diagnostics (global + repo)
@@ -2088,36 +2216,54 @@ Host apps also receive \`PORT\` (random free port), \`HOSTNAME=0.0.0.0\`, \`HOST
 - \`dev logs [-f]\`: Traefik access logs
 - \`dev tls install\`: install mkcert certs, enable HTTPS + TCP/SNI
 - \`dev repo init\`: create \`.devrouter.yml\`
+- \`dev repo inspect [--json]\`: inspect package, scripts, compose services, env names, devcontainer, devrouter config, and agent guidance for onboarding
+- \`dev repo devcontainer write --dry-run --json\`: plan conservative Node/pnpm/Postgres devcontainer/devrouter scaffold files without writing
+- \`dev repo devcontainer write --yes\`: write managed Node/pnpm/Postgres devcontainer/devrouter scaffold files when no custom-file conflicts exist
+- \`dev repo devcontainer verify --json\`: emit read-only onboarding evidence for PRs
+- \`dev repo devcontainer verify --live --yes --json\`: register proxy routes and probe HTTP routes after the devcontainer is running
 - \`dev repo agents [--with-linear]\`: write devrouter section in AGENTS.md + install this skill (and optional Linear workflow assets)
 - \`dev app add\`: add/update app entry in \`.devrouter.yml\`
 - \`dev app ls\`: list app entries
-- \`dev app run <name>\`: run app with dependency lifecycle
-- \`dev app exec <name> [--shell] [--env-map TARGET=SOURCE] -- <cmd>\`: one-shot command with resolved dep env
-- \`dev app rm <name>\`: remove app entry
+- \`dev app run <name> [--env <env>] [--workspace <slug>]\`: run app with dependency lifecycle (--env overrides SM defaultEnv; --workspace overrides the per-workspace token)
+- \`dev app exec <name> [--shell] [--env <env>] [--workspace <slug>] -- <cmd>\`: one-shot command with resolved dep env
+- \`dev app rm <name> [--keep-config]\`: remove app entry (\`--keep-config\` frees only the live route/hostname, leaves \`.devrouter.yml\` untouched)
+- \`dev workspace up <branch> [--path <dir>] [--no-devpod] [--open]\`: create a worktree + devpod + namespaced routes
+- \`dev workspace ls [--json]\`: list git worktrees with workspace token + route count
+- \`dev workspace down <workspace|branch> [--keep-worktree] [--keep-devpod]\`: free routes + stop devpod + remove worktree
 
 ## Validation workflow
 
-1. \`dev up\` -- ensure shared router is running
-2. For TCP/Postgres repos: \`dev tls install\`
-3. \`dev doctor --repo .\` -- check global + repo health
-4. \`dev app ls --repo .\` -- verify entries match expectations
-5. \`dev app run <host-app> --repo . --yes\` -- start target app with deps
-6. \`dev ls\` -- confirm routes are exposed
-7. \`curl -I https://<host>.localhost\` -- HTTP reachability
-8. For TCP/Postgres: use \`dev open <name>\` for connection hint
+For devcontainer onboarding:
+
+1. \`dev setup --repo . --yes --json\`
+2. \`dev doctor --repo . --json\`
+3. \`dev repo inspect --repo . --json\`
+4. \`dev repo devcontainer write --repo . --dry-run --json\`
+5. \`dev repo devcontainer write --repo . --yes\`
+6. \`dev repo devcontainer verify --repo . --json\`
+7. Start the devcontainer, for example \`devpod up .\`
+8. \`dev repo devcontainer verify --repo . --live --yes --json\`
+
+For existing host/docker runtime apps:
+
+1. \`dev setup --repo . --yes\`
+2. \`dev doctor --repo .\`
+3. \`dev app ls --repo .\`
+4. \`dev app run <host-app> --repo . --yes\`
+5. \`dev ls\`
+6. \`curl -I https://<host>.localhost\`
+7. For TCP/Postgres, use \`dev open <name>\` for the connection hint.
 
 ## Runtime behavior notes
 
-- \`dev app run\` auto-starts Docker dependencies, waits for health, stops them on exit.
+- \`dev app run\` auto-starts Docker dependencies and waits for health. Host app runs stop auto-started docker deps on exit; docker app runs leave target services running until explicit cleanup.
 - Host-runtime dependencies are NOT auto-started (v1).
 - \`kind=dependency\` entries do not create routes and cannot be direct targets for \`dev app run\`, \`dev app exec\`, or \`dev open\`.
 - \`kind=dependency\` services start as declared in compose (no Traefik label wiring, no random port publishing, no injected env vars).
 - Postgres on shared \`:5432\` requires TLS/SNI (\`dev tls install\`). Standard app clients should use the injected random port instead.
-- \`dev app exec\` starts deps as needed for one-shot commands and preserves argv semantics by default (\`shell: false\`).
-- \`dev app exec\` stops only deps started by that exec call; already-running deps stay running.
-- If exec cannot determine pre-existing running services, it leaves selected deps running to avoid non-owned teardown.
+- \`dev app exec\` follows the same dep lifecycle for one-shot commands and preserves argv semantics by default (\`shell: false\`).
 - \`dev app exec --shell\` is explicit and requires exactly one command string after \`--\`.
-- Secret-manager overlap caveat: if Infisical/Doppler defines DB vars too, probe effective env (\`printenv DATABASE_URL DATABASE_URI DB_HOST DB_PORT\`) before migrate/seed.
+- Secret-manager overlap caveat: if Infisical/Doppler defines DB vars too, probe effective env (\`printenv DB_URL DB_HOST DB_PORT\`) before migrate/seed.
 `;
     LINEAR_WORKFLOW_SKILL_CONTENT = `---
 name: linear-workflow
@@ -2235,8 +2381,8 @@ If the repository uses devrouter, use \`dev upgrade\` to resolve the required Ag
 function isoTimestamp(now) {
   return (now ?? /* @__PURE__ */ new Date()).toISOString();
 }
-function requiredPlaceholder(path10) {
-  return `<REQUIRED: ${path10}>`;
+function requiredPlaceholder(path16) {
+  return `<REQUIRED: ${path16}>`;
 }
 function normalizeOptionalValue(value) {
   const trimmed = value.trim();
@@ -2554,6 +2700,52 @@ function printDoctorReport(report) {
     }
   }
 }
+function printSetupReport(report) {
+  const summaryRows = [
+    ["Generated", report.generatedAt],
+    ["Repo path", report.repoPath ?? "-"],
+    ["Actions performed", String(report.summary.actions.performed)],
+    ["Actions skipped", String(report.summary.actions.skipped)],
+    ["Actions failed", String(report.summary.actions.failed)],
+    ["Checks OK", String(report.summary.checks.ok)],
+    ["Checks WARN", String(report.summary.checks.warn)],
+    ["Checks ERROR", String(report.summary.checks.error)]
+  ];
+  process.stdout.write(`${renderTable(["FIELD", "VALUE"], summaryRows)}
+
+`);
+  const actionRows = report.actions.map((entry) => [
+    entry.id,
+    entry.status.toUpperCase(),
+    entry.summary,
+    entry.suggestion ?? "-"
+  ]);
+  process.stdout.write(`${renderTable(["ACTION", "STATUS", "SUMMARY", "SUGGESTION"], actionRows)}
+`);
+  const detailedActions = report.actions.filter((entry) => entry.details);
+  if (detailedActions.length > 0) {
+    process.stdout.write("\nAction details:\n");
+    for (const entry of detailedActions) {
+      process.stdout.write(`- ${entry.id}: ${entry.details}
+`);
+    }
+  }
+  const failingChecks = report.checks.filter((check) => check.level !== "ok");
+  if (failingChecks.length > 0) {
+    process.stdout.write("\nDiagnostic findings:\n");
+    for (const check of failingChecks) {
+      process.stdout.write(`- ${check.id} [${check.level.toUpperCase()}]: ${check.summary}
+`);
+    }
+  }
+  if (report.nextSteps.length > 0) {
+    process.stdout.write("\nRecommended next steps:\n");
+    for (const step of report.nextSteps) {
+      process.stdout.write(`- ${step}
+`);
+    }
+  }
+}
 var init_output = __esm({
   "src/core/output.ts"() {
     "use strict";
@@ -2946,138 +3138,217 @@ var init_docker = __esm({
   }
 });
 
-// src/util/ports.ts
-function findPortListeners(port) {
-  const result = (0, import_node_child_process4.spawnSync)("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN"], {
+// src/core/tls.ts
+function runOrThrow(command, args) {
+  const result = (0, import_node_child_process4.spawnSync)(command, args, {
     encoding: "utf-8"
   });
-  if (result.status !== 0 || !result.stdout.trim()) {
-    return [];
-  }
-  const lines = result.stdout.trim().split(/\r?\n/);
-  if (lines.length <= 1) {
-    return [];
+  if (result.status !== 0) {
+    const details = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
+    throw new Error(`${command} ${args.join(" ")} failed: ${details || "unknown error"}`);
   }
-  return lines.slice(1).map((line) => {
-    const parts = line.trim().split(/\s+/);
-    const command = parts[0] ?? "?";
-    const pid = parts[1] ?? "?";
-    const user = parts[2] ?? "?";
-    const address = parts.slice(-2).join(" ") || "?";
-    return {
-      port,
-      command,
-      pid,
-      user,
-      address
-    };
-  });
 }
-var import_node_child_process4;
-var init_ports = __esm({
-  "src/util/ports.ts"() {
-    "use strict";
-    import_node_child_process4 = require("child_process");
+function commandExists(command) {
+  const result = (0, import_node_child_process4.spawnSync)("sh", ["-c", `command -v ${command}`], { encoding: "utf-8" });
+  return result.status === 0;
+}
+function ensureMkcert() {
+  if (commandExists("mkcert")) {
+    return;
   }
-});
-
-// src/commands/up.ts
-var up_exports = {};
-__export(up_exports, {
-  runUpCommand: () => runUpCommand
-});
-function buildPortConflictMessage() {
-  const listeners = [...findPortListeners(80), ...findPortListeners(443), ...findPortListeners(5432)];
-  if (listeners.length === 0) {
-    return "";
+  if (!commandExists("brew")) {
+    throw new Error("mkcert is missing and Homebrew is not available.");
   }
-  const details = listeners.map((listener) => {
-    return `- port ${listener.port}: ${listener.command} (pid ${listener.pid}, user ${listener.user}, ${listener.address})`;
-  }).join("\n");
-  return `Cannot start devrouter because host ports 80/443/5432 are already in use:
-${details}
-
-Mitigation:
-1) Stop the conflicting process/container
-2) Re-run: dev up
-
-Debug commands:
-- lsof -nP -iTCP:80 -sTCP:LISTEN
-- lsof -nP -iTCP:443 -sTCP:LISTEN
-- lsof -nP -iTCP:5432 -sTCP:LISTEN`;
+  runOrThrow("brew", ["install", "mkcert"]);
 }
-async function runUpCommand() {
-  await ensureNetwork(DEVNET_NAME);
-  ensureRouterFiles();
-  const routerRunning = await isContainerRunning(ROUTER_CONTAINER_NAME);
-  if (!routerRunning) {
-    const message = buildPortConflictMessage();
-    if (message) {
-      throw new Error(message);
+function normalizeHost(host) {
+  return host.trim().toLowerCase();
+}
+function normalizeUniqueHosts(hosts) {
+  const set = /* @__PURE__ */ new Set();
+  for (const host of hosts) {
+    const normalized = normalizeHost(host);
+    if (normalized.length === 0) {
+      continue;
     }
+    set.add(normalized);
   }
-  startRouterStack();
-  process.stdout.write("devrouter is up.\n");
+  return Array.from(set.values()).sort();
 }
-var init_up = __esm({
-  "src/commands/up.ts"() {
-    "use strict";
-    init_docker();
-    init_router();
-    init_ports();
+function parseDnsHostsFromSubjectAltName(subjectAltName) {
+  const names = [];
+  const matches = subjectAltName.matchAll(/DNS:([^,\n]+)/g);
+  for (const match of matches) {
+    const host = normalizeHost(match[1] ?? "");
+    if (host.length > 0) {
+      names.push(host);
+    }
   }
-});
-
-// src/commands/down.ts
-var down_exports = {};
-__export(down_exports, {
-  runDownCommand: () => runDownCommand
-});
-async function runDownCommand() {
-  stopRouterStack();
-  clearActiveTcpProtocols();
-  process.stdout.write("devrouter is down.\n");
+  return normalizeUniqueHosts(names);
 }
-var init_down = __esm({
-  "src/commands/down.ts"() {
-    "use strict";
-    init_router();
-  }
-});
-
-// src/core/status.ts
-function hasPortBinding(ports, privatePort, publicPort) {
-  if (!ports) {
-    return false;
+function parseCertificateDnsHosts(pem) {
+  const certificate = new import_node_crypto.X509Certificate(pem);
+  const subjectAltName = certificate.subjectAltName ?? "";
+  if (subjectAltName.length === 0) {
+    return [];
   }
-  return ports.some((port) => port.PrivatePort === privatePort && port.PublicPort === publicPort);
+  return parseDnsHostsFromSubjectAltName(subjectAltName);
 }
-function toRepoStatus(repoPath) {
-  const resolvedRepoPath = resolveRepoPath(repoPath);
-  const configPath = getRepoConfigPath(resolvedRepoPath);
-  const explicitRepo = typeof repoPath === "string" && repoPath.trim().length > 0;
-  const configExists = import_node_fs7.default.existsSync(configPath);
-  if (!explicitRepo && !configExists) {
-    return void 0;
+function isHostCoveredByCertificateHost(host, certificateHost) {
+  const normalizedHost = normalizeHost(host);
+  const normalizedCertificateHost = normalizeHost(certificateHost);
+  if (normalizedCertificateHost.startsWith("*.")) {
+    const suffix = normalizedCertificateHost.slice(1);
+    if (!normalizedHost.endsWith(suffix)) {
+      return false;
+    }
+    const wildcardPart = normalizedHost.slice(0, normalizedHost.length - suffix.length);
+    return wildcardPart.length > 0 && !wildcardPart.includes(".");
   }
-  if (!configExists) {
-    return {
-      path: resolvedRepoPath,
-      configPath,
-      exists: false,
-      valid: false,
-      appCount: 0,
-      tcpAppCount: 0,
-      error: `Missing .devrouter.yml in ${resolvedRepoPath}`
-    };
+  return normalizedHost === normalizedCertificateHost;
+}
+function findUncoveredCertificateHosts(requiredHosts, certificateHosts) {
+  const normalizedRequired = normalizeUniqueHosts(requiredHosts);
+  const normalizedCertificateHosts = normalizeUniqueHosts(certificateHosts);
+  return normalizedRequired.filter(
+    (requiredHost) => !normalizedCertificateHosts.some(
+      (certificateHost) => isHostCoveredByCertificateHost(requiredHost, certificateHost)
+    )
+  );
+}
+function readCurrentCertificateHosts() {
+  if (!import_node_fs7.default.existsSync(CERT_FILE)) {
+    return [];
   }
+  const pem = import_node_fs7.default.readFileSync(CERT_FILE, "utf-8");
+  return parseCertificateDnsHosts(pem);
+}
+function currentCertificateHostsOrEmpty() {
   try {
-    const config = loadRuntimeConfig(resolvedRepoPath).config;
-    const tcpAppCount = config.apps.filter(
-      (app) => app.kind !== "dependency" && app.protocol === "tcp"
-    ).length;
-    return {
-      path: resolvedRepoPath,
+    return readCurrentCertificateHosts();
+  } catch {
+    return [];
+  }
+}
+function buildDesiredTLSCertificateHosts(requestedHosts, existingCertificateHosts) {
+  return normalizeUniqueHosts([
+    ...DEFAULT_TLS_CERT_HOSTS,
+    ...existingCertificateHosts,
+    ...requestedHosts
+  ]);
+}
+function getTLSHostCoverage(hosts) {
+  const requiredHosts = normalizeUniqueHosts([...DEFAULT_TLS_CERT_HOSTS, ...hosts]);
+  const certificateHosts = readCurrentCertificateHosts();
+  const uncoveredHosts = findUncoveredCertificateHosts(requiredHosts, certificateHosts);
+  return {
+    requiredHosts,
+    certificateHosts,
+    uncoveredHosts
+  };
+}
+async function installTLS(options = {}) {
+  ensureRouterFiles();
+  const alreadyEnabled = isTLSEnabled();
+  const desiredHosts = buildDesiredTLSCertificateHosts(
+    options.hosts ?? [],
+    currentCertificateHostsOrEmpty()
+  );
+  ensureMkcert();
+  runOrThrow("mkcert", ["-install"]);
+  runOrThrow("mkcert", [
+    "-cert-file",
+    CERT_FILE,
+    "-key-file",
+    CERT_KEY_FILE,
+    ...desiredHosts
+  ]);
+  setTLSEnabled(true);
+  refreshHostRoutesDynamicFile();
+  const routerContainer = await findContainerByName("devrouter-traefik");
+  if (routerContainer && await isContainerRunning("devrouter-traefik")) {
+    startRouterStack();
+  }
+  return { alreadyEnabled, hosts: desiredHosts };
+}
+async function ensureTLSHostsCovered(hosts) {
+  if (!isTLSEnabled()) {
+    return {
+      refreshed: false,
+      uncoveredHosts: [],
+      certificateHosts: []
+    };
+  }
+  const coverage = getTLSHostCoverage(hosts);
+  if (coverage.uncoveredHosts.length === 0) {
+    return {
+      refreshed: false,
+      uncoveredHosts: [],
+      certificateHosts: coverage.certificateHosts
+    };
+  }
+  try {
+    const refreshed = await installTLS({ hosts: coverage.requiredHosts });
+    return {
+      refreshed: true,
+      uncoveredHosts: coverage.uncoveredHosts,
+      certificateHosts: refreshed.hosts
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `TLS cert does not currently cover host(s): ${coverage.uncoveredHosts.join(", ")}. Automatic refresh failed: ${message}
+Run: dev tls install`
+    );
+  }
+}
+var import_node_fs7, import_node_child_process4, import_node_crypto, DEFAULT_TLS_CERT_HOSTS;
+var init_tls = __esm({
+  "src/core/tls.ts"() {
+    "use strict";
+    import_node_fs7 = __toESM(require("fs"));
+    import_node_child_process4 = require("child_process");
+    import_node_crypto = require("crypto");
+    init_router();
+    init_docker();
+    init_host_routes();
+    DEFAULT_TLS_CERT_HOSTS = ["localhost", "*.localhost"];
+  }
+});
+
+// src/core/status.ts
+function hasPortBinding(ports, privatePort, publicPort) {
+  if (!ports) {
+    return false;
+  }
+  return ports.some((port) => port.PrivatePort === privatePort && port.PublicPort === publicPort);
+}
+function toRepoStatus(repoPath) {
+  const resolvedRepoPath = resolveRepoPath(repoPath);
+  const configPath = getRepoConfigPath(resolvedRepoPath);
+  const explicitRepo = typeof repoPath === "string" && repoPath.trim().length > 0;
+  const configExists = import_node_fs8.default.existsSync(configPath);
+  if (!explicitRepo && !configExists) {
+    return void 0;
+  }
+  if (!configExists) {
+    return {
+      path: resolvedRepoPath,
+      configPath,
+      exists: false,
+      valid: false,
+      appCount: 0,
+      tcpAppCount: 0,
+      error: `Missing .devrouter.yml in ${resolvedRepoPath}`
+    };
+  }
+  try {
+    const config = loadRuntimeConfig(resolvedRepoPath).config;
+    const tcpAppCount = config.apps.filter(
+      (app) => app.kind !== "dependency" && app.protocol === "tcp"
+    ).length;
+    return {
+      path: resolvedRepoPath,
       configPath,
       exists: true,
       valid: true,
@@ -3181,141 +3452,17 @@ async function collectRouterStatus(repoPath) {
     }
   };
 }
-var import_node_fs7;
+var import_node_fs8;
 var init_status = __esm({
   "src/core/status.ts"() {
     "use strict";
-    import_node_fs7 = __toESM(require("fs"));
+    import_node_fs8 = __toESM(require("fs"));
     init_docker();
     init_router();
     init_repo_config();
   }
 });
 
-// src/commands/status.ts
-var status_exports = {};
-__export(status_exports, {
-  runStatusCommand: () => runStatusCommand
-});
-async function runStatusCommand(options) {
-  const status = await collectRouterStatus(options.repo);
-  if (options.json) {
-    printJSON(status);
-    return;
-  }
-  printStatus(status);
-}
-var init_status2 = __esm({
-  "src/commands/status.ts"() {
-    "use strict";
-    init_output();
-    init_status();
-  }
-});
-
-// src/core/concurrency.ts
-function routeUrl(host) {
-  const scheme = isTLSEnabled() ? "https" : "http";
-  return `${scheme}://${host}`;
-}
-function evictIfStale(route) {
-  if (route.mode === "proxy") {
-    return false;
-  }
-  if (isPidRunning(route.pid)) {
-    return false;
-  }
-  removeHostRouteById(route.id);
-  return true;
-}
-function assertAppNotRunning(repoPath, app) {
-  const routes = listHostRouteState();
-  const targetId = buildHostRouteId(repoPath, app.name);
-  for (const route of routes) {
-    if (route.id === targetId) {
-      if (evictIfStale(route)) {
-        continue;
-      }
-      throw new AppAlreadyRunningError(
-        app.name,
-        routeUrl(route.host),
-        route.pid,
-        route.repoPath
-      );
-    }
-    if (route.host === app.host) {
-      if (evictIfStale(route)) {
-        continue;
-      }
-      throw new HostnameConflictError(
-        app.host,
-        route.name,
-        route.repoPath,
-        route.pid
-      );
-    }
-  }
-}
-function evictStaleHostRoutes() {
-  const routes = listHostRouteState();
-  let evicted = 0;
-  for (const route of routes) {
-    if (evictIfStale(route)) {
-      evicted += 1;
-    }
-  }
-  return evicted;
-}
-function evictOrphanedWorkspaceRoutes() {
-  const orphans = listHostRouteState().filter(
-    (route) => route.mode === "proxy" && route.workspace !== void 0 && !import_node_fs8.default.existsSync(route.repoPath)
-  );
-  for (const route of orphans) {
-    removeHostRouteById(route.id);
-  }
-  return orphans.length;
-}
-var import_node_fs8, AppAlreadyRunningError, HostnameConflictError;
-var init_concurrency = __esm({
-  "src/core/concurrency.ts"() {
-    "use strict";
-    import_node_fs8 = __toESM(require("fs"));
-    init_router();
-    init_host_routes();
-    AppAlreadyRunningError = class extends Error {
-      constructor(appName, url, pid, repoPath) {
-        const lines = [
-          `App "${appName}" is already running.`,
-          `  URL:  ${url}`,
-          pid ? `  PID:  ${pid}` : null,
-          `  Repo: ${repoPath}`
-        ].filter(Boolean);
-        super(lines.join("\n"));
-        this.appName = appName;
-        this.url = url;
-        this.pid = pid;
-        this.repoPath = repoPath;
-        this.name = "AppAlreadyRunningError";
-      }
-    };
-    HostnameConflictError = class extends Error {
-      constructor(hostname, existingApp, existingRepoPath, existingPid) {
-        const lines = [
-          `Hostname "${hostname}" is already claimed by app "${existingApp}".`,
-          existingPid ? `  PID:  ${existingPid}` : null,
-          `  Repo: ${existingRepoPath}`
-        ].filter(Boolean);
-        super(lines.join("\n"));
-        this.hostname = hostname;
-        this.existingApp = existingApp;
-        this.existingRepoPath = existingRepoPath;
-        this.existingPid = existingPid;
-        this.name = "HostnameConflictError";
-      }
-    };
-  }
-});
-
 // src/core/routes.ts
 function resolveEntrypointToProtocol(entrypoint) {
   for (const [protocol, entry] of Object.entries(TCP_PROTOCOL_REGISTRY)) {
@@ -3491,186 +3638,475 @@ var init_paths = __esm({
   }
 });
 
-// src/core/tls.ts
-function runOrThrow(command, args) {
-  const result = (0, import_node_child_process5.spawnSync)(command, args, {
-    encoding: "utf-8"
-  });
-  if (result.status !== 0) {
-    const details = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
-    throw new Error(`${command} ${args.join(" ")} failed: ${details || "unknown error"}`);
+// src/core/route-state.ts
+function comparablePath(filePath) {
+  const resolved = import_node_path8.default.resolve(filePath);
+  try {
+    return import_node_fs9.default.realpathSync.native(resolved);
+  } catch {
+    return resolved;
   }
 }
-function commandExists(command) {
-  const result = (0, import_node_child_process5.spawnSync)("sh", ["-c", `command -v ${command}`], { encoding: "utf-8" });
-  return result.status === 0;
+function sameRoutePath(left, right) {
+  return comparablePath(left) === comparablePath(right);
 }
-function ensureMkcert() {
-  if (commandExists("mkcert")) {
-    return;
+function listRoutesForWorktreePaths(worktreePaths) {
+  const routes = listHostRouteState();
+  const byWorktreePath = /* @__PURE__ */ new Map();
+  for (const worktreePath of worktreePaths) {
+    byWorktreePath.set(worktreePath, []);
   }
-  if (!commandExists("brew")) {
-    throw new Error("mkcert is missing and Homebrew is not available.");
+  for (const route of routes) {
+    for (const worktreePath of worktreePaths) {
+      if (sameRoutePath(route.repoPath, worktreePath)) {
+        byWorktreePath.get(worktreePath)?.push(route);
+        break;
+      }
+    }
   }
-  runOrThrow("brew", ["install", "mkcert"]);
+  return byWorktreePath;
 }
-function normalizeHost(host) {
-  return host.trim().toLowerCase();
+function removeWorkspaceRoutesForWorktree(workspace, worktreePath) {
+  return removeHostRoutesWhere(
+    (route) => route.workspace === workspace && sameRoutePath(route.repoPath, worktreePath)
+  );
 }
-function normalizeUniqueHosts(hosts) {
-  const set = /* @__PURE__ */ new Set();
-  for (const host of hosts) {
-    const normalized = normalizeHost(host);
-    if (normalized.length === 0) {
-      continue;
-    }
-    set.add(normalized);
-  }
-  return Array.from(set.values()).sort();
+function removeRouteForApp(repoPath, appName) {
+  return removeHostRoutesWhere((route) => route.name === appName && sameRoutePath(route.repoPath, repoPath));
 }
-function parseDnsHostsFromSubjectAltName(subjectAltName) {
-  const names = [];
-  const matches = subjectAltName.matchAll(/DNS:([^,\n]+)/g);
-  for (const match of matches) {
-    const host = normalizeHost(match[1] ?? "");
-    if (host.length > 0) {
-      names.push(host);
-    }
+function isStaleProcessRoute(route) {
+  if (route.mode === "proxy") {
+    return false;
   }
-  return normalizeUniqueHosts(names);
+  if (!route.pid) {
+    return true;
+  }
+  return !isPidRunning(route.pid);
 }
-function parseCertificateDnsHosts(pem) {
-  const certificate = new import_node_crypto.X509Certificate(pem);
-  const subjectAltName = certificate.subjectAltName ?? "";
-  if (subjectAltName.length === 0) {
-    return [];
+function findStaleProcessRoutes(routes = listHostRouteState()) {
+  return routes.filter((route) => isStaleProcessRoute(route));
+}
+function evictStaleRouteIfNeeded(route) {
+  if (!isStaleProcessRoute(route)) {
+    return "not-stale";
   }
-  return parseDnsHostsFromSubjectAltName(subjectAltName);
+  const removed = removeHostRoutesWhere(
+    (candidate) => candidate.id === route.id && isStaleProcessRoute(candidate)
+  );
+  return removed.length > 0 ? "evicted" : "changed";
 }
-function isHostCoveredByCertificateHost(host, certificateHost) {
-  const normalizedHost = normalizeHost(host);
-  const normalizedCertificateHost = normalizeHost(certificateHost);
-  if (normalizedCertificateHost.startsWith("*.")) {
-    const suffix = normalizedCertificateHost.slice(1);
-    if (!normalizedHost.endsWith(suffix)) {
-      return false;
+function reconcileRouteRunConflict(repoPath, app) {
+  for (; ; ) {
+    const routes = listHostRouteState();
+    let shouldRetry = false;
+    for (const route of routes) {
+      if (route.name === app.name && sameRoutePath(route.repoPath, repoPath)) {
+        const staleEviction = evictStaleRouteIfNeeded(route);
+        if (staleEviction === "evicted") {
+          continue;
+        }
+        if (staleEviction === "changed") {
+          shouldRetry = true;
+          break;
+        }
+        return { kind: "same-app", route };
+      }
+      if (route.host === app.host) {
+        const staleEviction = evictStaleRouteIfNeeded(route);
+        if (staleEviction === "evicted") {
+          continue;
+        }
+        if (staleEviction === "changed") {
+          shouldRetry = true;
+          break;
+        }
+        return { kind: "hostname", route };
+      }
+    }
+    if (!shouldRetry) {
+      return void 0;
     }
-    const wildcardPart = normalizedHost.slice(0, normalizedHost.length - suffix.length);
-    return wildcardPart.length > 0 && !wildcardPart.includes(".");
   }
-  return normalizedHost === normalizedCertificateHost;
 }
-function findUncoveredCertificateHosts(requiredHosts, certificateHosts) {
-  const normalizedRequired = normalizeUniqueHosts(requiredHosts);
-  const normalizedCertificateHosts = normalizeUniqueHosts(certificateHosts);
-  return normalizedRequired.filter(
-    (requiredHost) => !normalizedCertificateHosts.some(
-      (certificateHost) => isHostCoveredByCertificateHost(requiredHost, certificateHost)
-    )
-  );
+function isOrphanedWorkspaceProxyRoute(route) {
+  return route.mode === "proxy" && route.workspace !== void 0 && !import_node_fs9.default.existsSync(route.repoPath);
 }
-function readCurrentCertificateHosts() {
-  if (!import_node_fs9.default.existsSync(CERT_FILE)) {
-    return [];
+function findOrphanedWorkspaceProxyRoutes(routes = listHostRouteState()) {
+  return routes.filter((route) => isOrphanedWorkspaceProxyRoute(route));
+}
+var import_node_fs9, import_node_path8;
+var init_route_state = __esm({
+  "src/core/route-state.ts"() {
+    "use strict";
+    import_node_fs9 = __toESM(require("fs"));
+    import_node_path8 = __toESM(require("path"));
+    init_host_routes();
   }
-  const pem = import_node_fs9.default.readFileSync(CERT_FILE, "utf-8");
-  return parseCertificateDnsHosts(pem);
+});
+
+// src/core/tool-diagnostics.ts
+function outputFromResult(result) {
+  const stdout = typeof result.stdout === "string" ? result.stdout.trim() : "";
+  const stderr = typeof result.stderr === "string" ? result.stderr.trim() : "";
+  const output3 = [stdout, stderr].filter(Boolean).join("\n").trim();
+  return output3.length > 0 ? output3 : void 0;
 }
-function currentCertificateHostsOrEmpty() {
-  try {
-    return readCurrentCertificateHosts();
-  } catch {
-    return [];
+function runTool(command, args = []) {
+  const result = (0, import_node_child_process5.spawnSync)(command, args, {
+    encoding: "utf-8"
+  });
+  if (result.error) {
+    return {
+      ok: false,
+      error: result.error.message
+    };
+  }
+  const output3 = outputFromResult(result);
+  if (result.status === 0) {
+    return { ok: true, output: output3 };
   }
+  return {
+    ok: false,
+    output: output3,
+    error: output3 ?? `${command} ${args.join(" ")} exited with status ${result.status ?? "unknown"}`
+  };
 }
-function buildDesiredTLSCertificateHosts(requestedHosts, existingCertificateHosts) {
-  return normalizeUniqueHosts([
-    ...DEFAULT_TLS_CERT_HOSTS,
-    ...existingCertificateHosts,
-    ...requestedHosts
-  ]);
+function firstLine(value) {
+  return value?.split(/\r?\n/).find((line) => line.trim().length > 0)?.trim();
 }
-function getTLSHostCoverage(hosts) {
-  const requiredHosts = normalizeUniqueHosts([...DEFAULT_TLS_CERT_HOSTS, ...hosts]);
-  const certificateHosts = readCurrentCertificateHosts();
-  const uncoveredHosts = findUncoveredCertificateHosts(requiredHosts, certificateHosts);
+function parsePackageManager(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    return void 0;
+  }
+  const separator = trimmed.lastIndexOf("@");
+  if (separator <= 0) {
+    return { name: trimmed };
+  }
   return {
-    requiredHosts,
-    certificateHosts,
-    uncoveredHosts
+    name: trimmed.slice(0, separator),
+    version: trimmed.slice(separator + 1)
   };
 }
-async function installTLS(options = {}) {
-  ensureRouterFiles();
-  const alreadyEnabled = isTLSEnabled();
-  const desiredHosts = buildDesiredTLSCertificateHosts(
-    options.hosts ?? [],
-    currentCertificateHostsOrEmpty()
-  );
-  ensureMkcert();
-  runOrThrow("mkcert", ["-install"]);
-  runOrThrow("mkcert", [
-    "-cert-file",
-    CERT_FILE,
-    "-key-file",
-    CERT_KEY_FILE,
-    ...desiredHosts
-  ]);
-  setTLSEnabled(true);
-  refreshHostRoutesDynamicFile();
-  const routerContainer = await findContainerByName("devrouter-traefik");
-  if (routerContainer && await isContainerRunning("devrouter-traefik")) {
-    startRouterStack();
+function parseMajor(value) {
+  if (!value) {
+    return void 0;
   }
-  return { alreadyEnabled, hosts: desiredHosts };
+  const match = value.match(/(\d+)/);
+  return match ? Number(match[1]) : void 0;
 }
-async function ensureTLSHostsCovered(hosts) {
-  if (!isTLSEnabled()) {
+function parseMinimumNodeMajor(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const match = value.match(/>=\s*(\d+)/);
+  if (!match) {
+    return void 0;
+  }
+  return Number(match[1]);
+}
+function readPackageJson(repoPath) {
+  const packagePath = import_node_path9.default.join(repoPath, "package.json");
+  if (!import_node_fs10.default.existsSync(packagePath)) {
+    return void 0;
+  }
+  try {
+    return JSON.parse(import_node_fs10.default.readFileSync(packagePath, "utf-8"));
+  } catch {
+    return void 0;
+  }
+}
+function nodeToolchainCheck(repoPath) {
+  const pkg = readPackageJson(repoPath);
+  if (!pkg) {
     return {
-      refreshed: false,
-      uncoveredHosts: [],
-      certificateHosts: []
+      id: "global.node-toolchain",
+      level: "ok",
+      summary: "No package.json found; Node toolchain check is not applicable."
     };
   }
-  const coverage = getTLSHostCoverage(hosts);
-  if (coverage.uncoveredHosts.length === 0) {
+  const engines = typeof pkg.engines === "object" && pkg.engines ? pkg.engines : {};
+  const volta = typeof pkg.volta === "object" && pkg.volta ? pkg.volta : {};
+  const nodeRequirement = typeof volta.node === "string" ? volta.node : engines.node;
+  const minimumNodeMajor = parseMinimumNodeMajor(nodeRequirement) ?? parseMajor(String(nodeRequirement ?? ""));
+  const currentNodeMajor = parseMajor(process.versions.node);
+  const packageManager = parsePackageManager(pkg.packageManager);
+  const details = [`node=${process.versions.node}`];
+  const problems = [];
+  if (minimumNodeMajor !== void 0) {
+    details.push(`expectedNode=${String(nodeRequirement)}`);
+    if (currentNodeMajor !== void 0 && currentNodeMajor < minimumNodeMajor) {
+      problems.push(`Node ${process.versions.node} is older than ${String(nodeRequirement)}`);
+    }
+  }
+  if (packageManager?.name === "pnpm") {
+    const pnpm = runTool("pnpm", ["--version"]);
+    if (!pnpm.ok) {
+      problems.push(`pnpm is missing (${pnpm.error ?? "not found"})`);
+    } else {
+      const actualPnpm = firstLine(pnpm.output) ?? "unknown";
+      details.push(`pnpm=${actualPnpm}`);
+      if (packageManager.version) {
+        details.push(`expectedPnpm=${packageManager.version}`);
+        const expectedMajor = parseMajor(packageManager.version);
+        const actualMajor = parseMajor(actualPnpm);
+        if (expectedMajor !== void 0 && actualMajor !== void 0 && expectedMajor !== actualMajor) {
+          problems.push(`pnpm major ${actualMajor} does not match expected ${expectedMajor}`);
+        }
+      }
+    }
+  } else if (packageManager) {
+    details.push(`packageManager=${packageManager.name}${packageManager.version ? `@${packageManager.version}` : ""}`);
+  }
+  if (problems.length > 0) {
     return {
-      refreshed: false,
-      uncoveredHosts: [],
-      certificateHosts: coverage.certificateHosts
+      id: "global.node-toolchain",
+      level: "warn",
+      summary: "Node package toolchain may not match this repo.",
+      details: [...details, ...problems].join(", "),
+      suggestion: packageManager?.name === "pnpm" && packageManager.version ? `Install pnpm ${packageManager.version}: npm install -g pnpm@${packageManager.version}` : "Install the Node/package-manager versions declared by this repo."
+    };
+  }
+  return {
+    id: "global.node-toolchain",
+    level: "ok",
+    summary: "Node package toolchain is available for this repo.",
+    details: details.join(", ")
+  };
+}
+function buildGlobalToolChecks(repoPath) {
+  const checks = [];
+  const compose = runTool("docker", ["compose", "version"]);
+  checks.push({
+    id: "global.docker-compose",
+    level: compose.ok ? "ok" : "error",
+    summary: compose.ok ? "Docker Compose v2 is reachable." : "Docker Compose v2 is not reachable.",
+    details: firstLine(compose.output) ?? compose.error,
+    suggestion: compose.ok ? void 0 : "Install/start Docker with Compose v2, then run: dev setup --yes"
+  });
+  const mkcert = runTool("mkcert", ["-version"]);
+  const brew = runTool("brew", ["--version"]);
+  checks.push({
+    id: "global.mkcert",
+    level: mkcert.ok ? "ok" : "warn",
+    summary: mkcert.ok ? "mkcert is installed." : "mkcert is not installed.",
+    details: mkcert.ok ? firstLine(mkcert.output) : mkcert.error,
+    suggestion: mkcert.ok ? void 0 : brew.ok ? "Install mkcert: brew install mkcert" : "Install mkcert for local HTTPS, then run: dev setup --yes"
+  });
+  const devpod = runTool("devpod", ["version"]);
+  checks.push({
+    id: "global.devpod",
+    level: devpod.ok ? "ok" : "warn",
+    summary: devpod.ok ? "DevPod is installed." : "DevPod is not installed.",
+    details: firstLine(devpod.output) ?? devpod.error,
+    suggestion: devpod.ok ? void 0 : "Install DevPod for devcontainer workspace flows: brew install devpod"
+  });
+  checks.push(nodeToolchainCheck(repoPath));
+  return checks;
+}
+var import_node_fs10, import_node_path9, import_node_child_process5;
+var init_tool_diagnostics = __esm({
+  "src/core/tool-diagnostics.ts"() {
+    "use strict";
+    import_node_fs10 = __toESM(require("fs"));
+    import_node_path9 = __toESM(require("path"));
+    import_node_child_process5 = require("child_process");
+  }
+});
+
+// src/core/devcontainer-diagnostics.ts
+function asRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return void 0;
+  }
+  return value;
+}
+function asStringArray(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter((entry) => typeof entry === "string");
+}
+function normalizeWorkspaceToken(value) {
+  return value.replace(/\$\{WORKSPACE(?::-[^}]+)?\}/g, "${WORKSPACE}");
+}
+function expandAliasCandidates(value, workspace) {
+  const candidates = /* @__PURE__ */ new Set([normalizeWorkspaceToken(value)]);
+  const defaulted = value.replace(/\$\{WORKSPACE:-([^}]+)\}/g, "$1");
+  if (defaulted !== value) {
+    candidates.add(defaulted);
+  }
+  if (workspace) {
+    const workspaceValue = value.replace(/\$\{WORKSPACE:-[^}]+\}/g, workspace).replace(/\$\{WORKSPACE\}/g, workspace);
+    candidates.add(workspaceValue);
+  }
+  return Array.from(candidates.values());
+}
+function formatPublishedPort(serviceName, value) {
+  if (typeof value === "string") {
+    return `${serviceName}: ${value}`;
+  }
+  const record = asRecord(value);
+  if (!record) {
+    return void 0;
+  }
+  const target = record.target;
+  const published = record.published;
+  if (published !== void 0 && target !== void 0) {
+    return `${serviceName}: ${String(published)}:${String(target)}`;
+  }
+  if (target !== void 0) {
+    return `${serviceName}: target ${String(target)}`;
+  }
+  return `${serviceName}: ${JSON.stringify(record)}`;
+}
+function upstreamHost(upstream) {
+  const separator = upstream.lastIndexOf(":");
+  return separator > 0 ? upstream.slice(0, separator) : upstream;
+}
+function isLoopbackHost(host) {
+  return host === "127.0.0.1" || host === "localhost" || host === "host.docker.internal";
+}
+function inspectCompose(composeFile, workspace) {
+  if (!import_node_fs11.default.existsSync(composeFile)) {
+    return {
+      aliases: [],
+      publishedPorts: [],
+      devnetExternal: false,
+      parseError: `.devcontainer/docker-compose.yml is missing.`
     };
   }
   try {
-    const refreshed = await installTLS({ hosts: coverage.requiredHosts });
+    const raw = import_node_fs11.default.readFileSync(composeFile, "utf-8");
+    const parsed = import_yaml3.default.parse(raw);
+    const root = asRecord(parsed);
+    const services = asRecord(root?.services);
+    const networks = asRecord(root?.networks);
+    const devnet = asRecord(networks?.devnet);
+    const external = devnet?.external;
+    const devnetExternal = external === true || asRecord(external) !== void 0;
+    const aliases = /* @__PURE__ */ new Set();
+    const publishedPorts = [];
+    for (const [serviceName, serviceValue] of Object.entries(services ?? {})) {
+      const service = asRecord(serviceValue);
+      if (!service) {
+        continue;
+      }
+      if (Array.isArray(service.ports)) {
+        for (const port of service.ports) {
+          const formatted = formatPublishedPort(serviceName, port);
+          if (formatted) {
+            publishedPorts.push(formatted);
+          }
+        }
+      }
+      const networks2 = service.networks;
+      if (Array.isArray(networks2)) {
+        continue;
+      }
+      const networkMap = asRecord(networks2);
+      const devnet2 = asRecord(networkMap?.devnet);
+      for (const alias of asStringArray(devnet2?.aliases)) {
+        aliases.add(alias);
+      }
+    }
     return {
-      refreshed: true,
-      uncoveredHosts: coverage.uncoveredHosts,
-      certificateHosts: refreshed.hosts
+      aliases: Array.from(aliases.values()).sort(),
+      publishedPorts,
+      devnetExternal
     };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    throw new Error(
-      `TLS cert does not currently cover host(s): ${coverage.uncoveredHosts.join(", ")}. Automatic refresh failed: ${message}
-Run: dev tls install`
-    );
+    return {
+      aliases: [],
+      publishedPorts: [],
+      devnetExternal: false,
+      parseError: message
+    };
   }
 }
-var import_node_fs9, import_node_child_process5, import_node_crypto, DEFAULT_TLS_CERT_HOSTS;
-var init_tls = __esm({
-  "src/core/tls.ts"() {
+function routedProxyApps(config) {
+  if (!config) {
+    return [];
+  }
+  return config.apps.filter(
+    (app) => app.kind !== "dependency" && app.runtime === "proxy"
+  );
+}
+function buildDevcontainerChecks(repoPath, config, workspace) {
+  const devcontainerDir = import_node_path10.default.join(repoPath, ".devcontainer");
+  if (!import_node_fs11.default.existsSync(devcontainerDir)) {
+    return [];
+  }
+  const compose = inspectCompose(import_node_path10.default.join(devcontainerDir, "docker-compose.yml"), workspace);
+  const checks = [];
+  if (compose.parseError) {
+    checks.push({
+      id: "repo.devcontainer.aliases",
+      level: "warn",
+      summary: "Could not inspect devcontainer devnet aliases.",
+      details: compose.parseError,
+      suggestion: "Add .devcontainer/docker-compose.yml services on the external devnet network with aliases."
+    });
+  } else {
+    const aliasesReady = compose.aliases.length > 0 && compose.devnetExternal;
+    checks.push({
+      id: "repo.devcontainer.aliases",
+      level: aliasesReady ? "ok" : "warn",
+      summary: aliasesReady ? `Found ${compose.aliases.length} devnet alias(es) on the external devnet network.` : compose.aliases.length > 0 ? "Devcontainer aliases exist, but top-level devnet is not marked external." : "No devnet aliases found in the devcontainer compose file.",
+      details: compose.aliases.length > 0 ? `aliases=${compose.aliases.join(", ")}, devnetExternal=${String(compose.devnetExternal)}` : void 0,
+      suggestion: aliasesReady ? void 0 : "Attach routable devcontainer services to an external devnet network and add stable aliases."
+    });
+  }
+  checks.push({
+    id: "repo.devcontainer.no-published-ports",
+    level: compose.parseError ? "warn" : compose.publishedPorts.length === 0 ? "ok" : "error",
+    summary: compose.parseError ? "Could not inspect devcontainer compose file for published host ports." : compose.publishedPorts.length === 0 ? "Devcontainer compose file does not publish host ports." : `Devcontainer compose file publishes ${compose.publishedPorts.length} host port(s).`,
+    details: compose.publishedPorts.length > 0 ? compose.publishedPorts.join(", ") : void 0,
+    suggestion: compose.parseError || compose.publishedPorts.length > 0 ? "Remove published ports and route services through devnet aliases with devrouter proxy apps." : void 0
+  });
+  if (!config) {
+    checks.push({
+      id: "repo.devcontainer.upstream-alias-match",
+      level: "warn",
+      summary: "Cannot compare devcontainer aliases to .devrouter.yml upstreams.",
+      suggestion: "Add or fix .devrouter.yml proxy entries for the devcontainer services."
+    });
+    return checks;
+  }
+  const aliasSet = new Set(
+    compose.aliases.flatMap((alias) => expandAliasCandidates(alias, workspace)).map(normalizeWorkspaceToken)
+  );
+  const proxyApps2 = routedProxyApps(config);
+  const nonLoopbackUpstreams = proxyApps2.map((app) => ({
+    app: app.name,
+    host: normalizeWorkspaceToken(upstreamHost(app.upstream))
+  })).filter((entry) => !isLoopbackHost(entry.host));
+  const missing = nonLoopbackUpstreams.filter((entry) => !aliasSet.has(entry.host));
+  checks.push({
+    id: "repo.devcontainer.upstream-alias-match",
+    level: proxyApps2.length > 0 && missing.length === 0 ? "ok" : "warn",
+    summary: proxyApps2.length === 0 ? "No devrouter proxy apps found for the devcontainer." : missing.length === 0 ? "Devrouter proxy upstreams match devcontainer devnet aliases." : `${missing.length} devrouter proxy upstream(s) do not match devcontainer aliases.`,
+    details: missing.length > 0 ? missing.map((entry) => `${entry.app}: ${entry.host}`).join(", ") : void 0,
+    suggestion: proxyApps2.length === 0 || missing.length > 0 ? "Align .devrouter.yml proxy upstream hosts with .devcontainer/docker-compose.yml devnet aliases." : void 0
+  });
+  return checks;
+}
+var import_node_fs11, import_node_path10, import_yaml3;
+var init_devcontainer_diagnostics = __esm({
+  "src/core/devcontainer-diagnostics.ts"() {
     "use strict";
-    import_node_fs9 = __toESM(require("fs"));
-    import_node_child_process5 = require("child_process");
-    import_node_crypto = require("crypto");
-    init_router();
-    init_docker();
-    init_host_routes();
-    DEFAULT_TLS_CERT_HOSTS = ["localhost", "*.localhost"];
+    import_node_fs11 = __toESM(require("fs"));
+    import_node_path10 = __toESM(require("path"));
+    import_yaml3 = __toESM(require("yaml"));
   }
 });
 
 // src/core/doctor.ts
-function asRecord(value) {
+function asRecord2(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return void 0;
   }
@@ -3695,7 +4131,7 @@ function parseComposeEnvironment(value) {
     }
     return env;
   }
-  const objectValue = asRecord(value);
+  const objectValue = asRecord2(value);
   if (!objectValue) {
     return env;
   }
@@ -3728,15 +4164,15 @@ function inspectPostgresCredentials(repoPath, config) {
         parseErrors.push(`${app.name}: ${composeFile} (${message})`);
         continue;
       }
-      if (!import_node_fs10.default.existsSync(absolutePath)) {
+      if (!import_node_fs12.default.existsSync(absolutePath)) {
         continue;
       }
       try {
-        const raw = import_node_fs10.default.readFileSync(absolutePath, "utf-8");
-        const parsed = import_yaml3.default.parse(raw);
-        const root = asRecord(parsed);
-        const services = asRecord(root?.services);
-        const service = asRecord(services?.[app.docker.service]);
+        const raw = import_node_fs12.default.readFileSync(absolutePath, "utf-8");
+        const parsed = import_yaml4.default.parse(raw);
+        const root = asRecord2(parsed);
+        const services = asRecord2(root?.services);
+        const service = asRecord2(services?.[app.docker.service]);
         if (!service) {
           continue;
         }
@@ -3835,17 +4271,6 @@ function inspectHostCommandPrecedence(config) {
   }
   return { inspectedCount, riskyApps };
 }
-function isPidRunning2(pid) {
-  if (!pid || pid <= 0) {
-    return false;
-  }
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
 function addCheck(checks, check) {
   checks.push(check);
 }
@@ -3878,6 +4303,8 @@ async function buildDoctorReport(options = {}) {
   const fileLayout = getRouterFileLayout();
   const resolvedRepoPath = resolveRepoPath(options.repo);
   const explicitRepo = typeof options.repo === "string" && options.repo.trim().length > 0;
+  let loadedConfig;
+  let loadedWorkspace;
   if (fileLayout.missing.length === 0) {
     addCheck(checks, {
       id: "global.router-files",
@@ -3893,6 +4320,9 @@ async function buildDoctorReport(options = {}) {
       suggestion: "Run: dev up"
     });
   }
+  for (const check of buildGlobalToolChecks(resolvedRepoPath)) {
+    addCheck(checks, check);
+  }
   let statusNextSteps = [];
   try {
     const status = await collectRouterStatus(options.repo);
@@ -3995,7 +4425,10 @@ async function buildDoctorReport(options = {}) {
           suggestion: "Run: dev app add --name <name> --host <name>.localhost --protocol http --runtime host"
         });
       }
-      const config = loadRuntimeConfig(repo.path).config;
+      const runtimeConfig = loadRuntimeConfig(repo.path);
+      const config = runtimeConfig.config;
+      loadedConfig = config;
+      loadedWorkspace = runtimeConfig.workspace;
       const appNames = new Set(config.apps.map((app) => app.name));
       const missingDependencies = config.apps.flatMap(
         (app) => app.dependencies.filter((dependency) => !appNames.has(dependency.app)).map((dependency) => `${app.name}->${dependency.app}`)
@@ -4009,8 +4442,8 @@ async function buildDoctorReport(options = {}) {
       const missingComposeFiles = config.apps.filter((app) => app.runtime === "docker").flatMap((app) => app.docker.composeFiles.map((filePath) => ({
         app: app.name,
         filePath,
-        absolutePath: import_node_path8.default.resolve(repo.path, filePath)
-      }))).filter((entry) => !import_node_fs10.default.existsSync(entry.absolutePath));
+        absolutePath: import_node_path11.default.resolve(repo.path, filePath)
+      }))).filter((entry) => !import_node_fs12.default.existsSync(entry.absolutePath));
       addCheck(checks, {
         id: "repo.compose-files",
         level: missingComposeFiles.length === 0 ? "ok" : "error",
@@ -4053,8 +4486,8 @@ async function buildDoctorReport(options = {}) {
       const missingHostCwds = config.apps.filter((app) => app.runtime === "host").map((app) => ({
         app: app.name,
         cwd: app.hostRun.cwd,
-        absolutePath: import_node_path8.default.resolve(repo.path, app.hostRun.cwd)
-      })).filter((entry) => !import_node_fs10.default.existsSync(entry.absolutePath));
+        absolutePath: import_node_path11.default.resolve(repo.path, app.hostRun.cwd)
+      })).filter((entry) => !import_node_fs12.default.existsSync(entry.absolutePath));
       addCheck(checks, {
         id: "repo.host-cwd",
         level: missingHostCwds.length === 0 ? "ok" : "error",
@@ -4123,6 +4556,9 @@ async function buildDoctorReport(options = {}) {
       details: message
     });
   }
+  for (const check of buildDevcontainerChecks(resolvedRepoPath, loadedConfig, loadedWorkspace)) {
+    addCheck(checks, check);
+  }
   try {
     const tlsEnabled = isTLSEnabled();
     const containers = await listContainers(true);
@@ -4144,29 +4580,20 @@ async function buildDoctorReport(options = {}) {
       details: message
     });
   }
-  const staleHostRoutes = listHostRouteState().filter(
-    (route) => (
-      // Proxy routes have no backing process; they are never "stale".
-      route.mode === "proxy" ? false : route.pid ? !isPidRunning2(route.pid) : true
-    )
-  );
-  addCheck(checks, {
-    id: "routes.host-state",
-    level: staleHostRoutes.length === 0 ? "ok" : "warn",
-    summary: staleHostRoutes.length === 0 ? "Host route state contains only running process entries." : `${staleHostRoutes.length} host route entr${staleHostRoutes.length === 1 ? "y is" : "ies are"} stale (process not running).`,
-    suggestion: staleHostRoutes.length === 0 ? void 0 : "Re-run the affected host app(s): dev app run <name> --repo <path>"
-  });
-  const evictedCount = evictStaleHostRoutes();
+  const staleHostRoutes = findStaleProcessRoutes();
+  const staleCount = staleHostRoutes.length;
   addCheck(checks, {
     id: "routes.stale-host-routes",
-    level: evictedCount === 0 ? "ok" : "warn",
-    summary: evictedCount === 0 ? "No stale host route entries to clean up." : `Evicted ${evictedCount} stale host route entr${evictedCount === 1 ? "y" : "ies"} (dead PID).`
+    level: staleCount === 0 ? "ok" : "warn",
+    summary: staleCount === 0 ? "No stale host route entries detected." : `${staleCount} stale host route entr${staleCount === 1 ? "y" : "ies"} detected (dead PID).`,
+    suggestion: staleCount === 0 ? void 0 : "Re-run the affected host app(s) or remove routes with: dev app rm <name> --repo <path> --keep-config"
   });
-  const evictedOrphanCount = evictOrphanedWorkspaceRoutes();
+  const orphanedWorkspaceRoutes = findOrphanedWorkspaceProxyRoutes();
   addCheck(checks, {
     id: "routes.orphaned-workspace-routes",
-    level: evictedOrphanCount === 0 ? "ok" : "warn",
-    summary: evictedOrphanCount === 0 ? "No orphaned workspace proxy routes to clean up." : `Evicted ${evictedOrphanCount} orphaned workspace proxy route entr${evictedOrphanCount === 1 ? "y" : "ies"} (worktree removed without 'dev workspace down').`
+    level: orphanedWorkspaceRoutes.length === 0 ? "ok" : "warn",
+    summary: orphanedWorkspaceRoutes.length === 0 ? "No orphaned workspace proxy routes detected." : `${orphanedWorkspaceRoutes.length} orphaned workspace proxy route entr${orphanedWorkspaceRoutes.length === 1 ? "y" : "ies"} detected (worktree removed without 'dev workspace down').`,
+    suggestion: orphanedWorkspaceRoutes.length === 0 ? void 0 : "Run: dev workspace down <workspace>"
   });
   const summary = collectSummary(checks);
   const nextSteps = collectNextSteps(checks, statusNextSteps);
@@ -4178,22 +4605,24 @@ async function buildDoctorReport(options = {}) {
     nextSteps
   };
 }
-var import_node_fs10, import_node_path8, import_yaml3, POSTGRES_DEFAULTS;
+var import_node_fs12, import_node_path11, import_yaml4, POSTGRES_DEFAULTS;
 var init_doctor = __esm({
   "src/core/doctor.ts"() {
     "use strict";
-    import_node_fs10 = __toESM(require("fs"));
-    import_node_path8 = __toESM(require("path"));
-    import_yaml3 = __toESM(require("yaml"));
+    import_node_fs12 = __toESM(require("fs"));
+    import_node_path11 = __toESM(require("path"));
+    import_yaml4 = __toESM(require("yaml"));
     init_docker();
     init_host_routes();
-    init_concurrency();
     init_repo_config();
     init_router();
     init_status();
     init_routes();
     init_paths();
     init_tls();
+    init_route_state();
+    init_tool_diagnostics();
+    init_devcontainer_diagnostics();
     POSTGRES_DEFAULTS = {
       POSTGRES_USER: "prisma",
       POSTGRES_PASSWORD: "prisma",
@@ -4202,6 +4631,305 @@ var init_doctor = __esm({
   }
 });
 
+// src/core/setup.ts
+function action(status, entry) {
+  return { status, ...entry };
+}
+function actionStatusCounts(actions) {
+  return actions.reduce(
+    (acc, entry) => {
+      acc[entry.status] += 1;
+      return acc;
+    },
+    { performed: 0, skipped: 0, failed: 0 }
+  );
+}
+function collectNextSteps2(report, doctorNextSteps) {
+  const steps = /* @__PURE__ */ new Set();
+  for (const entry of report.actions) {
+    if (entry.status === "failed" || entry.status === "skipped") {
+      if (entry.suggestion) {
+        steps.add(entry.suggestion);
+      }
+    }
+  }
+  for (const check of report.checks) {
+    if (check.level !== "ok" && check.suggestion) {
+      steps.add(check.suggestion);
+    }
+  }
+  for (const step of doctorNextSteps) {
+    steps.add(step);
+  }
+  return Array.from(steps.values());
+}
+async function runSetup(options = {}) {
+  const repoPath = resolveRepoPath(options.repo);
+  const actions = [];
+  if (!options.yes) {
+    actions.push(action("failed", {
+      id: "setup.confirmation",
+      summary: "Setup requires --yes before mutating devrouter-owned machine state.",
+      suggestion: "Run: dev setup --yes"
+    }));
+    const doctor2 = await buildDoctorReport({ repo: options.repo });
+    const partialReport2 = { actions, checks: doctor2.checks };
+    return {
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      repoPath,
+      actions,
+      checks: doctor2.checks,
+      summary: {
+        actions: actionStatusCounts(actions),
+        checks: doctor2.summary
+      },
+      nextSteps: collectNextSteps2(partialReport2, doctor2.nextSteps)
+    };
+  }
+  try {
+    const missingBefore = getRouterFileLayout().missing;
+    ensureRouterFiles();
+    actions.push(action(missingBefore.length === 0 ? "skipped" : "performed", {
+      id: "global.router-files",
+      summary: missingBefore.length === 0 ? "Global router files were already present." : `Created missing global router file(s): ${missingBefore.join(", ")}`
+    }));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    actions.push(action("failed", {
+      id: "global.router-files",
+      summary: "Failed to ensure global router files.",
+      details: message,
+      suggestion: "Check write access to ~/.config/devrouter, then run: dev setup --yes"
+    }));
+  }
+  try {
+    const existed = await networkExists(DEVNET_NAME);
+    await ensureNetwork(DEVNET_NAME);
+    actions.push(action(existed ? "skipped" : "performed", {
+      id: "global.devnet",
+      summary: existed ? "Shared Docker network devnet already exists." : "Created shared Docker network devnet."
+    }));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    actions.push(action("failed", {
+      id: "global.devnet",
+      summary: "Failed to ensure shared Docker network devnet.",
+      details: message,
+      suggestion: "Start Docker and verify Docker context, then run: dev setup --yes"
+    }));
+  }
+  try {
+    const wasRunning = await isContainerRunning(ROUTER_CONTAINER_NAME);
+    startRouterStack();
+    actions.push(action(wasRunning ? "skipped" : "performed", {
+      id: "global.router-stack",
+      summary: wasRunning ? "Shared Traefik router was already running." : "Started shared Traefik router."
+    }));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    actions.push(action("failed", {
+      id: "global.router-stack",
+      summary: "Failed to start shared Traefik router.",
+      details: message,
+      suggestion: "Resolve Docker/port conflicts on 80, 443, or 5432, then run: dev setup --yes"
+    }));
+  }
+  const mkcert = runTool("mkcert", ["-version"]);
+  if (!mkcert.ok) {
+    actions.push(action("skipped", {
+      id: "global.tls",
+      summary: "Skipped TLS setup because mkcert is not installed.",
+      details: mkcert.error,
+      suggestion: "Install mkcert, then run: dev setup --yes"
+    }));
+  } else {
+    try {
+      const tls = await installTLS();
+      actions.push(action(tls.alreadyEnabled ? "skipped" : "performed", {
+        id: "global.tls",
+        summary: tls.alreadyEnabled ? "TLS was already enabled; certificates were refreshed." : "Installed local TLS certificates and enabled TLS routing.",
+        details: `hosts=${tls.hosts.join(", ")}`
+      }));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      actions.push(action("failed", {
+        id: "global.tls",
+        summary: "Failed to install local TLS certificates.",
+        details: message,
+        suggestion: "Run: dev tls install"
+      }));
+    }
+  }
+  const doctor = await buildDoctorReport({ repo: options.repo });
+  const partialReport = { actions, checks: doctor.checks };
+  return {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    repoPath,
+    actions,
+    checks: doctor.checks,
+    summary: {
+      actions: actionStatusCounts(actions),
+      checks: doctor.summary
+    },
+    nextSteps: collectNextSteps2(partialReport, doctor.nextSteps)
+  };
+}
+var init_setup = __esm({
+  "src/core/setup.ts"() {
+    "use strict";
+    init_docker();
+    init_router();
+    init_tls();
+    init_doctor();
+    init_tool_diagnostics();
+    init_repo_config();
+  }
+});
+
+// src/commands/setup.ts
+var setup_exports = {};
+__export(setup_exports, {
+  runSetupCommand: () => runSetupCommand
+});
+async function runSetupCommand(options) {
+  const report = await runSetup({ repo: options.repo, yes: Boolean(options.yes) });
+  if (options.json) {
+    printJSON(report);
+  } else {
+    printSetupReport(report);
+  }
+  if (report.summary.actions.failed > 0 || report.summary.checks.error > 0) {
+    process.exitCode = 1;
+  }
+}
+var init_setup2 = __esm({
+  "src/commands/setup.ts"() {
+    "use strict";
+    init_setup();
+    init_output();
+  }
+});
+
+// src/util/ports.ts
+function findPortListeners(port) {
+  const result = (0, import_node_child_process6.spawnSync)("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN"], {
+    encoding: "utf-8"
+  });
+  if (result.status !== 0 || !result.stdout.trim()) {
+    return [];
+  }
+  const lines = result.stdout.trim().split(/\r?\n/);
+  if (lines.length <= 1) {
+    return [];
+  }
+  return lines.slice(1).map((line) => {
+    const parts = line.trim().split(/\s+/);
+    const command = parts[0] ?? "?";
+    const pid = parts[1] ?? "?";
+    const user = parts[2] ?? "?";
+    const address = parts.slice(-2).join(" ") || "?";
+    return {
+      port,
+      command,
+      pid,
+      user,
+      address
+    };
+  });
+}
+var import_node_child_process6;
+var init_ports = __esm({
+  "src/util/ports.ts"() {
+    "use strict";
+    import_node_child_process6 = require("child_process");
+  }
+});
+
+// src/commands/up.ts
+var up_exports = {};
+__export(up_exports, {
+  runUpCommand: () => runUpCommand
+});
+function buildPortConflictMessage() {
+  const listeners = [...findPortListeners(80), ...findPortListeners(443), ...findPortListeners(5432)];
+  if (listeners.length === 0) {
+    return "";
+  }
+  const details = listeners.map((listener) => {
+    return `- port ${listener.port}: ${listener.command} (pid ${listener.pid}, user ${listener.user}, ${listener.address})`;
+  }).join("\n");
+  return `Cannot start devrouter because host ports 80/443/5432 are already in use:
+${details}
+
+Mitigation:
+1) Stop the conflicting process/container
+2) Re-run: dev up
+
+Debug commands:
+- lsof -nP -iTCP:80 -sTCP:LISTEN
+- lsof -nP -iTCP:443 -sTCP:LISTEN
+- lsof -nP -iTCP:5432 -sTCP:LISTEN`;
+}
+async function runUpCommand() {
+  await ensureNetwork(DEVNET_NAME);
+  ensureRouterFiles();
+  const routerRunning = await isContainerRunning(ROUTER_CONTAINER_NAME);
+  if (!routerRunning) {
+    const message = buildPortConflictMessage();
+    if (message) {
+      throw new Error(message);
+    }
+  }
+  startRouterStack();
+  process.stdout.write("devrouter is up.\n");
+}
+var init_up = __esm({
+  "src/commands/up.ts"() {
+    "use strict";
+    init_docker();
+    init_router();
+    init_ports();
+  }
+});
+
+// src/commands/down.ts
+var down_exports = {};
+__export(down_exports, {
+  runDownCommand: () => runDownCommand
+});
+async function runDownCommand() {
+  stopRouterStack();
+  clearActiveTcpProtocols();
+  process.stdout.write("devrouter is down.\n");
+}
+var init_down = __esm({
+  "src/commands/down.ts"() {
+    "use strict";
+    init_router();
+  }
+});
+
+// src/commands/status.ts
+var status_exports = {};
+__export(status_exports, {
+  runStatusCommand: () => runStatusCommand
+});
+async function runStatusCommand(options) {
+  const status = await collectRouterStatus(options.repo);
+  if (options.json) {
+    printJSON(status);
+    return;
+  }
+  printStatus(status);
+}
+var init_status2 = __esm({
+  "src/commands/status.ts"() {
+    "use strict";
+    init_output();
+    init_status();
+  }
+});
+
 // src/commands/doctor.ts
 var doctor_exports = {};
 __export(doctor_exports, {
@@ -4211,9 +4939,12 @@ async function runDoctorCommand(options) {
   const report = await buildDoctorReport({ repo: options.repo });
   if (options.json) {
     printJSON(report);
-    return;
+  } else {
+    printDoctorReport(report);
+  }
+  if (report.summary.error > 0) {
+    process.exitCode = 1;
   }
-  printDoctorReport(report);
 }
 var init_doctor2 = __esm({
   "src/commands/doctor.ts"() {
@@ -4302,7 +5033,7 @@ async function runOpenCommand(name) {
     );
     return;
   }
-  const result = (0, import_node_child_process6.spawnSync)("open", [url], { encoding: "utf-8" });
+  const result = (0, import_node_child_process7.spawnSync)("open", [url], { encoding: "utf-8" });
   if (result.status !== 0) {
     const details = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
     throw new Error(`Unable to open '${url}': ${details || "unknown error"}`);
@@ -4310,11 +5041,11 @@ async function runOpenCommand(name) {
   process.stdout.write(`Opened ${url}
 `);
 }
-var import_node_child_process6;
+var import_node_child_process7;
 var init_open = __esm({
   "src/commands/open.ts"() {
     "use strict";
-    import_node_child_process6 = require("child_process");
+    import_node_child_process7 = require("child_process");
     init_docker();
     init_host_routes();
     init_repo_config();
@@ -4337,7 +5068,7 @@ async function runLogsCommand(options) {
   const args = ["logs", "--tail", tail, ROUTER_CONTAINER_NAME];
   if (options.follow) {
     args.splice(1, 0, "-f");
-    const child = (0, import_node_child_process7.spawn)("docker", args, { stdio: "inherit" });
+    const child = (0, import_node_child_process8.spawn)("docker", args, { stdio: "inherit" });
     const onSignal = () => {
       child.kill("SIGTERM");
     };
@@ -4351,17 +5082,17 @@ async function runLogsCommand(options) {
       });
     });
   } else {
-    const result = (0, import_node_child_process7.spawnSync)("docker", args, { stdio: "inherit" });
+    const result = (0, import_node_child_process8.spawnSync)("docker", args, { stdio: "inherit" });
     if (result.status !== 0) {
       throw new Error("Failed to retrieve router logs.");
     }
   }
 }
-var import_node_child_process7;
+var import_node_child_process8;
 var init_logs = __esm({
   "src/commands/logs.ts"() {
     "use strict";
-    import_node_child_process7 = require("child_process");
+    import_node_child_process8 = require("child_process");
     init_router();
     init_docker();
   }
@@ -4384,65 +5115,1327 @@ async function runRepoInitCommand(options) {
 `);
   process.stdout.write("Next: dev app add --name <name> --host <host.localhost> --protocol <http|tcp> --runtime <host|docker>\n");
 }
-var init_repo_init = __esm({
-  "src/commands/repo-init.ts"() {
+var init_repo_init = __esm({
+  "src/commands/repo-init.ts"() {
+    "use strict";
+    init_repo_config();
+  }
+});
+
+// src/core/repo-inspect.ts
+function asRecord3(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return void 0;
+  }
+  return value;
+}
+function readJson(filePath) {
+  if (!import_node_fs13.default.existsSync(filePath)) {
+    return void 0;
+  }
+  try {
+    return JSON.parse(import_node_fs13.default.readFileSync(filePath, "utf-8"));
+  } catch {
+    return void 0;
+  }
+}
+function relative(repoPath, filePath) {
+  return import_node_path12.default.relative(repoPath, filePath) || ".";
+}
+function redactEnvAssignments(value) {
+  return value.replace(
+    /(^|\s)([A-Za-z_][A-Za-z0-9_]*)=("[^"]*"|'[^']*'|[^\s]+)/g,
+    "$1$2=<redacted>"
+  );
+}
+function sanitizeDiagnosticText(value) {
+  return redactEnvAssignments(value).replace(/\bvalue\s+'[^']+'/g, "value '<redacted>'").replace(/\b[a-z][a-z0-9+.-]*:\/\/[^\s'"]+/gi, "<redacted-url>");
+}
+function parsePackageManager2(value) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  const separator = trimmed.lastIndexOf("@");
+  if (separator <= 0) {
+    return { name: trimmed };
+  }
+  return {
+    name: trimmed.slice(0, separator),
+    version: trimmed.slice(separator + 1)
+  };
+}
+function inspectPackageManager(repoPath, pkg) {
+  const packageManager = parsePackageManager2(pkg?.packageManager);
+  if (packageManager) {
+    return {
+      ...packageManager,
+      source: "package.json:packageManager"
+    };
+  }
+  const lockfiles = [
+    ["pnpm-lock.yaml", "pnpm"],
+    ["package-lock.json", "npm"],
+    ["yarn.lock", "yarn"],
+    ["bun.lockb", "bun"],
+    ["bun.lock", "bun"]
+  ];
+  for (const [fileName, name] of lockfiles) {
+    if (import_node_fs13.default.existsSync(import_node_path12.default.join(repoPath, fileName))) {
+      return { name, source: fileName };
+    }
+  }
+  return void 0;
+}
+function inspectNode(repoPath, pkg) {
+  const volta = asRecord3(pkg?.volta);
+  if (typeof volta?.node === "string") {
+    return { version: volta.node, source: "package.json:volta.node" };
+  }
+  const engines = asRecord3(pkg?.engines);
+  if (typeof engines?.node === "string") {
+    return { version: engines.node, source: "package.json:engines.node" };
+  }
+  const nvmrc = import_node_path12.default.join(repoPath, ".nvmrc");
+  if (import_node_fs13.default.existsSync(nvmrc)) {
+    const version = import_node_fs13.default.readFileSync(nvmrc, "utf-8").trim();
+    return { version, source: ".nvmrc" };
+  }
+  return void 0;
+}
+function inspectScripts(pkg) {
+  const scripts = asRecord3(pkg?.scripts);
+  if (!scripts) {
+    return [];
+  }
+  return Object.entries(scripts).filter((entry) => typeof entry[1] === "string").map(([name, command]) => ({
+    name,
+    command: redactEnvAssignments(command),
+    evidence: [`package.json:scripts.${name}`]
+  }));
+}
+function inferPort(command) {
+  const patterns = [
+    /\bPORT=(\d{2,5})\b/,
+    /--port[=\s]+(\d{2,5})\b/,
+    /(?:^|\s)-p\s+(\d{2,5})\b/
+  ];
+  for (const pattern of patterns) {
+    const match = command.match(pattern);
+    if (match) {
+      return { port: Number(match[1]), confidence: "high", evidence: [`script command: ${match[0]}`] };
+    }
+  }
+  const frameworkDefaults = [
+    { pattern: /\bnext\b/, port: 3e3, label: "next default port" },
+    { pattern: /\bvite\b/, port: 5173, label: "vite default port" },
+    { pattern: /\bastro\b/, port: 4321, label: "astro default port" },
+    { pattern: /\bnuxt\b/, port: 3e3, label: "nuxt default port" }
+  ];
+  for (const entry of frameworkDefaults) {
+    if (entry.pattern.test(command)) {
+      return { port: entry.port, confidence: "medium", evidence: [entry.label] };
+    }
+  }
+  return { confidence: "low", evidence: ["No explicit port detected"] };
+}
+function inspectAppCandidates(scripts) {
+  const candidates = scripts.filter(
+    (script) => /(^dev$|:dev$|dev:|^start$|web|app|serve)/.test(script.name)
+  );
+  return candidates.map((script) => {
+    const port = inferPort(script.command);
+    return {
+      name: script.name === "dev" || script.name === "start" ? "app" : script.name.replace(/[:_]/g, "-"),
+      port: port.port,
+      confidence: port.confidence,
+      evidence: [...script.evidence, ...port.evidence]
+    };
+  });
+}
+function configuredComposeFiles(repoPath) {
+  try {
+    const config = loadRepoConfig(repoPath);
+    const files = config.apps.filter((app) => app.runtime === "docker").flatMap((app) => app.docker.composeFiles).filter((fileName) => !import_node_path12.default.isAbsolute(fileName) && !import_node_path12.default.normalize(fileName).startsWith(".."));
+    return Array.from(new Set(files));
+  } catch {
+    return [];
+  }
+}
+function composeFiles(repoPath) {
+  const candidates = [
+    "docker-compose.yml",
+    "docker-compose.yaml",
+    "compose.yml",
+    "compose.yaml",
+    ".devcontainer/docker-compose.yml",
+    ".devcontainer/docker-compose.yaml",
+    ...configuredComposeFiles(repoPath)
+  ];
+  return Array.from(new Set(candidates)).filter((fileName) => import_node_fs13.default.existsSync(import_node_path12.default.join(repoPath, fileName)));
+}
+function stringArray(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.map((entry) => typeof entry === "string" ? entry : JSON.stringify(entry));
+}
+function envNames(value) {
+  if (Array.isArray(value)) {
+    return value.filter((entry) => typeof entry === "string").map((entry) => entry.split("=")[0]?.trim()).filter((entry) => Boolean(entry));
+  }
+  const record = asRecord3(value);
+  return record ? Object.keys(record).sort() : [];
+}
+function inferServiceKind(name, image) {
+  const source = `${name} ${image ?? ""}`.toLowerCase();
+  const rules = [
+    ["postgres", "postgres"],
+    ["redis", "redis"],
+    ["mysql", "mysql"],
+    ["mariadb", "mariadb"],
+    ["mock-oauth2", "oidc"],
+    ["oidc", "oidc"],
+    ["mailhog", "mail"]
+  ];
+  for (const [needle, kind] of rules) {
+    if (source.includes(needle)) {
+      return { kind, confidence: "high" };
+    }
+  }
+  return { kind: "unknown", confidence: "low" };
+}
+function inspectServices(repoPath) {
+  const services = [];
+  for (const fileName of composeFiles(repoPath)) {
+    try {
+      const parsed = import_yaml5.default.parse(import_node_fs13.default.readFileSync(import_node_path12.default.join(repoPath, fileName), "utf-8"));
+      const serviceMap = asRecord3(asRecord3(parsed)?.services);
+      for (const [name, value] of Object.entries(serviceMap ?? {})) {
+        const service = asRecord3(value);
+        if (!service) {
+          continue;
+        }
+        const image = typeof service.image === "string" ? service.image : void 0;
+        const kind = inferServiceKind(name, image);
+        services.push({
+          name,
+          kind: kind.kind,
+          source: fileName,
+          image,
+          ports: stringArray(service.ports),
+          hasHealthcheck: service.healthcheck !== void 0,
+          envNames: envNames(service.environment),
+          confidence: kind.confidence
+        });
+      }
+    } catch {
+      services.push({
+        name: "(parse-error)",
+        kind: "unknown",
+        source: fileName,
+        ports: [],
+        hasHealthcheck: false,
+        envNames: [],
+        confidence: "low"
+      });
+    }
+  }
+  return services;
+}
+function inspectEnvFiles(repoPath) {
+  const files = import_node_fs13.default.readdirSync(repoPath).filter((fileName) => /^\.env(\.|$)/.test(fileName)).sort().map((fileName) => {
+    const content = import_node_fs13.default.readFileSync(import_node_path12.default.join(repoPath, fileName), "utf-8");
+    const names = content.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("#") && line.includes("=")).map((line) => line.split("=")[0]?.trim()).filter((name) => Boolean(name)).sort();
+    return { path: fileName, names };
+  });
+  const allNames = Array.from(new Set(files.flatMap((file) => file.names))).sort();
+  return {
+    files,
+    authLikeNames: allNames.filter((name) => /(AUTH|OIDC|ISSUER|CLERK|NEXTAUTH)/i.test(name)),
+    databaseLikeNames: allNames.filter((name) => /(DATABASE|POSTGRES|REDIS|MYSQL|MARIADB|DB_)/i.test(name))
+  };
+}
+function inspectDevcontainer(repoPath) {
+  const dir = import_node_path12.default.join(repoPath, ".devcontainer");
+  if (!import_node_fs13.default.existsSync(dir)) {
+    return { exists: false, files: [] };
+  }
+  return {
+    exists: true,
+    files: import_node_fs13.default.readdirSync(dir).filter((fileName) => import_node_fs13.default.statSync(import_node_path12.default.join(dir, fileName)).isFile()).sort().map((fileName) => `.devcontainer/${fileName}`)
+  };
+}
+function inspectDevrouter(repoPath) {
+  const configPath = getRepoConfigPath(repoPath);
+  if (!import_node_fs13.default.existsSync(configPath)) {
+    return {
+      exists: false,
+      configPath,
+      valid: false,
+      appCount: 0,
+      tcpAppCount: 0,
+      apps: []
+    };
+  }
+  try {
+    const config = loadRepoConfig(repoPath);
+    return {
+      exists: true,
+      configPath,
+      valid: true,
+      appCount: config.apps.length,
+      tcpAppCount: config.apps.filter((app) => app.kind !== "dependency" && app.protocol === "tcp").length,
+      apps: config.apps.map((app) => ({
+        name: app.name,
+        runtime: app.runtime,
+        protocol: app.kind === "dependency" ? void 0 : app.protocol,
+        host: app.kind === "dependency" ? void 0 : app.host
+      }))
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      exists: true,
+      configPath,
+      valid: false,
+      appCount: 0,
+      tcpAppCount: 0,
+      apps: [],
+      error: sanitizeDiagnosticText(message)
+    };
+  }
+}
+function inspectAgentGuidance(repoPath) {
+  const results = [];
+  for (const [fileName, kind] of [["AGENTS.md", "agents"], ["CLAUDE.md", "claude"]]) {
+    if (import_node_fs13.default.existsSync(import_node_path12.default.join(repoPath, fileName))) {
+      results.push({ path: fileName, kind });
+    }
+  }
+  const skillsDir = import_node_path12.default.join(repoPath, ".agents", "skills");
+  if (import_node_fs13.default.existsSync(skillsDir)) {
+    for (const name of import_node_fs13.default.readdirSync(skillsDir).sort()) {
+      const skillPath = import_node_path12.default.join(skillsDir, name, "SKILL.md");
+      if (import_node_fs13.default.existsSync(skillPath)) {
+        results.push({ path: relative(repoPath, skillPath), kind: "skill" });
+      }
+    }
+  }
+  return results;
+}
+function buildIssues(report) {
+  const issues = [];
+  if (!report.packageManager) {
+    issues.push({
+      id: "repo.package-manager.missing",
+      level: "warn",
+      summary: "No package manager metadata or lockfile detected."
+    });
+  }
+  if (!report.devcontainer.exists) {
+    issues.push({
+      id: "repo.devcontainer.missing",
+      level: "warn",
+      summary: "No .devcontainer directory found."
+    });
+  }
+  if (!report.devrouter.exists) {
+    issues.push({
+      id: "repo.devrouter.missing",
+      level: "warn",
+      summary: "No .devrouter.yml found.",
+      suggestion: `Run: dev repo init --repo ${report.repoPath}`
+    });
+  } else if (!report.devrouter.valid) {
+    issues.push({
+      id: "repo.devrouter.invalid",
+      level: "error",
+      summary: ".devrouter.yml exists but is invalid.",
+      details: report.devrouter.error,
+      suggestion: "Fix .devrouter.yml validation errors."
+    });
+  }
+  return issues;
+}
+function inspectRepo(options = {}) {
+  const repoPath = resolveRepoPath(options.repo);
+  const pkg = readJson(import_node_path12.default.join(repoPath, "package.json"));
+  const scripts = inspectScripts(pkg);
+  const reportWithoutIssues = {
+    repoPath,
+    packageManager: inspectPackageManager(repoPath, pkg),
+    node: inspectNode(repoPath, pkg),
+    scripts,
+    apps: inspectAppCandidates(scripts),
+    services: inspectServices(repoPath),
+    env: inspectEnvFiles(repoPath),
+    devcontainer: inspectDevcontainer(repoPath),
+    devrouter: inspectDevrouter(repoPath),
+    agentGuidance: inspectAgentGuidance(repoPath)
+  };
+  return {
+    ...reportWithoutIssues,
+    issues: buildIssues(reportWithoutIssues)
+  };
+}
+var import_node_fs13, import_node_path12, import_yaml5;
+var init_repo_inspect = __esm({
+  "src/core/repo-inspect.ts"() {
+    "use strict";
+    import_node_fs13 = __toESM(require("fs"));
+    import_node_path12 = __toESM(require("path"));
+    import_yaml5 = __toESM(require("yaml"));
+    init_repo_config();
+  }
+});
+
+// src/commands/repo-inspect.ts
+var repo_inspect_exports = {};
+__export(repo_inspect_exports, {
+  runRepoInspectCommand: () => runRepoInspectCommand
+});
+async function runRepoInspectCommand(options) {
+  const report = inspectRepo({ repo: options.repo });
+  if (options.json) {
+    printJSON(report);
+    return;
+  }
+  printRepoInspectionSummary(report);
+}
+function printRepoInspectionSummary(report) {
+  const packageManager = report.packageManager ? `${report.packageManager.name}${report.packageManager.version ? `@${report.packageManager.version}` : ""}` : "not detected";
+  const devrouter = report.devrouter.exists ? report.devrouter.valid ? `valid (${report.devrouter.appCount} app(s))` : "invalid" : "missing";
+  process.stdout.write(`Repo: ${report.repoPath}
+`);
+  process.stdout.write(`Package manager: ${packageManager}
+`);
+  process.stdout.write(`Scripts: ${report.scripts.length}
+`);
+  process.stdout.write(`App candidates: ${report.apps.length}
+`);
+  process.stdout.write(`Compose services: ${report.services.length}
+`);
+  process.stdout.write(`Devcontainer: ${report.devcontainer.exists ? "yes" : "no"}
+`);
+  process.stdout.write(`Devrouter config: ${devrouter}
+`);
+  if (report.issues.length > 0) {
+    process.stdout.write("\nIssues:\n");
+    for (const issue of report.issues) {
+      process.stdout.write(`- ${issue.id} [${issue.level}]: ${issue.summary}
+`);
+    }
+  }
+  process.stdout.write("\nFor full agent-readable output, run: dev repo inspect --json\n");
+}
+var init_repo_inspect2 = __esm({
+  "src/commands/repo-inspect.ts"() {
+    "use strict";
+    init_repo_inspect();
+    init_output();
+  }
+});
+
+// src/commands/repo-agents.ts
+var repo_agents_exports = {};
+__export(repo_agents_exports, {
+  runRepoAgentsCommand: () => runRepoAgentsCommand
+});
+async function runRepoAgentsCommand(options, deps = {}) {
+  const repoPath = resolveRepoPath(options.repo);
+  let linearMetadata = null;
+  const skill = ensureSkillFile(repoPath);
+  process.stdout.write(`Wrote skill to ${skill.path}
+`);
+  if (options.withLinear) {
+    linearMetadata = await (deps.collectLinearMetadata ?? collectLinearWorkflowMetadata)();
+    if (linearMetadata.captureMode === "placeholder") {
+      process.stdout.write(
+        "Warning: non-interactive mode detected; wrote placeholder Linear mapping values. Re-run in a TTY to capture workspace/team/project.\n"
+      );
+    }
+    const linearSkills = ensureLinearWorkflowSkillFiles(repoPath);
+    for (const filePath of linearSkills.paths) {
+      process.stdout.write(`Wrote Linear workflow artifact to ${filePath}
+`);
+    }
+  }
+  const result = ensureAgentsMdSection(repoPath);
+  if (!result.written) {
+    process.stdout.write(`devrouter section already present: ${result.path}
+`);
+  } else {
+    process.stdout.write(`Wrote devrouter section to ${result.path}
+`);
+  }
+  if (options.withLinear) {
+    if (!linearMetadata) {
+      throw new Error("Linear metadata was not collected.");
+    }
+    const linearAgents = ensureLinearWorkflowAgentsSection(repoPath, linearMetadata);
+    if (!linearAgents.written) {
+      process.stdout.write(`Linear workflow section already present: ${linearAgents.path}
+`);
+      return;
+    }
+    process.stdout.write(`Wrote Linear workflow section to ${linearAgents.path}
+`);
+  }
+}
+var init_repo_agents = __esm({
+  "src/commands/repo-agents.ts"() {
+    "use strict";
+    init_repo_config();
+    init_agents_md();
+    init_linear_onboarding();
+  }
+});
+
+// src/core/devcontainer-write.ts
+function sanitizeProjectName(value) {
+  const sanitized = value.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32);
+  return sanitized || "app";
+}
+function majorVersion(value, fallback) {
+  const match = value?.match(/(\d+)/);
+  return match ? match[1] : fallback;
+}
+function devrouterVersion(value) {
+  return value && /^\d+\.\d+\.\d+$/.test(value) ? value : DEFAULT_DEVROUTER_VERSION;
+}
+function inferDevScript(repo) {
+  const script = repo.scripts.find((entry) => entry.name === "dev") ?? repo.scripts.find((entry) => entry.name.endsWith(":dev"));
+  if (!script) {
+    return "pnpm dev";
+  }
+  return script.name === "dev" ? "pnpm dev" : `pnpm run -- ${shellSingleQuote(script.name)}`;
+}
+function inferPort2(repo) {
+  return repo.apps.find((app) => app.port)?.port ?? 3e3;
+}
+function renderDockerfile(nodeMajor, pnpmVersion) {
+  const pnpmPackageSpec = `pnpm@${pnpmVersion}`;
+  return `# ${MANAGED_MARKER}
+FROM node:${nodeMajor}-bookworm-slim
+
+RUN apt-get update \\
+  && apt-get install -y --no-install-recommends git ca-certificates curl procps openssl \\
+  && rm -rf /var/lib/apt/lists/*
+
+RUN npm install -g ${shellSingleQuote(pnpmPackageSpec)}
+
+WORKDIR /workspaces/app
+`;
+}
+function renderCompose(projectName) {
+  return `# ${MANAGED_MARKER}
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: prisma
+      POSTGRES_PASSWORD: prisma
+      POSTGRES_DB: prisma
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U prisma -d prisma"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+    networks:
+      default: {}
+      devnet:
+        aliases:
+          - \${WORKSPACE:-${projectName}}-db
+    volumes:
+      - ./init-db.sh:/docker-entrypoint-initdb.d/10-create-shadow-db.sh:ro
+      - pgdata:/var/lib/postgresql/data
+
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    init: true
+    env_file:
+      - devcontainer.env
+    command: sleep infinity
+    networks:
+      default: {}
+      devnet:
+        aliases:
+          - \${WORKSPACE:-${projectName}}-app
+    volumes:
+      - ..:/workspaces/${projectName}:cached
+      - node_modules:/workspaces/${projectName}/node_modules
+    working_dir: /workspaces/${projectName}
+    depends_on:
+      postgres:
+        condition: service_healthy
+
+networks:
+  devnet:
+    external: true
+
+volumes:
+  pgdata:
+  node_modules:
+`;
+}
+function renderInitDb() {
+  return `#!/usr/bin/env bash
+# ${MANAGED_MARKER}
+set -euo pipefail
+
+psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" <<'SQL'
+SELECT 'CREATE DATABASE shadow'
+WHERE NOT EXISTS (SELECT FROM pg_database WHERE datname = 'shadow')\\gexec
+SQL
+`;
+}
+function renderDevcontainerJson(projectName) {
+  return `{
+  "name": "${projectName}",
+  "dockerComposeFile": "docker-compose.yml",
+  "service": "app",
+  "workspaceFolder": "/workspaces/${projectName}",
+  "postCreateCommand": "bash .devcontainer/post-create.sh",
+  "postStartCommand": "bash .devcontainer/post-start.sh",
+  "customizations": {
+    "devrouter": {
+      "managed": "${MANAGED_MARKER}"
+    },
+    "vscode": {
+      "extensions": []
+    }
+  }
+}
+`;
+}
+function renderEnv(projectName, port) {
+  return `# ${MANAGED_MARKER}
+WORKSPACE=${projectName}
+HOST=0.0.0.0
+HOSTNAME=0.0.0.0
+PORT=${port}
+DATABASE_URL=postgres://prisma:prisma@postgres:5432/prisma
+SHADOW_DATABASE_URL=postgres://prisma:prisma@postgres:5432/shadow
+`;
+}
+function renderPostCreate() {
+  return `#!/usr/bin/env bash
+# ${MANAGED_MARKER}
+set -euo pipefail
+
+export CI=true
+export npm_config_verify_deps_before_run=false
+
+if [ -f package.json ]; then
+  pnpm install --no-frozen-lockfile
+fi
+`;
+}
+function shellSingleQuote(value) {
+  return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+function renderPostStart(devCommand) {
+  return `#!/usr/bin/env bash
+# ${MANAGED_MARKER}
+set -euo pipefail
+
+export CI=true
+export npm_config_verify_deps_before_run=false
+set -a
+. .devcontainer/devcontainer.env
+set +a
+
+if pgrep -f ${shellSingleQuote(devCommand)} >/dev/null 2>&1; then
+  exit 0
+fi
+
+setsid bash -lc ${shellSingleQuote(devCommand)} >/tmp/devrouter-app.log 2>&1 </dev/null &
+`;
+}
+function renderDevrouter(projectName, port, version) {
+  return `# ${MANAGED_MARKER}
+version: 1
+devrouter:
+  version: ${version}
+project:
+  name: ${projectName}
+apps:
+  - name: app
+    host: ${projectName}.localhost
+    protocol: http
+    runtime: proxy
+    upstream: \${WORKSPACE}-app:${port}
+
+  - name: db
+    host: db.${projectName}.localhost
+    protocol: tcp
+    tcpProtocol: postgres
+    runtime: proxy
+    upstream: \${WORKSPACE}-db:5432
+`;
+}
+function renderReadme(projectName) {
+  return `<!-- ${MANAGED_MARKER} -->
+# Devcontainer
+
+Use this repo through the devcontainer, with devrouter providing stable local routes.
+
+\`\`\`bash
+dev setup --yes
+devpod up .
+dev app run app --repo . --yes
+dev app run db --repo . --yes
+\`\`\`
+
+- App: https://${projectName}.localhost
+- Postgres: db.${projectName}.localhost:5432 (TLS/SNI)
+`;
+}
+function postWriteNextSteps(repoPath) {
+  const quotedRepoPath = shellSingleQuote(repoPath);
+  return [
+    `Run: dev setup --repo ${quotedRepoPath} --yes`,
+    `Run: cd ${quotedRepoPath} && devpod up .`,
+    `Run: dev app run app --repo ${quotedRepoPath} --yes`,
+    `Run: dev app run db --repo ${quotedRepoPath} --yes`,
+    `Optional: dev repo agents --repo ${quotedRepoPath}`
+  ];
+}
+function issueNextSteps(issues) {
+  const steps = issues.filter((issue) => issue.level === "error").map((issue) => issue.suggestion).filter((suggestion) => Boolean(suggestion));
+  if (steps.length > 0) {
+    return [...steps, "Re-run: dev repo devcontainer write --dry-run --json"];
+  }
+  return ["Resolve reported errors, then re-run: dev repo devcontainer write --dry-run --json"];
+}
+function packageManagerIssues(repo) {
+  if (!repo.packageManager) {
+    return [
+      {
+        id: "repo.devcontainer.package-manager-unknown",
+        level: "warn",
+        summary: "Package manager could not be detected; pnpm scaffold will be generated.",
+        suggestion: "Add packageManager: pnpm@<version> to package.json or add pnpm-lock.yaml before writing."
+      }
+    ];
+  }
+  if (repo.packageManager.name !== "pnpm") {
+    return [
+      {
+        id: "repo.devcontainer.package-manager-unsupported",
+        level: "error",
+        summary: `Only pnpm repositories are supported by this devcontainer scaffold; detected ${repo.packageManager.name}.`,
+        details: repo.packageManager.source,
+        suggestion: "Use a pnpm repo for this scaffold, or adapt the generated plan manually before writing."
+      }
+    ];
+  }
+  if (repo.packageManager.version && !VALID_PACKAGE_VERSION_RE.test(repo.packageManager.version)) {
+    return [
+      {
+        id: "repo.devcontainer.package-manager-version-unsupported",
+        level: "error",
+        summary: `Unsupported pnpm version '${repo.packageManager.version}' in packageManager.`,
+        details: repo.packageManager.source,
+        suggestion: "Use a pinned semver packageManager value such as pnpm@11.6.0 before writing the scaffold."
+      }
+    ];
+  }
+  return [];
+}
+function plannedFiles(repoPath, version) {
+  const repo = inspectRepo({ repo: repoPath });
+  const projectName = sanitizeProjectName(import_node_path13.default.basename(repo.repoPath));
+  const nodeMajor = majorVersion(repo.node?.version, "24");
+  const pnpmVersion = repo.packageManager?.name === "pnpm" && repo.packageManager.version ? repo.packageManager.version : DEFAULT_PNPM_VERSION;
+  const port = inferPort2(repo);
+  const devCommand = inferDevScript(repo);
+  const issues = packageManagerIssues(repo);
+  return {
+    projectName,
+    issues,
+    files: [
+      { relativePath: ".devcontainer/Dockerfile", content: renderDockerfile(nodeMajor, pnpmVersion) },
+      { relativePath: ".devcontainer/docker-compose.yml", content: renderCompose(projectName) },
+      { relativePath: ".devcontainer/init-db.sh", content: renderInitDb(), executable: true },
+      { relativePath: ".devcontainer/devcontainer.json", content: renderDevcontainerJson(projectName) },
+      { relativePath: ".devcontainer/devcontainer.env", content: renderEnv(projectName, port) },
+      { relativePath: ".devcontainer/post-create.sh", content: renderPostCreate(), executable: true },
+      { relativePath: ".devcontainer/post-start.sh", content: renderPostStart(devCommand), executable: true },
+      { relativePath: ".devcontainer/README.md", content: renderReadme(projectName) },
+      { relativePath: ".devrouter.yml", content: renderDevrouter(projectName, port, version) }
+    ]
+  };
+}
+function classifyFile(repoPath, file) {
+  const absolutePath = import_node_path13.default.join(repoPath, file.relativePath);
+  if (!import_node_fs14.default.existsSync(absolutePath)) {
+    return {
+      path: file.relativePath,
+      action: "create",
+      reason: "file is missing",
+      bytes: Buffer.byteLength(file.content)
+    };
+  }
+  const current = import_node_fs14.default.readFileSync(absolutePath, "utf-8");
+  if (!current.includes(MANAGED_MARKER)) {
+    return {
+      path: file.relativePath,
+      action: "conflict",
+      reason: "existing file is not marked as devrouter-managed"
+    };
+  }
+  if (current === file.content) {
+    return {
+      path: file.relativePath,
+      action: "skip",
+      reason: "managed file already matches",
+      bytes: Buffer.byteLength(file.content)
+    };
+  }
+  return {
+    path: file.relativePath,
+    action: "update",
+    reason: "managed file differs",
+    bytes: Buffer.byteLength(file.content)
+  };
+}
+function buildPlan(repoPath, dryRun, version) {
+  const rendered = plannedFiles(repoPath, version);
+  const files = rendered.files;
+  const filePlans = files.map((file) => classifyFile(repoPath, file));
+  const issues = [...rendered.issues];
+  if (filePlans.some((file) => file.action === "conflict")) {
+    issues.push({
+      id: "repo.devcontainer.write-conflict",
+      level: "error",
+      summary: "One or more target files already exist and are not devrouter-managed.",
+      suggestion: "Review the conflicts, move custom files aside, or merge the devrouter-managed section manually."
+    });
+  }
+  filePlans.push({
+    path: "AGENTS.md",
+    action: "suggest",
+    reason: "run dev repo agents after reviewing the scaffold"
+  });
+  return {
+    files,
+    plan: {
+      repoPath,
+      projectName: rendered.projectName,
+      profile: "node-postgres",
+      dryRun,
+      files: filePlans,
+      issues,
+      nextSteps: issues.some((issue) => issue.level === "error") ? issueNextSteps(issues) : dryRun ? [`Review this plan, then run: dev repo devcontainer write --repo ${shellSingleQuote(repoPath)} --yes`] : postWriteNextSteps(repoPath)
+    }
+  };
+}
+function writeFile(repoPath, file) {
+  const absolutePath = import_node_path13.default.join(repoPath, file.relativePath);
+  import_node_fs14.default.mkdirSync(import_node_path13.default.dirname(absolutePath), { recursive: true });
+  import_node_fs14.default.writeFileSync(absolutePath, file.content, "utf-8");
+  if (file.executable) {
+    import_node_fs14.default.chmodSync(absolutePath, 493);
+  }
+}
+function writeDevcontainer(options = {}) {
+  const repoPath = resolveRepoPath(options.repo);
+  const dryRun = Boolean(options.dryRun);
+  const { plan, files } = buildPlan(repoPath, dryRun, devrouterVersion(options.installedVersion));
+  if (dryRun || plan.issues.some((issue) => issue.level === "error")) {
+    return plan;
+  }
+  if (!options.yes) {
+    return {
+      ...plan,
+      issues: [
+        ...plan.issues,
+        {
+          id: "repo.devcontainer.confirmation",
+          level: "error",
+          summary: "Writing devcontainer files requires --yes.",
+          suggestion: `Run: dev repo devcontainer write --repo ${shellSingleQuote(repoPath)} --yes`
+        }
+      ],
+      nextSteps: [`Run: dev repo devcontainer write --repo ${shellSingleQuote(repoPath)} --yes`]
+    };
+  }
+  for (const file of files) {
+    const classification = classifyFile(repoPath, file);
+    if (classification.action === "create" || classification.action === "update") {
+      writeFile(repoPath, file);
+    }
+  }
+  return {
+    ...plan,
+    nextSteps: postWriteNextSteps(repoPath)
+  };
+}
+var import_node_fs14, import_node_path13, MANAGED_MARKER, DEFAULT_DEVROUTER_VERSION, DEFAULT_PNPM_VERSION, VALID_PACKAGE_VERSION_RE;
+var init_devcontainer_write = __esm({
+  "src/core/devcontainer-write.ts"() {
+    "use strict";
+    import_node_fs14 = __toESM(require("fs"));
+    import_node_path13 = __toESM(require("path"));
+    init_repo_inspect();
+    init_repo_config();
+    MANAGED_MARKER = "devrouter:managed devcontainer";
+    DEFAULT_DEVROUTER_VERSION = "0.0.0";
+    DEFAULT_PNPM_VERSION = "11.6.0";
+    VALID_PACKAGE_VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+  }
+});
+
+// src/core/concurrency.ts
+function routeUrl(host) {
+  const scheme = isTLSEnabled() ? "https" : "http";
+  return `${scheme}://${host}`;
+}
+function assertAppNotRunning(repoPath, app) {
+  const conflict = reconcileRouteRunConflict(repoPath, app);
+  if (!conflict) {
+    return;
+  }
+  if (conflict.kind === "same-app") {
+    throw new AppAlreadyRunningError(
+      app.name,
+      routeUrl(conflict.route.host),
+      conflict.route.pid,
+      conflict.route.repoPath
+    );
+  }
+  throw new HostnameConflictError(
+    app.host,
+    conflict.route.name,
+    conflict.route.repoPath,
+    conflict.route.pid
+  );
+}
+var AppAlreadyRunningError, HostnameConflictError;
+var init_concurrency = __esm({
+  "src/core/concurrency.ts"() {
+    "use strict";
+    init_router();
+    init_route_state();
+    AppAlreadyRunningError = class extends Error {
+      constructor(appName, url, pid, repoPath) {
+        const lines = [
+          `App "${appName}" is already running.`,
+          `  URL:  ${url}`,
+          pid ? `  PID:  ${pid}` : null,
+          `  Repo: ${repoPath}`
+        ].filter(Boolean);
+        super(lines.join("\n"));
+        this.appName = appName;
+        this.url = url;
+        this.pid = pid;
+        this.repoPath = repoPath;
+        this.name = "AppAlreadyRunningError";
+      }
+    };
+    HostnameConflictError = class extends Error {
+      constructor(hostname, existingApp, existingRepoPath, existingPid) {
+        const lines = [
+          `Hostname "${hostname}" is already claimed by app "${existingApp}".`,
+          existingPid ? `  PID:  ${existingPid}` : null,
+          `  Repo: ${existingRepoPath}`
+        ].filter(Boolean);
+        super(lines.join("\n"));
+        this.hostname = hostname;
+        this.existingApp = existingApp;
+        this.existingRepoPath = existingRepoPath;
+        this.existingPid = existingPid;
+        this.name = "HostnameConflictError";
+      }
+    };
+  }
+});
+
+// src/core/devcontainer-verify.ts
+function collectSummary2(checks) {
+  return checks.reduce(
+    (acc, check) => {
+      acc[check.level] += 1;
+      return acc;
+    },
+    { ok: 0, warn: 0, error: 0 }
+  );
+}
+function collectNextSteps3(checks) {
+  const steps = /* @__PURE__ */ new Set();
+  for (const check of checks) {
+    if (check.level !== "ok" && check.suggestion) {
+      steps.add(check.suggestion);
+    }
+  }
+  return Array.from(steps.values());
+}
+function proxyApps(config) {
+  return (config?.apps ?? []).filter(
+    (app) => app.kind !== "dependency" && app.runtime === "proxy"
+  );
+}
+function routedApps(config) {
+  return config.apps.filter((app) => app.kind !== "dependency");
+}
+function requiredFileChecks(repoPath) {
+  const required = [
+    ".devcontainer/devcontainer.json",
+    ".devcontainer/docker-compose.yml",
+    ".devrouter.yml"
+  ];
+  const missing = required.filter((fileName) => !import_node_fs15.default.existsSync(import_node_path14.default.join(repoPath, fileName)));
+  return {
+    id: "repo.devcontainer.verify-files",
+    level: missing.length === 0 ? "ok" : "error",
+    summary: missing.length === 0 ? "Required devcontainer/devrouter files are present." : `Missing required devcontainer/devrouter file(s): ${missing.join(", ")}.`,
+    suggestion: missing.length === 0 ? void 0 : "Run: dev repo devcontainer write --dry-run --json"
+  };
+}
+function proxyConfigCheck(apps) {
+  return {
+    id: "repo.devcontainer.verify-proxy-apps",
+    level: apps.length > 0 ? "ok" : "error",
+    summary: apps.length > 0 ? `Found ${apps.length} proxy app(s) for devcontainer routing.` : "No proxy app entries found for devcontainer routing.",
+    suggestion: apps.length > 0 ? void 0 : "Add runtime: proxy app entries to .devrouter.yml or run: dev repo devcontainer write --dry-run --json"
+  };
+}
+function workspaceTemplateCheck(apps) {
+  const templated = apps.filter((app) => app.upstream.includes(WORKSPACE_PLACEHOLDER));
+  return {
+    id: "repo.devcontainer.verify-workspace-upstreams",
+    level: apps.length > 0 && templated.length === apps.length ? "ok" : "warn",
+    summary: apps.length === 0 ? "No proxy upstreams to inspect for workspace templating." : templated.length === apps.length ? "All proxy upstreams use the ${WORKSPACE} placeholder." : `${apps.length - templated.length} proxy upstream(s) do not use the \${WORKSPACE} placeholder.`,
+    details: apps.length > 0 && templated.length !== apps.length ? apps.filter((app) => !app.upstream.includes(WORKSPACE_PLACEHOLDER)).map((app) => app.name).join(", ") : void 0,
+    suggestion: apps.length > 0 && templated.length !== apps.length ? "Use ${WORKSPACE} in devcontainer proxy upstreams so parallel worktrees do not collide." : void 0
+  };
+}
+function workspacePreview(repoPath, config) {
+  const preview = applyWorkspace(config, "verify", repoPath);
+  return routedApps(preview).map((app) => ({
+    name: app.name,
+    host: app.host,
+    upstream: app.runtime === "proxy" ? app.upstream : void 0
+  }));
+}
+function workspacePreviewCheck(preview) {
+  const missingNamespacedHosts = (preview ?? []).filter((app) => !app.host.endsWith(".verify.localhost"));
+  return {
+    id: "repo.devcontainer.verify-workspace-preview",
+    level: (preview ?? []).length > 0 && missingNamespacedHosts.length === 0 ? "ok" : "warn",
+    summary: (preview ?? []).length === 0 ? "No routed app entries found for workspace preview." : missingNamespacedHosts.length === 0 ? "Workspace preview namespaces configured hosts without rewriting .devrouter.yml." : `${missingNamespacedHosts.length} workspace preview host(s) were not namespaced.`,
+    details: missingNamespacedHosts.length > 0 ? missingNamespacedHosts.map((app) => `${app.name}: ${app.host}`).join(", ") : void 0,
+    suggestion: missingNamespacedHosts.length > 0 ? "Use valid .localhost hosts and let devrouter namespace them at runtime." : void 0
+  };
+}
+function blockingDoctorChecks(doctor) {
+  return doctor.checks.filter(
+    (check) => check.level === "error" && (check.id.startsWith("repo.devcontainer") || check.id === "repo.config" || check.id === "repo.tcp-tls" || check.id === "global.devnet")
+  );
+}
+function doctorGateCheck(doctor) {
+  const blocking = blockingDoctorChecks(doctor);
+  return {
+    id: "repo.devcontainer.verify-doctor",
+    level: blocking.length === 0 ? "ok" : "error",
+    summary: blocking.length === 0 ? "Doctor has no blocking devcontainer diagnostics." : `Doctor reported ${blocking.length} blocking devcontainer diagnostic(s).`,
+    details: blocking.length > 0 ? blocking.map((check) => check.id).join(", ") : void 0,
+    suggestion: blocking.length > 0 ? "Run: dev doctor --repo <path> --json" : void 0
+  };
+}
+function routeUrl2(host) {
+  return `${isTLSEnabled() ? "https" : "http"}://${host}`;
+}
+function curlRoute(host) {
+  const result = (0, import_node_child_process9.spawnSync)("curl", ["-k", "-fsS", "--max-time", "5", routeUrl2(host)], {
+    encoding: "utf-8"
+  });
+  if (result.status === 0) {
+    return { ok: true, details: "HTTP route responded successfully." };
+  }
+  return {
+    ok: false,
+    details: (result.stderr || result.stdout || `curl exited with status ${String(result.status)}`).trim()
+  };
+}
+function registerProxyRoute(repoPath, app, workspace) {
+  ensureRouterFiles();
+  const { port, upstreamHost: upstreamHost2 } = parseUpstream(app.upstream);
+  if (app.protocol === "tcp" && !isTLSEnabled()) {
+    throw new Error(
+      `App "${app.name}" is a TCP proxy route, which requires TLS (SNI). Run \`dev tls install\` first.`
+    );
+  }
+  if (app.protocol === "tcp") {
+    const needsRestart = activateTcpProtocol(app.tcpProtocol);
+    if (needsRestart) {
+      startRouterStack();
+    }
+  }
+  removeRouteForApp(repoPath, app.name);
+  assertAppNotRunning(repoPath, { name: app.name, host: app.host });
+  upsertHostRoute({
+    name: app.name,
+    host: app.host,
+    protocol: app.protocol,
+    tcpProtocol: app.protocol === "tcp" ? app.tcpProtocol : void 0,
+    repoPath,
+    port,
+    upstreamHost: upstreamHost2,
+    mode: "proxy",
+    workspace
+  });
+}
+async function liveChecks(repoPath, yes) {
+  if (!yes) {
+    return {
+      routes: [],
+      checks: [
+        {
+          id: "repo.devcontainer.verify-live-confirmation",
+          level: "error",
+          summary: "Live devcontainer verification requires --yes.",
+          suggestion: "Run: dev repo devcontainer verify --live --yes --json"
+        }
+      ]
+    };
+  }
+  let runtime;
+  try {
+    runtime = loadRuntimeConfig(repoPath);
+  } catch (error) {
+    return {
+      routes: [],
+      checks: [
+        {
+          id: "repo.devcontainer.verify-live-config",
+          level: "error",
+          summary: "Could not load runtime config for live verification.",
+          details: error instanceof Error ? error.message : String(error),
+          suggestion: "Fix .devrouter.yml and re-run: dev repo devcontainer verify --live --yes --json"
+        }
+      ]
+    };
+  }
+  const apps = proxyApps(runtime.config);
+  const checks = [];
+  const routes = [];
+  for (const app of apps) {
+    try {
+      registerProxyRoute(repoPath, app, runtime.workspace);
+      if (app.protocol === "http") {
+        const curl = curlRoute(app.host);
+        routes.push({
+          name: app.name,
+          host: app.host,
+          status: curl.ok ? "reachable" : "failed",
+          details: curl.details
+        });
+        checks.push({
+          id: `repo.devcontainer.verify-live-http.${app.name}`,
+          level: curl.ok ? "ok" : "error",
+          summary: curl.ok ? `HTTP proxy route '${app.name}' responded.` : `HTTP proxy route '${app.name}' did not respond.`,
+          details: curl.ok ? void 0 : curl.details,
+          suggestion: curl.ok ? void 0 : "Start the devcontainer app process, then re-run live verification."
+        });
+      } else {
+        routes.push({
+          name: app.name,
+          host: app.host,
+          status: "registered",
+          details: `${app.tcpProtocol} route registered on port ${String(TCP_PROTOCOL_REGISTRY[app.tcpProtocol]?.port ?? 5432)}.`
+        });
+        checks.push({
+          id: `repo.devcontainer.verify-live-tcp.${app.name}`,
+          level: "ok",
+          summary: `TCP proxy route '${app.name}' registered.`
+        });
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      routes.push({
+        name: app.name,
+        host: app.host,
+        status: "failed",
+        details: message
+      });
+      checks.push({
+        id: `repo.devcontainer.verify-live-route.${app.name}`,
+        level: "error",
+        summary: `Could not register proxy route '${app.name}'.`,
+        details: message,
+        suggestion: "Run: dev setup --yes, start the devcontainer, then retry live verification."
+      });
+    }
+  }
+  return { checks, routes };
+}
+async function verifyDevcontainer(options = {}) {
+  const repoPath = resolveRepoPath(options.repo);
+  const doctor = await buildDoctorReport({ repo: repoPath });
+  const checks = [doctorGateCheck(doctor), requiredFileChecks(repoPath)];
+  let config;
+  let workspaceEvidence;
+  let apps = [];
+  try {
+    config = loadRepoConfig(repoPath);
+    apps = proxyApps(config);
+    workspaceEvidence = workspacePreview(repoPath, config);
+    checks.push(proxyConfigCheck(apps));
+    checks.push(workspaceTemplateCheck(apps));
+    checks.push(workspacePreviewCheck(workspaceEvidence));
+  } catch (error) {
+    checks.push({
+      id: "repo.devcontainer.verify-config",
+      level: "error",
+      summary: "Could not load .devrouter.yml for devcontainer verification.",
+      details: error instanceof Error ? error.message : String(error),
+      suggestion: "Fix .devrouter.yml and re-run: dev repo devcontainer verify --json"
+    });
+  }
+  let liveRoutes;
+  if (options.live) {
+    const live = await liveChecks(repoPath, Boolean(options.yes));
+    checks.push(...live.checks);
+    liveRoutes = live.routes;
+  }
+  const summary = collectSummary2(checks);
+  return {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    repoPath,
+    live: Boolean(options.live),
+    summary,
+    checks,
+    evidence: {
+      doctorSummary: doctor.summary,
+      blockingDoctorChecks: blockingDoctorChecks(doctor).map((check) => check.id),
+      proxyApps: apps.map((app) => ({
+        name: app.name,
+        protocol: app.protocol,
+        host: app.host,
+        upstream: app.upstream
+      })),
+      workspacePreview: workspaceEvidence,
+      liveRoutes
+    },
+    nextSteps: collectNextSteps3(checks)
+  };
+}
+var import_node_child_process9, import_node_fs15, import_node_path14;
+var init_devcontainer_verify = __esm({
+  "src/core/devcontainer-verify.ts"() {
     "use strict";
+    import_node_child_process9 = require("child_process");
+    import_node_fs15 = __toESM(require("fs"));
+    import_node_path14 = __toESM(require("path"));
     init_repo_config();
+    init_concurrency();
+    init_host_routes();
+    init_doctor();
+    init_route_state();
+    init_router();
+    init_capabilities();
   }
 });
 
-// src/commands/repo-agents.ts
-var repo_agents_exports = {};
-__export(repo_agents_exports, {
-  runRepoAgentsCommand: () => runRepoAgentsCommand
+// src/commands/repo-devcontainer.ts
+var repo_devcontainer_exports = {};
+__export(repo_devcontainer_exports, {
+  runRepoDevcontainerVerifyCommand: () => runRepoDevcontainerVerifyCommand,
+  runRepoDevcontainerWriteCommand: () => runRepoDevcontainerWriteCommand
 });
-async function runRepoAgentsCommand(options, deps = {}) {
-  const repoPath = resolveRepoPath(options.repo);
-  let linearMetadata = null;
-  const skill = ensureSkillFile(repoPath);
-  process.stdout.write(`Wrote skill to ${skill.path}
+async function runRepoDevcontainerWriteCommand(options) {
+  const report = writeDevcontainer({
+    repo: options.repo,
+    dryRun: Boolean(options.dryRun),
+    yes: Boolean(options.yes),
+    installedVersion: options.installedVersion
+  });
+  if (options.json) {
+    printJSON(report);
+  } else {
+    process.stdout.write(`Devcontainer profile: ${report.profile}
+`);
+    for (const file of report.files) {
+      process.stdout.write(`- ${file.action}: ${file.path} (${file.reason})
 `);
-  if (options.withLinear) {
-    linearMetadata = await (deps.collectLinearMetadata ?? collectLinearWorkflowMetadata)();
-    if (linearMetadata.captureMode === "placeholder") {
-      process.stdout.write(
-        "Warning: non-interactive mode detected; wrote placeholder Linear mapping values. Re-run in a TTY to capture workspace/team/project.\n"
-      );
     }
-    const linearSkills = ensureLinearWorkflowSkillFiles(repoPath);
-    for (const filePath of linearSkills.paths) {
-      process.stdout.write(`Wrote Linear workflow artifact to ${filePath}
+    if (report.issues.length > 0) {
+      process.stdout.write("\nFindings:\n");
+      for (const issue of report.issues) {
+        process.stdout.write(`- ${issue.id} [${issue.level}]: ${issue.summary}
+`);
+        if (issue.details) {
+          process.stdout.write(`  Details: ${issue.details}
+`);
+        }
+        if (issue.suggestion) {
+          process.stdout.write(`  Suggestion: ${issue.suggestion}
+`);
+        }
+      }
+    }
+    if (report.nextSteps.length > 0) {
+      process.stdout.write("\nNext steps:\n");
+      for (const step of report.nextSteps) {
+        process.stdout.write(`- ${step}
 `);
+      }
     }
   }
-  const result = ensureAgentsMdSection(repoPath);
-  if (!result.written) {
-    process.stdout.write(`devrouter section already present: ${result.path}
-`);
+  if (report.issues.some((issue) => issue.level === "error")) {
+    process.exitCode = 1;
+  }
+}
+async function runRepoDevcontainerVerifyCommand(options) {
+  const report = await verifyDevcontainer({
+    repo: options.repo,
+    live: Boolean(options.live),
+    yes: Boolean(options.yes)
+  });
+  if (options.json) {
+    printJSON(report);
   } else {
-    process.stdout.write(`Wrote devrouter section to ${result.path}
-`);
+    printVerifySummary(report);
   }
-  if (options.withLinear) {
-    if (!linearMetadata) {
-      throw new Error("Linear metadata was not collected.");
-    }
-    const linearAgents = ensureLinearWorkflowAgentsSection(repoPath, linearMetadata);
-    if (!linearAgents.written) {
-      process.stdout.write(`Linear workflow section already present: ${linearAgents.path}
+  if (report.summary.error > 0) {
+    process.exitCode = 1;
+  }
+}
+function printVerifySummary(report) {
+  process.stdout.write(`Repo: ${report.repoPath}
+`);
+  process.stdout.write(`Mode: ${report.live ? "live" : "static"}
+`);
+  process.stdout.write(`Checks: ${report.summary.ok} ok, ${report.summary.warn} warn, ${report.summary.error} error
+`);
+  process.stdout.write(`Proxy apps: ${report.evidence.proxyApps.length}
+`);
+  if (report.checks.some((check) => check.level !== "ok")) {
+    process.stdout.write("\nFindings:\n");
+    for (const check of report.checks.filter((entry) => entry.level !== "ok")) {
+      process.stdout.write(`- ${check.id} [${check.level}]: ${check.summary}
 `);
-      return;
     }
-    process.stdout.write(`Wrote Linear workflow section to ${linearAgents.path}
+  }
+  if (report.nextSteps.length > 0) {
+    process.stdout.write("\nNext steps:\n");
+    for (const step of report.nextSteps) {
+      process.stdout.write(`- ${step}
 `);
+    }
   }
 }
-var init_repo_agents = __esm({
-  "src/commands/repo-agents.ts"() {
+var init_repo_devcontainer = __esm({
+  "src/commands/repo-devcontainer.ts"() {
     "use strict";
-    init_repo_config();
-    init_agents_md();
-    init_linear_onboarding();
+    init_output();
+    init_devcontainer_write();
+    init_devcontainer_verify();
   }
 });
 
@@ -4532,7 +6525,7 @@ function sanitizeRouterId(value) {
   return value.replace(/[^a-zA-Z0-9_-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
 }
 function repoHash(repoPath) {
-  return (0, import_node_crypto2.createHash)("sha1").update(import_node_path9.default.resolve(repoPath)).digest("hex").slice(0, 12);
+  return (0, import_node_crypto2.createHash)("sha1").update(import_node_path15.default.resolve(repoPath)).digest("hex").slice(0, 12);
 }
 function asDockerApp(app) {
   return app.runtime === "docker";
@@ -4611,25 +6604,25 @@ function prepareDockerOverlay(repoPath, appName, apps, publishTcpPorts = false)
   if (dockerApps.length === 0) {
     throw new Error("No docker apps selected to prepare compose overlay.");
   }
-  const cachePath = import_node_path9.default.join(CACHE_DIR, repoHash(repoPath), sanitizeRouterId(appName));
-  import_node_fs11.default.mkdirSync(cachePath, { recursive: true });
-  const overlayPath = import_node_path9.default.join(cachePath, "compose.devrouter.yml");
+  const cachePath = import_node_path15.default.join(CACHE_DIR, repoHash(repoPath), sanitizeRouterId(appName));
+  import_node_fs16.default.mkdirSync(cachePath, { recursive: true });
+  const overlayPath = import_node_path15.default.join(cachePath, "compose.devrouter.yml");
   const overlayDocument = buildOverlayDocument(dockerApps, publishTcpPorts);
-  import_node_fs11.default.writeFileSync(overlayPath, import_yaml4.default.stringify(overlayDocument, { lineWidth: 0 }), "utf-8");
+  import_node_fs16.default.writeFileSync(overlayPath, import_yaml6.default.stringify(overlayDocument, { lineWidth: 0 }), "utf-8");
   return {
     overlayPath,
     composeFiles: ensureComposeFiles(dockerApps),
     dockerApps
   };
 }
-function runDockerComposeUp(repoPath, composeFiles, overlayPath, services) {
+function runDockerComposeUp(repoPath, composeFiles2, overlayPath, services) {
   const fileArgs = [];
-  for (const composeFile of composeFiles) {
+  for (const composeFile of composeFiles2) {
     const resolved = assertPathWithinRepo(composeFile, repoPath, "composeFiles");
     fileArgs.push("-f", resolved);
   }
   const args = ["compose", ...fileArgs, "-f", overlayPath, "up", "-d", "--wait", ...services];
-  const result = (0, import_node_child_process8.spawnSync)("docker", args, {
+  const result = (0, import_node_child_process10.spawnSync)("docker", args, {
     encoding: "utf-8",
     cwd: repoPath
   });
@@ -4638,9 +6631,9 @@ function runDockerComposeUp(repoPath, composeFiles, overlayPath, services) {
     throw new Error(`docker compose up failed: ${withDockerFailureGuidance(details || "unknown error")}`);
   }
 }
-function queryRunningComposeServices(repoPath, composeFiles, overlayPath, services) {
+function queryRunningComposeServices(repoPath, composeFiles2, overlayPath, services) {
   const fileArgs = [];
-  for (const composeFile of composeFiles) {
+  for (const composeFile of composeFiles2) {
     const resolved = assertPathWithinRepo(composeFile, repoPath, "composeFiles");
     fileArgs.push("-f", resolved);
   }
@@ -4655,7 +6648,7 @@ function queryRunningComposeServices(repoPath, composeFiles, overlayPath, servic
     "--services",
     ...services
   ];
-  const result = (0, import_node_child_process8.spawnSync)("docker", args, {
+  const result = (0, import_node_child_process10.spawnSync)("docker", args, {
     encoding: "utf-8",
     cwd: repoPath
   });
@@ -4674,14 +6667,14 @@ function queryRunningComposeServices(repoPath, composeFiles, overlayPath, servic
     runningServices
   };
 }
-function runDockerComposeStop(repoPath, composeFiles, overlayPath, services) {
+function runDockerComposeStop(repoPath, composeFiles2, overlayPath, services) {
   const fileArgs = [];
-  for (const composeFile of composeFiles) {
+  for (const composeFile of composeFiles2) {
     const resolved = assertPathWithinRepo(composeFile, repoPath, "composeFiles");
     fileArgs.push("-f", resolved);
   }
   const args = ["compose", ...fileArgs, "-f", overlayPath, "stop", ...services];
-  const result = (0, import_node_child_process8.spawnSync)("docker", args, {
+  const result = (0, import_node_child_process10.spawnSync)("docker", args, {
     encoding: "utf-8",
     cwd: repoPath
   });
@@ -4691,26 +6684,26 @@ function runDockerComposeStop(repoPath, composeFiles, overlayPath, services) {
 `);
   }
 }
-function runDockerComposeLogs(repoPath, composeFiles, overlayPath, services, tail = 20) {
+function runDockerComposeLogs(repoPath, composeFiles2, overlayPath, services, tail = 20) {
   const fileArgs = [];
-  for (const composeFile of composeFiles) {
+  for (const composeFile of composeFiles2) {
     const resolved = assertPathWithinRepo(composeFile, repoPath, "composeFiles");
     fileArgs.push("-f", resolved);
   }
   const args = ["compose", ...fileArgs, "-f", overlayPath, "logs", "--tail", String(tail), ...services];
-  (0, import_node_child_process8.spawnSync)("docker", args, {
+  (0, import_node_child_process10.spawnSync)("docker", args, {
     stdio: "inherit",
     cwd: repoPath
   });
 }
-function queryMappedPort(repoPath, composeFiles, overlayPath, service, internalPort) {
+function queryMappedPort(repoPath, composeFiles2, overlayPath, service, internalPort) {
   const fileArgs = [];
-  for (const composeFile of composeFiles) {
+  for (const composeFile of composeFiles2) {
     const resolved = assertPathWithinRepo(composeFile, repoPath, "composeFiles");
     fileArgs.push("-f", resolved);
   }
   const args = ["compose", ...fileArgs, "-f", overlayPath, "port", service, String(internalPort)];
-  const result = (0, import_node_child_process8.spawnSync)("docker", args, {
+  const result = (0, import_node_child_process10.spawnSync)("docker", args, {
     encoding: "utf-8",
     cwd: repoPath
   });
@@ -4724,21 +6717,154 @@ function queryMappedPort(repoPath, composeFiles, overlayPath, service, internalP
   const port = Number(match[1]);
   return Number.isInteger(port) && port > 0 ? port : void 0;
 }
-var import_node_fs11, import_node_path9, import_node_crypto2, import_node_child_process8, import_yaml4;
+var import_node_fs16, import_node_path15, import_node_crypto2, import_node_child_process10, import_yaml6;
 var init_docker_run = __esm({
   "src/core/docker-run.ts"() {
     "use strict";
-    import_node_fs11 = __toESM(require("fs"));
-    import_node_path9 = __toESM(require("path"));
+    import_node_fs16 = __toESM(require("fs"));
+    import_node_path15 = __toESM(require("path"));
     import_node_crypto2 = require("crypto");
-    import_node_child_process8 = require("child_process");
-    import_yaml4 = __toESM(require("yaml"));
+    import_node_child_process10 = require("child_process");
+    import_yaml6 = __toESM(require("yaml"));
     init_router();
     init_paths();
     init_docker_error_guidance();
   }
 });
 
+// src/core/dependency-runtime-plan.ts
+function uniqueApps(apps) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const app of apps) {
+    byName.set(app.name, app);
+  }
+  return Array.from(byName.values());
+}
+function dependencyNames(apps) {
+  return apps.map((entry) => entry.name).sort();
+}
+function planDependencyRuntime(options) {
+  const selectedApps = uniqueApps([options.app, ...options.dependencies]);
+  const selectedDockerApps = selectedApps.filter(
+    (entry) => entry.runtime === "docker"
+  );
+  const services = selectedDockerApps.map((entry) => entry.docker.service);
+  const dependencyServices = options.dependencies.filter((entry) => entry.runtime === "docker").map((entry) => entry.docker.service);
+  const runningServices = options.runningServicesBefore?.status === "known" ? options.runningServicesBefore.runningServices : void 0;
+  const allDependencyServicesRunning = runningServices !== void 0 && dependencyServices.every((service) => runningServices.has(service));
+  const hasTcpDeps = options.app.runtime === "host" && selectedDockerApps.some(
+    (entry) => entry.kind !== "dependency" && entry.protocol === "tcp"
+  );
+  return {
+    app: options.app,
+    dependencies: options.dependencies,
+    selectedApps,
+    selectedDockerApps,
+    services,
+    dependencyServices,
+    stopPolicy: options.stopPolicy ?? "always-stop-selected",
+    runningServicesBefore: options.runningServicesBefore,
+    allDependencyServicesRunning,
+    shouldPromptForDependencies: options.dependencies.length > 0 && !allDependencyServicesRunning,
+    hasTcpDeps
+  };
+}
+function planDependencyStart(runtimePlan, startDependencies) {
+  const shouldRunComposeUp = runtimePlan.app.runtime === "docker" || startDependencies;
+  if (!shouldRunComposeUp) {
+    return {
+      shouldRunComposeUp,
+      startedServices: [],
+      dependencyApps: []
+    };
+  }
+  if (runtimePlan.stopPolicy === "stop-only-newly-started") {
+    if (runtimePlan.runningServicesBefore?.status === "unknown") {
+      return {
+        shouldRunComposeUp,
+        startedServices: [],
+        dependencyApps: startDependencies ? dependencyNames(runtimePlan.dependencies) : [],
+        ownershipWarning: `unable to determine which dependencies were already running before 'dev app exec'; leaving dependencies running after command exit to avoid stopping non-owned services. Details: ${runtimePlan.runningServicesBefore.reason}`
+      };
+    }
+    const beforeSet2 = runtimePlan.runningServicesBefore?.status === "known" ? runtimePlan.runningServicesBefore.runningServices : void 0;
+    return {
+      shouldRunComposeUp,
+      startedServices: beforeSet2 ? runtimePlan.services.filter((service) => !beforeSet2.has(service)) : [],
+      dependencyApps: startDependencies ? dependencyNames(runtimePlan.dependencies) : []
+    };
+  }
+  const beforeSet = runtimePlan.app.runtime === "docker" && runtimePlan.runningServicesBefore?.status === "known" ? runtimePlan.runningServicesBefore.runningServices : void 0;
+  return {
+    shouldRunComposeUp,
+    startedServices: runtimePlan.app.runtime === "docker" ? runtimePlan.services.filter((service) => !beforeSet?.has(service)) : [...runtimePlan.services],
+    dependencyApps: startDependencies ? dependencyNames(runtimePlan.dependencies) : []
+  };
+}
+function buildTcpDepUrl(tcpProtocol, port) {
+  switch (tcpProtocol) {
+    case "postgres":
+      return buildPostgresDependencyUrl(port);
+    case "redis":
+      return `redis://localhost:${port}`;
+    case "mysql":
+    case "mariadb":
+      return `mysql://root@localhost:${port}`;
+    default:
+      return void 0;
+  }
+}
+function buildTcpDepShadowUrl(tcpProtocol, port) {
+  if (tcpProtocol === "postgres") {
+    return buildPostgresDependencyShadowUrl(port);
+  }
+  return void 0;
+}
+function buildDependencyEnv(mappedDeps) {
+  const depEnv = {};
+  const [hostSuffix, portSuffix, urlSuffix, shadowUrlSuffix] = DEP_ENV_SUFFIXES;
+  for (const { app, mappedPort } of mappedDeps) {
+    if (mappedPort === void 0) {
+      continue;
+    }
+    const envPrefix = app.name.toUpperCase().replace(/-/g, "_");
+    depEnv[`${envPrefix}_${hostSuffix}`] = "localhost";
+    depEnv[`${envPrefix}_${portSuffix}`] = String(mappedPort);
+    const url = buildTcpDepUrl(app.tcpProtocol, mappedPort);
+    if (url) {
+      depEnv[`${envPrefix}_${urlSuffix}`] = url;
+    }
+    const shadowUrl = buildTcpDepShadowUrl(app.tcpProtocol, mappedPort);
+    if (shadowUrl) {
+      depEnv[`${envPrefix}_${shadowUrlSuffix}`] = shadowUrl;
+    }
+  }
+  return depEnv;
+}
+function applyDependencyEnvMap(app, depEnv) {
+  const mappedEnv = { ...depEnv };
+  for (const depRef of app.dependencies) {
+    if (!depRef.envMap) {
+      continue;
+    }
+    for (const [target, source] of Object.entries(depRef.envMap)) {
+      if (!(source in mappedEnv)) {
+        throw new Error(
+          `envMap on dependency '${depRef.app}': source variable '${source}' not found in dependency env. Available: ${Object.keys(mappedEnv).join(", ") || "(none)"}`
+        );
+      }
+      mappedEnv[target] = mappedEnv[source];
+    }
+  }
+  return mappedEnv;
+}
+var init_dependency_runtime_plan = __esm({
+  "src/core/dependency-runtime-plan.ts"() {
+    "use strict";
+    init_capabilities();
+  }
+});
+
 // src/core/app-run.ts
 function wrapWithSecretManager(smCommand, reinjectEnv, userCommand, shell) {
   const envPairs = Object.entries(reinjectEnv).map(([k, v]) => `${k}=${v}`);
@@ -4779,6 +6905,21 @@ function toError(error) {
   }
   return new Error(String(error));
 }
+function dependencyNames2(apps) {
+  return apps.map((entry) => entry.name).sort();
+}
+function observedRuntimeServices(result) {
+  if (!result) {
+    return void 0;
+  }
+  if (result.status === "known") {
+    return { status: "known", runningServices: result.runningServices };
+  }
+  return { status: "unknown", reason: result.reason };
+}
+function isDependencyOnlyApp(app) {
+  return app.kind === "dependency";
+}
 function normalizeProcessEnv(env) {
   const normalized = {};
   for (const [key, value] of Object.entries(env)) {
@@ -4794,25 +6935,6 @@ function buildExecEnvironment(depEnv, processEnv = process.env) {
     ...depEnv
   };
 }
-function buildTcpDepUrl(tcpProtocol, port) {
-  switch (tcpProtocol) {
-    case "postgres":
-      return `postgres://prisma:prisma@localhost:${port}/prisma`;
-    case "redis":
-      return `redis://localhost:${port}`;
-    case "mysql":
-    case "mariadb":
-      return `mysql://root@localhost:${port}`;
-    default:
-      return void 0;
-  }
-}
-function buildTcpDepShadowUrl(tcpProtocol, port) {
-  if (tcpProtocol === "postgres") {
-    return `postgres://prisma:prisma@localhost:${port}/shadow`;
-  }
-  return void 0;
-}
 function isProcessRunning(pid) {
   if (!Number.isInteger(pid) || pid <= 0) {
     return false;
@@ -4825,7 +6947,7 @@ function isProcessRunning(pid) {
   }
 }
 function readProcessTree(rootPid) {
-  const result = (0, import_node_child_process9.spawnSync)("ps", ["-ax", "-o", "pid=,ppid="], { encoding: "utf-8" });
+  const result = (0, import_node_child_process11.spawnSync)("ps", ["-ax", "-o", "pid=,ppid="], { encoding: "utf-8" });
   if (result.status !== 0) {
     return [rootPid];
   }
@@ -4907,7 +7029,7 @@ function detectListeningPorts(pids) {
   if (pids.length === 0) {
     return [];
   }
-  const result = (0, import_node_child_process9.spawnSync)(
+  const result = (0, import_node_child_process11.spawnSync)(
     "lsof",
     ["-nP", "-iTCP", "-sTCP:LISTEN", "-a", "-p", pids.join(",")],
     { encoding: "utf-8" }
@@ -4966,7 +7088,7 @@ async function runHostApp(repoPath, app, extraEnv = {}, secretManager, env, work
     app.hostRun.command,
     true
   ) : app.hostRun.command;
-  const child = (0, import_node_child_process9.spawn)(spawnCommand, {
+  const child = (0, import_node_child_process11.spawn)(spawnCommand, {
     cwd: commandCwd,
     stdio: "inherit",
     shell: true,
@@ -5049,19 +7171,6 @@ async function runHostApp(repoPath, app, extraEnv = {}, secretManager, env, work
     throw new Error(`Host command for '${app.name}' exited with code ${exit.code}.`);
   }
 }
-function uniqueApps(apps) {
-  const byName = /* @__PURE__ */ new Map();
-  for (const app of apps) {
-    byName.set(app.name, app);
-  }
-  return Array.from(byName.values());
-}
-function dependencyNames(apps) {
-  return apps.map((entry) => entry.name).sort();
-}
-function isDependencyOnlyApp(app) {
-  return app.kind === "dependency";
-}
 async function shouldStartDependencies(appName, dependencies, yes) {
   if (dependencies.length === 0) {
     return false;
@@ -5071,7 +7180,7 @@ async function shouldStartDependencies(appName, dependencies, yes) {
   }
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
     throw new Error(
-      `App '${appName}' has dependencies (${dependencyNames(
+      `App '${appName}' has dependencies (${dependencyNames2(
         dependencies
       ).join(", ")}). Re-run with --yes in non-interactive mode.`
     );
@@ -5079,7 +7188,7 @@ async function shouldStartDependencies(appName, dependencies, yes) {
   const rl = (0, import_promises2.createInterface)({ input: import_node_process2.stdin, output: import_node_process2.stdout });
   try {
     const answer = await rl.question(
-      `Start dependencies for '${appName}' (${dependencyNames(dependencies).join(", ")})? [y/N] `
+      `Start dependencies for '${appName}' (${dependencyNames2(dependencies).join(", ")})? [y/N] `
     );
     return /^y(es)?$/i.test(answer.trim());
   } finally {
@@ -5110,74 +7219,53 @@ async function startAppDependencies(options) {
   const unsupportedDependencies = dependencies.filter((entry) => entry.runtime !== "docker");
   if (unsupportedDependencies.length > 0) {
     throw new Error(
-      `App '${app.name}' has host-runtime dependencies (${dependencyNames(
+      `App '${app.name}' has host-runtime dependencies (${dependencyNames2(
         unsupportedDependencies
       ).join(", ")}). v1 only auto-starts docker dependencies. Start host dependencies manually before running this app.`
     );
   }
-  const selectedApps = uniqueApps([app, ...dependencies]);
-  const selectedDockerApps = selectedApps.filter(
-    (entry) => entry.runtime === "docker"
-  );
   const stopPolicy = options.stopPolicy ?? "always-stop-selected";
   const startedServices = [];
   let overlay;
   let startDependencies = false;
-  const hasTcpDeps = app.runtime === "host" && selectedDockerApps.some(
-    (entry) => entry.kind !== "dependency" && entry.protocol === "tcp"
-  );
-  if (selectedDockerApps.length > 0) {
-    overlay = prepareDockerOverlay(repoPath, app.name, selectedDockerApps, hasTcpDeps);
-    const services = selectedDockerApps.map((entry) => entry.docker.service);
-    const depServices = dependencies.filter((entry) => entry.runtime === "docker").map((entry) => entry.docker.service);
-    let runningServicesBefore = null;
-    let ownershipKnown = true;
-    const preRunResult = depServices.length > 0 ? queryRunningComposeServices(repoPath, overlay.composeFiles, overlay.overlayPath, depServices) : void 0;
-    const allDepsRunning = preRunResult?.status === "known" && depServices.every((s) => preRunResult.runningServices.has(s));
-    if (allDepsRunning) {
+  const basePlan = planDependencyRuntime({ app, dependencies, stopPolicy });
+  let observedPlan = basePlan;
+  let startPlan = planDependencyStart(observedPlan, false);
+  if (basePlan.selectedDockerApps.length > 0) {
+    overlay = prepareDockerOverlay(repoPath, app.name, basePlan.selectedDockerApps, basePlan.hasTcpDeps);
+    const preRunResult = basePlan.dependencyServices.length > 0 ? queryRunningComposeServices(repoPath, overlay.composeFiles, overlay.overlayPath, basePlan.dependencyServices) : void 0;
+    observedPlan = planDependencyRuntime({
+      app,
+      dependencies,
+      stopPolicy,
+      runningServicesBefore: observedRuntimeServices(preRunResult)
+    });
+    if (observedPlan.allDependencyServicesRunning) {
       startDependencies = false;
-    } else if (dependencies.length > 0) {
+    } else if (observedPlan.shouldPromptForDependencies) {
       startDependencies = await shouldStartDependencies(
         app.name,
         dependencies,
         Boolean(options.yes)
       );
-    } else {
-      startDependencies = false;
     }
-    const shouldRunComposeUp = app.runtime === "docker" || startDependencies;
-    if (shouldRunComposeUp) {
-      if (stopPolicy === "stop-only-newly-started") {
-        if (preRunResult?.status === "known") {
-          runningServicesBefore = preRunResult.runningServices;
-        } else if (preRunResult?.status === "unknown") {
-          ownershipKnown = false;
-          process.stderr.write(
-            `Warning: unable to determine which dependencies were already running before 'dev app exec'; leaving dependencies running after command exit to avoid stopping non-owned services. Details: ${preRunResult.reason}
-`
-          );
-        }
-      }
-      runDockerComposeUp(repoPath, overlay.composeFiles, overlay.overlayPath, services);
-      if (stopPolicy === "stop-only-newly-started") {
-        const beforeSet = runningServicesBefore;
-        if (ownershipKnown && beforeSet) {
-          startedServices.push(...services.filter((service) => !beforeSet.has(service)));
-        }
-      } else if (app.runtime === "docker") {
-        const beforeSet = preRunResult?.status === "known" ? preRunResult.runningServices : void 0;
-        startedServices.push(...services.filter((service) => !beforeSet?.has(service)));
-      } else {
-        startedServices.push(...services);
-      }
-      runDockerComposeLogs(repoPath, overlay.composeFiles, overlay.overlayPath, services);
+    startPlan = planDependencyStart(observedPlan, startDependencies);
+    if (startPlan.ownershipWarning) {
+      process.stderr.write(`Warning: ${startPlan.ownershipWarning}
+`);
+    }
+    if (startPlan.shouldRunComposeUp) {
+      runDockerComposeUp(repoPath, overlay.composeFiles, overlay.overlayPath, observedPlan.services);
+      startedServices.push(...startPlan.startedServices);
+      runDockerComposeLogs(repoPath, overlay.composeFiles, overlay.overlayPath, observedPlan.services);
     }
   }
-  const depEnv = {};
-  if (hasTcpDeps && overlay) {
-    const tcpDeps = selectedDockerApps.filter(
+  let depEnv = {};
+  if (observedPlan.hasTcpDeps && overlay) {
+    const tcpDeps = observedPlan.selectedDockerApps.filter(
       (entry) => entry.kind !== "dependency" && entry.protocol === "tcp"
     );
+    const mappedDeps = [];
     let routerRestarted = false;
     for (const dep of tcpDeps) {
       const needsRestart = activateTcpProtocol(dep.tcpProtocol);
@@ -5196,18 +7284,11 @@ async function startAppDependencies(options) {
         dep.docker.service,
         dep.docker.internalPort
       );
+      mappedDeps.push({ app: dep, mappedPort });
       if (mappedPort !== void 0) {
         const envPrefix = dep.name.toUpperCase().replace(/-/g, "_");
-        depEnv[`${envPrefix}_HOST`] = "localhost";
-        depEnv[`${envPrefix}_PORT`] = String(mappedPort);
         const url = buildTcpDepUrl(dep.tcpProtocol, mappedPort);
-        if (url) {
-          depEnv[`${envPrefix}_URL`] = url;
-        }
         const shadowUrl = buildTcpDepShadowUrl(dep.tcpProtocol, mappedPort);
-        if (shadowUrl) {
-          depEnv[`${envPrefix}_SHADOW_URL`] = shadowUrl;
-        }
         process.stdout.write(`Dependency ${dep.name} available at localhost:${mappedPort}
 `);
         if (url) {
@@ -5220,19 +7301,9 @@ async function startAppDependencies(options) {
         }
       }
     }
+    depEnv = buildDependencyEnv(mappedDeps);
   }
-  for (const depRef of app.dependencies) {
-    if (depRef.envMap) {
-      for (const [target, source] of Object.entries(depRef.envMap)) {
-        if (!(source in depEnv)) {
-          throw new Error(
-            `envMap on dependency '${depRef.app}': source variable '${source}' not found in dependency env. Available: ${Object.keys(depEnv).join(", ") || "(none)"}`
-          );
-        }
-        depEnv[target] = depEnv[source];
-      }
-    }
-  }
+  depEnv = applyDependencyEnvMap(app, depEnv);
   const stopDeps = () => {
     if (startedServices.length > 0 && overlay) {
       process.stdout.write(`Stopping dependencies (${startedServices.join(", ")})...
@@ -5254,12 +7325,12 @@ async function startAppDependencies(options) {
     secretManager: config.secretManager,
     overlay,
     startedServices,
-    dependencyApps: startDependencies ? dependencyNames(dependencies) : [],
+    dependencyApps: startPlan.dependencyApps,
     stopDeps
   };
 }
-function registerProxyRoute(repoPath, app, workspace) {
-  const { port, upstreamHost } = parseUpstream(app.upstream);
+function registerProxyRoute2(repoPath, app, workspace) {
+  const { port, upstreamHost: upstreamHost2 } = parseUpstream(app.upstream);
   if (app.protocol === "tcp" && !isTLSEnabled()) {
     throw new Error(
       `App "${app.name}" is a TCP proxy route, which requires TLS (SNI). Run \`dev tls install\` first.`
@@ -5273,7 +7344,7 @@ function registerProxyRoute(repoPath, app, workspace) {
       startRouterStack();
     }
   }
-  removeHostRouteById(buildHostRouteId(repoPath, app.name));
+  removeRouteForApp(repoPath, app.name);
   assertAppNotRunning(repoPath, { name: app.name, host: app.host });
   upsertHostRoute({
     name: app.name,
@@ -5282,7 +7353,7 @@ function registerProxyRoute(repoPath, app, workspace) {
     tcpProtocol: app.protocol === "tcp" ? app.tcpProtocol : void 0,
     repoPath,
     port,
-    upstreamHost,
+    upstreamHost: upstreamHost2,
     mode: "proxy",
     workspace
   });
@@ -5304,7 +7375,7 @@ async function runConfiguredApp(options) {
     if (deps.app.runtime === "host") {
       await runHostApp(deps.repoPath, deps.app, deps.depEnv, deps.secretManager, options.env, deps.workspace);
     } else if (deps.app.runtime === "proxy") {
-      registerProxyRoute(deps.repoPath, deps.app, deps.workspace);
+      registerProxyRoute2(deps.repoPath, deps.app, deps.workspace);
     } else if (deps.app.kind !== "dependency" && deps.app.protocol === "tcp") {
       const registryEntry = TCP_PROTOCOL_REGISTRY[deps.app.tcpProtocol];
       const port = registryEntry?.port ?? "?";
@@ -5354,7 +7425,7 @@ async function execWithAppEnv(options) {
           options.command[0],
           true
         );
-        child = (0, import_node_child_process9.spawn)(wrapped, {
+        child = (0, import_node_child_process11.spawn)(wrapped, {
           cwd: deps.repoPath,
           stdio: "inherit",
           shell: true,
@@ -5368,7 +7439,7 @@ async function execWithAppEnv(options) {
           false
         );
         const [cmd, ...wrappedArgs] = wrapped;
-        child = (0, import_node_child_process9.spawn)(cmd, wrappedArgs, {
+        child = (0, import_node_child_process11.spawn)(cmd, wrappedArgs, {
           cwd: deps.repoPath,
           stdio: "inherit",
           shell: false,
@@ -5376,7 +7447,7 @@ async function execWithAppEnv(options) {
         });
       }
     } else if (options.shell) {
-      child = (0, import_node_child_process9.spawn)(options.command[0], {
+      child = (0, import_node_child_process11.spawn)(options.command[0], {
         cwd: deps.repoPath,
         stdio: "inherit",
         shell: true,
@@ -5384,7 +7455,7 @@ async function execWithAppEnv(options) {
       });
     } else {
       const [command, ...args] = options.command;
-      child = (0, import_node_child_process9.spawn)(command, args, {
+      child = (0, import_node_child_process11.spawn)(command, args, {
         cwd: deps.repoPath,
         stdio: "inherit",
         shell: false,
@@ -5403,22 +7474,25 @@ async function execWithAppEnv(options) {
     deps.stopDeps();
   }
 }
-var import_node_net, import_promises2, import_node_child_process9, import_node_process2, POLL_INTERVAL_MS, DEFAULT_PORT_TIMEOUT_MS, PROCESS_TERMINATION_GRACE_MS;
+var import_node_net, import_promises2, import_node_child_process11, import_node_process2, POLL_INTERVAL_MS, DEFAULT_PORT_TIMEOUT_MS, PROCESS_TERMINATION_GRACE_MS;
 var init_app_run = __esm({
   "src/core/app-run.ts"() {
     "use strict";
     import_node_net = __toESM(require("net"));
     import_promises2 = require("readline/promises");
-    import_node_child_process9 = require("child_process");
+    import_node_child_process11 = require("child_process");
     import_node_process2 = require("process");
     init_docker_run();
     init_repo_config();
     init_host_routes();
     init_concurrency();
+    init_route_state();
     init_docker();
     init_router();
     init_paths();
     init_tls();
+    init_dependency_runtime_plan();
+    init_dependency_runtime_plan();
     POLL_INTERVAL_MS = 1e3;
     DEFAULT_PORT_TIMEOUT_MS = 12e4;
     PROCESS_TERMINATION_GRACE_MS = 3e3;
@@ -5490,31 +7564,27 @@ __export(app_rm_exports, {
 async function runAppRmCommand(options) {
   const repoPath = resolveRepoPath(options.repo);
   if (options.keepConfig) {
-    try {
-      removeHostRouteByName(options.name, repoPath);
+    if (removeRouteForApp(repoPath, options.name).length > 0) {
       process.stdout.write(`Freed route for '${options.name}' (config left intact)
 `);
-    } catch {
-      process.stdout.write(`No active route for '${options.name}' (config left intact)
-`);
+      return;
     }
+    process.stdout.write(`No active route for '${options.name}' (config left intact)
+`);
     return;
   }
   const result = removeRepoApp(repoPath, options.name);
   if (!result.removed) {
     throw new Error(`App '${options.name}' not found in ${result.configPath}.`);
   }
-  try {
-    removeHostRouteByName(options.name, repoPath);
-  } catch {
-  }
+  removeRouteForApp(repoPath, options.name);
   process.stdout.write(`Removed '${options.name}' from ${result.configPath}
 `);
 }
 var init_app_rm = __esm({
   "src/commands/app-rm.ts"() {
     "use strict";
-    init_host_routes();
+    init_route_state();
     init_repo_config();
   }
 });
@@ -5541,11 +7611,11 @@ var init_tls2 = __esm({
 
 // src/core/workspace-lifecycle.ts
 function hasDevpod() {
-  const result = (0, import_node_child_process10.spawnSync)("devpod", ["version"], { encoding: "utf-8" });
+  const result = (0, import_node_child_process12.spawnSync)("devpod", ["version"], { encoding: "utf-8" });
   return result.status === 0;
 }
 function listGitWorktrees(repoPath) {
-  const result = (0, import_node_child_process10.spawnSync)("git", ["-C", repoPath, "worktree", "list", "--porcelain"], {
+  const result = (0, import_node_child_process12.spawnSync)("git", ["-C", repoPath, "worktree", "list", "--porcelain"], {
     encoding: "utf-8"
   });
   if (result.status !== 0) {
@@ -5569,18 +7639,7 @@ function listGitWorktrees(repoPath) {
   return worktrees;
 }
 function defaultWorktreePath(mainRepo, ws) {
-  return import_node_path10.default.join(import_node_path10.default.dirname(mainRepo), `${import_node_path10.default.basename(mainRepo)}-${ws}`);
-}
-function comparablePath(filePath) {
-  const resolved = import_node_path10.default.resolve(filePath);
-  try {
-    return import_node_fs12.default.realpathSync.native(resolved);
-  } catch {
-    return resolved;
-  }
-}
-function samePath(left, right) {
-  return comparablePath(left) === comparablePath(right);
+  return import_node_path16.default.join(import_node_path16.default.dirname(mainRepo), `${import_node_path16.default.basename(mainRepo)}-${ws}`);
 }
 async function workspaceUp(branch, opts = {}) {
   const mainRepo = resolveRepoPath(opts.repoPath);
@@ -5588,16 +7647,16 @@ async function workspaceUp(branch, opts = {}) {
   if (!ws) {
     throw new Error(`Branch '${branch}' does not yield a valid workspace token.`);
   }
-  const worktreePath = opts.path ? import_node_path10.default.resolve(opts.path) : defaultWorktreePath(mainRepo, ws);
-  if (import_node_fs12.default.existsSync(worktreePath)) {
+  const worktreePath = opts.path ? import_node_path16.default.resolve(opts.path) : defaultWorktreePath(mainRepo, ws);
+  if (import_node_fs17.default.existsSync(worktreePath)) {
     process.stdout.write(`Worktree already exists: ${worktreePath}
 `);
   } else {
-    const add = (0, import_node_child_process10.spawnSync)("git", ["-C", mainRepo, "worktree", "add", worktreePath, branch], {
+    const add = (0, import_node_child_process12.spawnSync)("git", ["-C", mainRepo, "worktree", "add", worktreePath, branch], {
       encoding: "utf-8"
     });
     if (add.status !== 0) {
-      const addNew = (0, import_node_child_process10.spawnSync)("git", ["-C", mainRepo, "worktree", "add", "-b", branch, worktreePath], {
+      const addNew = (0, import_node_child_process12.spawnSync)("git", ["-C", mainRepo, "worktree", "add", "-b", branch, worktreePath], {
         encoding: "utf-8"
       });
       if (addNew.status !== 0) {
@@ -5609,7 +7668,7 @@ async function workspaceUp(branch, opts = {}) {
 `);
   }
   if (!opts.noDevpod && hasDevpod()) {
-    const dp = (0, import_node_child_process10.spawnSync)("devpod", ["up", worktreePath, "--id", ws, "--open-ide=false"], {
+    const dp = (0, import_node_child_process12.spawnSync)("devpod", ["up", worktreePath, "--id", ws, "--open-ide=false"], {
       stdio: "inherit",
       env: { ...process.env, WORKSPACE: ws }
     });
@@ -5649,7 +7708,7 @@ ${urls.map((u) => `  ${u}`).join("\n")}
   }
   if (opts.open) {
     for (const url of openUrls) {
-      const opened = (0, import_node_child_process10.spawnSync)("open", [url], { encoding: "utf-8" });
+      const opened = (0, import_node_child_process12.spawnSync)("open", [url], { encoding: "utf-8" });
       if (opened.status !== 0) {
         const detail = [opened.stdout, opened.stderr].filter(Boolean).join("\n").trim();
         throw new Error(`Unable to open '${url}': ${detail || "unknown error"}`);
@@ -5662,10 +7721,10 @@ ${urls.map((u) => `  ${u}`).join("\n")}
 function workspaceLs(repoPath) {
   const mainRepo = resolveRepoPath(repoPath);
   const worktrees = listGitWorktrees(mainRepo);
-  const routes = listHostRouteState();
+  const routesByWorktreePath = listRoutesForWorktreePaths(worktrees.map((worktree) => worktree.path));
   return worktrees.map((wt) => {
     const workspace = isLinkedWorktree(wt.path) && wt.branch ? wsFromBranch(wt.branch) : void 0;
-    const wsRoutes = routes.filter((route) => samePath(route.repoPath, wt.path));
+    const wsRoutes = routesByWorktreePath.get(wt.path) ?? [];
     return {
       workspace,
       branch: wt.branch,
@@ -5685,20 +7744,15 @@ function workspaceDown(target, opts = {}) {
     (wt) => wt.branch && wsFromBranch(wt.branch) === ws
   );
   const worktreePath = match?.path ?? defaultWorktreePath(mainRepo, ws);
-  const routes = listHostRouteState().filter(
-    (route) => route.workspace === ws && samePath(route.repoPath, worktreePath)
-  );
-  for (const route of routes) {
-    removeHostRouteById(route.id);
-  }
+  const routes = removeWorkspaceRoutesForWorktree(ws, worktreePath);
   process.stdout.write(`Freed ${routes.length} route(s) for workspace '${ws}'.
 `);
   if (!opts.keepDevpod && hasDevpod()) {
-    (0, import_node_child_process10.spawnSync)("devpod", ["stop", ws], { stdio: "inherit" });
+    (0, import_node_child_process12.spawnSync)("devpod", ["stop", ws], { stdio: "inherit" });
   }
   if (!opts.keepWorktree) {
-    if (import_node_fs12.default.existsSync(worktreePath) && worktreePath !== mainRepo) {
-      const rm = (0, import_node_child_process10.spawnSync)("git", ["-C", mainRepo, "worktree", "remove", worktreePath], {
+    if (import_node_fs17.default.existsSync(worktreePath) && worktreePath !== mainRepo) {
+      const rm = (0, import_node_child_process12.spawnSync)("git", ["-C", mainRepo, "worktree", "remove", worktreePath], {
         encoding: "utf-8"
       });
       if (rm.status === 0) {
@@ -5714,15 +7768,15 @@ function workspaceDown(target, opts = {}) {
   }
   return { freedRoutes: routes.length, workspace: ws };
 }
-var import_node_fs12, import_node_path10, import_node_child_process10;
+var import_node_fs17, import_node_path16, import_node_child_process12;
 var init_workspace_lifecycle = __esm({
   "src/core/workspace-lifecycle.ts"() {
     "use strict";
-    import_node_fs12 = __toESM(require("fs"));
-    import_node_path10 = __toESM(require("path"));
-    import_node_child_process10 = require("child_process");
+    import_node_fs17 = __toESM(require("fs"));
+    import_node_path16 = __toESM(require("path"));
+    import_node_child_process12 = require("child_process");
     init_app_run();
-    init_host_routes();
+    init_route_state();
     init_repo_config();
     init_workspace();
   }
@@ -5812,12 +7866,12 @@ var init_version = __esm({
 
 // src/cli.ts
 var import_commander = require("commander");
-var CLI_VERSION = true ? "0.0.22" : "0.0.0-dev";
+var CLI_VERSION = true ? "0.0.23" : "0.0.0-dev";
 var VERSION_FLAGS = /* @__PURE__ */ new Set(["-V", "--version"]);
-function withErrorHandling(action) {
+function withErrorHandling(action2) {
   return async (...args) => {
     try {
-      await action(...args);
+      await action2(...args);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       process.stderr.write(`Error: ${message}
@@ -5837,6 +7891,10 @@ program.command("upgrade").description("Show upgrade targets from .devrouter.yml
   const { runUpgradeCommand: runUpgradeCommand2 } = await Promise.resolve().then(() => (init_upgrade2(), upgrade_exports));
   await runUpgradeCommand2({ targetVersion, repo: options.repo });
 }));
+program.command("setup").description("Run first-time devrouter machine setup and report diagnostics").option("--repo <path>", "Repository path for final diagnostics (defaults to current directory)").option("--yes", "Confirm non-interactive setup actions").option("--json", "Output JSON").action(withErrorHandling(async (options) => {
+  const { runSetupCommand: runSetupCommand2 } = await Promise.resolve().then(() => (init_setup2(), setup_exports));
+  await runSetupCommand2(options);
+}));
 program.command("up").description("Ensure devnet and start shared Traefik (reserves 80/443/5432)").action(withErrorHandling(async () => {
   const { runUpCommand: runUpCommand2 } = await Promise.resolve().then(() => (init_up(), up_exports));
   await runUpCommand2();
@@ -5870,10 +7928,23 @@ repoCommand.command("init").description("Initialize `.devrouter.yml` in a reposi
   const { runRepoInitCommand: runRepoInitCommand2 } = await Promise.resolve().then(() => (init_repo_init(), repo_init_exports));
   await runRepoInitCommand2({ ...options, installedVersion: CLI_VERSION });
 }));
+repoCommand.command("inspect").description("Inspect repository stack facts for agent-native onboarding").option("--repo <path>", "Repository path (defaults to current directory)").option("--json", "Output JSON").action(withErrorHandling(async (options) => {
+  const { runRepoInspectCommand: runRepoInspectCommand2 } = await Promise.resolve().then(() => (init_repo_inspect2(), repo_inspect_exports));
+  await runRepoInspectCommand2(options);
+}));
 repoCommand.command("agents").description("Write/update devrouter section in the repo's AGENTS.md").option("--repo <path>", "Repository path (defaults to current directory)").option("--with-linear", "Also install optional Linear workflow skill/assets and AGENTS section").action(withErrorHandling(async (options) => {
   const { runRepoAgentsCommand: runRepoAgentsCommand2 } = await Promise.resolve().then(() => (init_repo_agents(), repo_agents_exports));
   await runRepoAgentsCommand2(options);
 }));
+var repoDevcontainerCommand = repoCommand.command("devcontainer").description("Manage devcontainer onboarding");
+repoDevcontainerCommand.command("write").description("Plan or write a conservative devcontainer scaffold").option("--repo <path>", "Repository path (defaults to current directory)").option("--dry-run", "Print the planned file changes without writing").option("--yes", "Write files when no conflicts are detected").option("--json", "Output JSON").action(withErrorHandling(async (options) => {
+  const { runRepoDevcontainerWriteCommand: runRepoDevcontainerWriteCommand2 } = await Promise.resolve().then(() => (init_repo_devcontainer(), repo_devcontainer_exports));
+  await runRepoDevcontainerWriteCommand2({ ...options, installedVersion: CLI_VERSION });
+}));
+repoDevcontainerCommand.command("verify").description("Verify devcontainer onboarding state and emit PR evidence").option("--repo <path>", "Repository path (defaults to current directory)").option("--live", "Register proxy routes and probe HTTP routes").option("--yes", "Confirm live verification actions").option("--json", "Output JSON").action(withErrorHandling(async (options) => {
+  const { runRepoDevcontainerVerifyCommand: runRepoDevcontainerVerifyCommand2 } = await Promise.resolve().then(() => (init_repo_devcontainer(), repo_devcontainer_exports));
+  await runRepoDevcontainerVerifyCommand2(options);
+}));
 var appCommand = program.command("app").description("Manage app entries and runtime actions from `.devrouter.yml`");
 appCommand.command("add").description("Add or update one app definition in `.devrouter.yml`").requiredOption("--name <name>", "App name").option("--kind <kind>", "app or dependency", "app").option("--host <host>", "Hostname ending with .localhost (required for --kind app)").option("--protocol <protocol>", "http or tcp (required for --kind app)").option("--runtime <runtime>", "host, docker, or proxy (required for --kind app, optional for --kind dependency)").option("--service <service>", "Docker service name (runtime=docker)").option("--port <port>", "Internal port (runtime=docker)", (value) => Number(value)).option("--upstream <host:port>", "Already-running upstream to route to (runtime=proxy)").option("--compose-file <file>", "Compose file path (repeatable)", (value, prev) => {
   const next = prev ?? [];