@getmonoceros/workbench 1.7.4 → 1.8.0

package/dist/bin.js

@@ -251,25 +251,25 @@ function detectHelpRequest(argv, main2) {
   const separatorIdx = argv.indexOf("--");
   if (helpIdx === -1) return null;
   if (separatorIdx !== -1 && separatorIdx < helpIdx) return null;
-  const path15 = [];
+  const path16 = [];
   const tokens = argv.slice(
     0,
     separatorIdx === -1 ? argv.length : separatorIdx
   );
   let cursor = main2;
   const mainName = (main2.meta ?? {}).name ?? "monoceros";
-  path15.push(mainName);
+  path16.push(mainName);
   for (const tok of tokens) {
     if (tok.startsWith("-")) continue;
     const subs = cursor.subCommands ?? {};
     if (tok in subs) {
       cursor = subs[tok];
-      path15.push(tok);
+      path16.push(tok);
       continue;
     }
     break;
   }
-  return { path: path15, cmd: cursor };
+  return { path: path16, cmd: cursor };
 }
 async function maybeRenderHelp(argv, main2) {
   const hit = detectHelpRequest(argv, main2);
@@ -308,9 +308,10 @@ import { defineCommand } from "citty";
 import { consola as consola2 } from "consola";
 
 // src/modify/index.ts
-import { promises as fs6 } from "fs";
+import { promises as fs7 } from "fs";
 import { consola } from "consola";
 import { createPatch } from "diff";
+import path6 from "path";
 
 // src/config/io.ts
 import { promises as fs } from "fs";
@@ -346,11 +347,7 @@ var KNOWN_PROVIDER_HOSTS = {
   "bitbucket.org": "bitbucket"
 };
 var CONFIG_SCHEMA_VERSION = 1;
-var FeatureOptionValueSchema = z.union([
-  z.string(),
-  z.number(),
-  z.boolean()
-]);
+var FeatureOptionValueSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]).transform((v) => v === null ? "" : v);
 var FeatureEntrySchema = z.object({
   ref: z.string().regex(
     FEATURE_REF_RE,
@@ -358,9 +355,14 @@ var FeatureEntrySchema = z.object({
   ),
   options: z.record(z.string(), FeatureOptionValueSchema).optional()
 });
+var EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 var GitUserSchema = z.object({
-  name: z.string().min(1),
-  email: z.string().min(3).regex(/^[^\s@]+@[^\s@]+\.[^\s@]+$/, "Invalid email")
+  name: z.union([z.literal(""), z.null(), z.string().min(1)]).nullish().transform((v) => typeof v === "string" && v.length > 0 ? v : void 0),
+  email: z.union([
+    z.literal(""),
+    z.null(),
+    z.string().regex(EMAIL_RE, "Invalid email")
+  ]).nullish().transform((v) => typeof v === "string" && v.length > 0 ? v : void 0)
 });
 var RepoEntrySchema = z.object({
   url: z.string().regex(
@@ -567,222 +569,737 @@ function prettyPath(p) {
   return p;
 }
 
-// src/config/global.ts
+// src/devcontainer/credentials.ts
+import { spawn } from "child_process";
 import { promises as fs2 } from "fs";
-import { z as z2 } from "zod";
-import { parseDocument as parseDocument2 } from "yaml";
-var SCHEMA_VERSION = 1;
-var MonocerosConfigSchema = z2.object({
-  schemaVersion: z2.literal(SCHEMA_VERSION),
-  // .nullish() (= .optional().nullable()) on defaults so the shipped
-  // sample yml — where `defaults:` is uncommented but every sub-block
-  // is commented out — parses cleanly. YAML produces `defaults: null`
-  // in that case; without .nullish() the schema would reject it and
-  // we'd be back to forcing builders to comment-juggle three lines.
-  defaults: z2.object({
-    // .nullish() (not just .optional()) so the sample yml can leave
-    // `git:` uncommented as a category marker — YAML produces
-    // `git: null` for an empty mapping, which zod's plain
-    // `.optional()` would reject.
-    git: z2.object({
-      user: GitUserSchema.optional()
-    }).nullish(),
-    // .nullish() for the same reason as `git` — the sample keeps
-    // `features:` uncommented as a category marker.
-    features: z2.record(
-      z2.string().regex(
-        REGEX.featureRef,
-        "Invalid feature ref. Expected an OCI-image-style ref like 'ghcr.io/getmonoceros/monoceros-features/<name>:<tag>'."
-      ),
-      z2.record(z2.string(), FeatureOptionValueSchema)
-    ).nullish()
-  }).nullish(),
-  // Machine-global routing settings — one Traefik per builder, so
-  // host-port and similar live here rather than in any container yml.
-  // See ADR 0007.
-  routing: z2.object({
-    hostPort: z2.number().int().min(1).max(65535).optional().describe(
-      "Host port the Traefik singleton binds. Default 80. Set this when 80 is held by another service on your machine \u2014 URLs then become http://<name>.localhost:<port>/."
-    )
-  }).nullish()
-});
-async function readMonocerosConfig(opts = {}) {
-  const home = opts.monocerosHome ?? monocerosHome();
-  const filePath = monocerosConfigPath(home);
-  let text;
-  try {
-    text = await fs2.readFile(filePath, "utf8");
-  } catch {
-    return void 0;
-  }
-  const doc = parseDocument2(text, { prettyErrors: true });
-  if (doc.errors.length > 0) {
-    throw new Error(
-      `yaml parse error in ${filePath}: ${doc.errors[0].message}`
-    );
-  }
-  const result = MonocerosConfigSchema.safeParse(doc.toJS());
-  if (!result.success) {
-    const issues = result.error.issues.map((issue) => {
-      const where = issue.path.length > 0 ? issue.path.join(".") : "(root)";
-      return `  - ${where}: ${issue.message}`;
-    }).join("\n");
-    throw new Error(
-      `Invalid ${filePath}:
-${issues}
+import path2 from "path";
 
-See ${filePath.replace(
-        /\.yml$/,
-        ".sample.yml"
-      )} for a valid example.`
-    );
-  }
-  return result.data;
+// src/util/format.ts
+var ESC = "\x1B[";
+var ANSI_BOLD2 = `${ESC}1m`;
+var ANSI_UNDERLINE2 = `${ESC}4m`;
+var ANSI_CYAN2 = `${ESC}36m`;
+var ANSI_GREY2 = `${ESC}90m`;
+var ANSI_RESET2 = `${ESC}0m`;
+function makeWrap(isTty2) {
+  return (s, ...codes) => isTty2 ? codes.join("") + s + ANSI_RESET2 : s;
 }
-var DEFAULT_PROXY_HOST_PORT = 80;
-function proxyHostPort(config) {
-  return config?.routing?.hostPort ?? DEFAULT_PROXY_HOST_PORT;
+function makePalette(isTty2) {
+  const wrap = makeWrap(isTty2);
+  return {
+    bold: (s) => wrap(s, ANSI_BOLD2),
+    underline: (s) => wrap(s, ANSI_UNDERLINE2),
+    cyan: (s) => wrap(s, ANSI_CYAN2),
+    dim: (s) => wrap(s, ANSI_GREY2),
+    sectionLine: (label) => wrap(`\u25B8 ${label}`, ANSI_BOLD2, ANSI_UNDERLINE2)
+  };
+}
+function colorsFor(stream) {
+  return makePalette(stream.isTTY ?? false);
 }
+var stderrPalette = makePalette(process.stderr.isTTY ?? false);
+var bold2 = stderrPalette.bold;
+var underline2 = stderrPalette.underline;
+var cyan2 = stderrPalette.cyan;
+var dim = stderrPalette.dim;
+var sectionLine = stderrPalette.sectionLine;
 
-// src/proxy/index.ts
-import { spawn } from "child_process";
-import { promises as fs3 } from "fs";
-import path2 from "path";
-var PROXY_CONTAINER_NAME = "monoceros-proxy";
-var PROXY_NETWORK_NAME = "monoceros-proxy";
-var TRAEFIK_IMAGE = "traefik:v3.3";
-var defaultDockerExec = (args) => {
+// src/devcontainer/credentials.ts
+var realGitCredentialFill = (input) => {
   return new Promise((resolve, reject) => {
-    const child = spawn("docker", args, {
-      stdio: ["ignore", "pipe", "pipe"]
+    const child = spawn("git", ["credential", "fill"], {
+      stdio: ["pipe", "pipe", "inherit"],
+      env: {
+        ...process.env,
+        GIT_TERMINAL_PROMPT: "0",
+        GIT_ASKPASS: "",
+        SSH_ASKPASS: ""
+      }
     });
     let stdout = "";
-    let stderr = "";
     child.stdout.on("data", (chunk) => {
       stdout += chunk.toString();
     });
-    child.stderr.on("data", (chunk) => {
-      stderr += chunk.toString();
-    });
     child.on("error", reject);
-    child.on(
-      "exit",
-      (code) => resolve({ stdout, stderr, exitCode: code ?? 0 })
-    );
+    child.on("exit", (code) => resolve({ stdout, exitCode: code ?? 0 }));
+    child.stdin.write(input);
+    child.stdin.end();
   });
 };
-var realDocker = defaultDockerExec;
-function proxyDynamicDir(home) {
-  return path2.join(home ?? monocerosHome(), "traefik", "dynamic");
+function resolveProvider(host, explicit) {
+  const canonical = KNOWN_PROVIDER_HOSTS[host.toLowerCase()];
+  if (canonical) return canonical;
+  return explicit ?? "unknown";
 }
-async function ensureProxy(opts = {}) {
-  const docker = opts.docker ?? realDocker;
-  const dyn = proxyDynamicDir(opts.monocerosHome);
-  await fs3.mkdir(dyn, { recursive: true });
-  const netInspect = await docker(["network", "inspect", PROXY_NETWORK_NAME]);
-  if (netInspect.exitCode !== 0) {
-    const create = await docker(["network", "create", PROXY_NETWORK_NAME]);
-    if (create.exitCode !== 0) {
-      throw new Error(
-        `Could not create docker network ${PROXY_NETWORK_NAME}: ${create.stderr.trim() || `exit ${create.exitCode}`}`
-      );
-    }
-  }
-  const state = await docker([
-    "inspect",
-    "--format",
-    "{{.State.Running}}",
-    PROXY_CONTAINER_NAME
-  ]);
-  if (state.exitCode === 0) {
-    if (state.stdout.trim() === "true") return;
-    const start = await docker(["start", PROXY_CONTAINER_NAME]);
-    if (start.exitCode !== 0) {
-      throw new Error(
-        `Could not start existing ${PROXY_CONTAINER_NAME} container: ${start.stderr.trim() || `exit ${start.exitCode}`}`
-      );
+function uniqueHttpsHosts(repos) {
+  const byHost = /* @__PURE__ */ new Map();
+  for (const repo of repos) {
+    if (!repo.url.startsWith("https://")) continue;
+    let host;
+    try {
+      host = new URL(repo.url).hostname;
+    } catch {
+      continue;
     }
-    return;
-  }
-  const hostPort = opts.hostPort ?? 80;
-  const run = await docker([
-    "run",
-    "-d",
-    "--name",
-    PROXY_CONTAINER_NAME,
-    "--network",
-    PROXY_NETWORK_NAME,
-    "-p",
-    `${hostPort}:80`,
-    "-v",
-    `${dyn}:/etc/traefik/dynamic:ro`,
-    "--label",
-    "monoceros.role=proxy",
-    TRAEFIK_IMAGE,
-    "--entrypoints.web.address=:80",
-    "--providers.file.directory=/etc/traefik/dynamic",
-    "--providers.file.watch=true",
-    "--providers.docker=false",
-    "--api.dashboard=false",
-    "--log.level=INFO"
-  ]);
-  if (run.exitCode !== 0) {
-    throw new Error(
-      `Could not start ${PROXY_CONTAINER_NAME}: ${run.stderr.trim() || `exit ${run.exitCode}`}`
-    );
-  }
-  opts.logger?.info(
-    `Started ${PROXY_CONTAINER_NAME} (Traefik on :${hostPort}).`
-  );
-}
-async function maybeStopProxy(opts = {}) {
-  const docker = opts.docker ?? realDocker;
-  const logger = opts.logger;
-  const inspect = await docker([
-    "network",
-    "inspect",
-    PROXY_NETWORK_NAME,
-    "--format",
-    "{{range $k, $v := .Containers}}{{$v.Name}}\n{{end}}"
-  ]);
-  if (inspect.exitCode !== 0) {
-    return;
-  }
-  const others = inspect.stdout.split("\n").map((n) => n.trim()).filter((n) => n.length > 0 && n !== PROXY_CONTAINER_NAME);
-  if (others.length > 0) return;
-  await docker(["rm", "-f", PROXY_CONTAINER_NAME]);
-  const netRm = await docker(["network", "rm", PROXY_NETWORK_NAME]);
-  if (netRm.exitCode !== 0) {
-    logger?.warn?.(
-      `Could not remove docker network ${PROXY_NETWORK_NAME}: ${netRm.stderr.trim() || `exit ${netRm.exitCode}`}`
-    );
-    return;
+    if (byHost.has(host)) continue;
+    byHost.set(host, { host, provider: resolveProvider(host, repo.provider) });
   }
-  logger?.info(
-    `Stopped ${PROXY_CONTAINER_NAME} (no dev-containers with ports left).`
-  );
+  return [...byHost.values()];
 }
-
-// src/proxy/dynamic.ts
-import { promises as fs4 } from "fs";
-import path3 from "path";
-async function writeDynamicConfig(name, ports, opts = {}) {
-  if (ports.length === 0) {
-    throw new Error(
-      `writeDynamicConfig requires at least one port. For empty port lists, call removeDynamicConfig(${JSON.stringify(name)}).`
-    );
+function installCommandForOS(opts) {
+  switch (process.platform) {
+    case "darwin":
+      return cyan2(opts.brew);
+    case "win32":
+      return cyan2(opts.winget);
+    default:
+      if (opts.linuxBrew) return cyan2(opts.linuxBrew);
+      return `See ${opts.linuxDocsUrl} for package instructions.`;
   }
-  const dir = proxyDynamicDir(opts.monocerosHome);
-  await fs4.mkdir(dir, { recursive: true });
-  const file = path3.join(dir, `${name}.yml`);
-  await fs4.writeFile(file, renderDynamicConfig(name, ports), "utf8");
-  return file;
-}
-async function removeDynamicConfig(name, opts = {}) {
-  const file = path3.join(proxyDynamicDir(opts.monocerosHome), `${name}.yml`);
-  await fs4.rm(file, { force: true });
 }
-function renderDynamicConfig(name, ports) {
+function providerSetupHint(host, provider) {
+  if (provider === "github") {
+    const isSaas = host.toLowerCase() === "github.com";
+    const hostArg = isSaas ? "" : ` --hostname ${host}`;
+    const install = installCommandForOS({
+      brew: "brew install gh",
+      winget: "winget install --id GitHub.cli",
+      linuxBrew: "brew install gh",
+      linuxDocsUrl: "https://github.com/cli/cli#installation"
+    });
+    return {
+      title: `${host} \u2014 GitHub`,
+      body: [
+        "Install the GitHub CLI:",
+        install,
+        "",
+        "Then run once:",
+        cyan2(`gh auth login${hostArg}`),
+        cyan2(`gh auth setup-git${hostArg}`),
+        "",
+        "`gh auth login` walks through OAuth in your browser.",
+        "`gh auth setup-git` wires gh into git as a credential helper."
+      ].join("\n")
+    };
+  }
+  if (provider === "gitlab") {
+    const isSaas = host.toLowerCase() === "gitlab.com";
+    const hostArg = isSaas ? "" : ` --hostname ${host}`;
+    const install = installCommandForOS({
+      brew: "brew install glab",
+      winget: "winget install --id GLab.GLab",
+      linuxBrew: "brew install glab",
+      linuxDocsUrl: "https://gitlab.com/gitlab-org/cli#installation"
+    });
+    return {
+      title: `${host} \u2014 GitLab`,
+      body: [
+        "Install the GitLab CLI (glab):",
+        install,
+        "",
+        "Then run once:",
+        cyan2(`glab auth login${hostArg}`),
+        "",
+        "Choose `HTTPS` when asked for git-protocol, then accept",
+        '"Authenticate Git with your GitLab credentials" \u2014 glab',
+        "configures itself as the git credential helper."
+      ].join("\n")
+    };
+  }
+  if (provider === "bitbucket") {
+    const isCloud = host.toLowerCase() === "bitbucket.org";
+    if (isCloud) {
+      return {
+        title: `${host} \u2014 Bitbucket Cloud`,
+        body: [
+          "Bitbucket has no first-party CLI for git-credentials, so this",
+          "is a manual one-time setup. Generate an Atlassian API token at",
+          "https://id.atlassian.com/manage-profile/security/api-tokens",
+          "",
+          "Then store it via your OS credential helper:",
+          cyan2(
+            `git credential approve <<< $'protocol=https\\nhost=${host}\\nusername=<your-atlassian-email>\\npassword=<token>\\n'`
+          )
+        ].join("\n")
+      };
+    }
+    return {
+      title: `${host} \u2014 Bitbucket Data Center`,
+      body: [
+        "Bitbucket has no first-party CLI for git-credentials, so this",
+        "is a manual one-time setup. Generate a personal HTTP access",
+        `token in your Bitbucket UI: profile picture (top right on ${host})`,
+        "\u2192 Manage account \u2192 HTTP access tokens \u2192 Create token. Give it",
+        "at least repo-read + repo-write scopes for the repos you need.",
+        "",
+        "Then store it via your OS credential helper:",
+        cyan2(
+          `git credential approve <<< $'protocol=https\\nhost=${host}\\nusername=<your-bitbucket-username>\\npassword=<token>\\n'`
+        )
+      ].join("\n")
+    };
+  }
+  return {
+    title: `${host} \u2014 Gitea`,
+    body: [
+      "Gitea has no first-party CLI helper for git-credentials (the",
+      "`tea` CLI logs into its own config, not into your git credential",
+      "helper), so this is a manual one-time setup. Generate an access",
+      `token in your Gitea UI: profile picture (top right on ${host}) \u2192`,
+      'Settings \u2192 Applications \u2192 "Generate New Token". Give it at',
+      "least the `read:repository` scope (add `write:repository` if you",
+      "need push from the container).",
+      "",
+      "Then store it via your OS credential helper:",
+      cyan2(
+        `git credential approve <<< $'protocol=https\\nhost=${host}\\nusername=<your-gitea-username>\\npassword=<token>\\n'`
+      )
+    ].join("\n")
+  };
+}
+function parseCredentialFillOutput(output) {
+  const result = {};
+  for (const line of output.split("\n")) {
+    const eqIdx = line.indexOf("=");
+    if (eqIdx <= 0) continue;
+    const key = line.slice(0, eqIdx);
+    const value = line.slice(eqIdx + 1);
+    if (key === "username") result.username = value;
+    if (key === "password") result.password = value;
+  }
+  return result;
+}
+function formatCredentialLine(host, username, password) {
+  const encUser = encodeURIComponent(username);
+  const encPass = encodeURIComponent(password);
+  return `https://${encUser}:${encPass}@${host}`;
+}
+async function collectGitCredentials(devContainerRoot, hosts, options = {}) {
+  const credsDir = path2.join(devContainerRoot, ".monoceros");
+  const credentialsPath = path2.join(credsDir, "git-credentials");
+  const spawnFn = options.spawn ?? realGitCredentialFill;
+  const logger = options.logger ?? { info: () => {
+  }, warn: () => {
+  } };
+  const lines = [];
+  const perHost = [];
+  for (const { host, provider } of hosts) {
+    if (provider === "unknown") {
+      perHost.push({
+        host,
+        provider: "github",
+        // placeholder — never rendered because pre-flight already bailed
+        status: "no-credentials",
+        detail: "provider not declared (internal: should not reach here)"
+      });
+      continue;
+    }
+    logger.info(`Fetching credentials for ${host} from host git\u2026`);
+    const input = `protocol=https
+host=${host}
+
+`;
+    let result;
+    try {
+      result = await spawnFn(input);
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      perHost.push({ host, provider, status: "spawn-error", detail });
+      continue;
+    }
+    if (result.exitCode !== 0) {
+      perHost.push({
+        host,
+        provider,
+        status: "non-zero-exit",
+        detail: `exit code ${result.exitCode}`
+      });
+      continue;
+    }
+    const { username, password } = parseCredentialFillOutput(result.stdout);
+    if (!username || !password) {
+      perHost.push({
+        host,
+        provider,
+        status: "no-credentials",
+        detail: "host credential helper returned no username/password"
+      });
+      continue;
+    }
+    lines.push(formatCredentialLine(host, username, password));
+    perHost.push({ host, provider, status: "ok", detail: "" });
+  }
+  await fs2.mkdir(credsDir, { recursive: true });
+  await fs2.writeFile(
+    credentialsPath,
+    lines.join("\n") + (lines.length > 0 ? "\n" : ""),
+    {
+      mode: 384
+    }
+  );
+  return {
+    hostsWritten: lines.length,
+    hostsSkipped: perHost.filter((p) => p.status !== "ok").length,
+    perHost,
+    credentialsPath
+  };
+}
+function formatMissingCredentialsError(missing) {
+  if (missing.length === 1) {
+    const m = missing[0];
+    const hint = providerSetupHint(m.host, m.provider);
+    return [
+      `Missing Git credentials: ${hint.title}`,
+      "",
+      hint.body,
+      "",
+      `Then re-run ${cyan2("monoceros apply")}.`
+    ].join("\n");
+  }
+  const lines = [
+    `Missing Git credentials for ${missing.length} hosts:`,
+    ""
+  ];
+  for (const m of missing) {
+    const hint = providerSetupHint(m.host, m.provider);
+    lines.push(hint.title);
+    lines.push("");
+    lines.push(hint.body);
+    lines.push("");
+  }
+  lines.push(`Then re-run ${cyan2("monoceros apply")}.`);
+  return lines.join("\n");
+}
+function formatUnknownProviderError(hosts) {
+  const sorted = [...new Set(hosts)].sort();
+  const lines = [
+    sorted.length === 1 ? `Unknown Git provider for host ${sorted[0]}.` : `Unknown Git provider for ${sorted.length} hosts: ${sorted.join(", ")}.`,
+    "",
+    "Monoceros auto-detects only github.com / gitlab.com / bitbucket.org.",
+    "For any other host (self-hosted GitLab, Gitea, Bitbucket Server, \u2026)",
+    "declare the provider explicitly in the yml. Edit the repo entry:",
+    "",
+    cyan2("  repos:"),
+    cyan2(`    - url: https://${sorted[0]}/\u2026`),
+    cyan2("      provider: gitlab   # or: github, bitbucket, gitea"),
+    "",
+    `Or re-add with ${cyan2("monoceros add-repo <name> <url> --provider=<github|gitlab|bitbucket|gitea>")}.`
+  ];
+  return lines.join("\n");
+}
+
+// src/devcontainer/locate-running.ts
+import { spawn as spawn2 } from "child_process";
+var realDockerLookup = (args) => {
+  return new Promise((resolve, reject) => {
+    const child = spawn2("docker", args, {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", reject);
+    child.on(
+      "exit",
+      (code) => resolve({ stdout, stderr, exitCode: code ?? 0 })
+    );
+  });
+};
+async function findRunningContainerByLocalFolder(containerPath, opts = {}) {
+  const docker = opts.docker ?? realDockerLookup;
+  const result = await docker([
+    "ps",
+    "-q",
+    "--filter",
+    `label=devcontainer.local_folder=${containerPath}`,
+    "--filter",
+    "status=running"
+  ]);
+  if (result.exitCode !== 0) return null;
+  const ids = result.stdout.split("\n").map((s) => s.trim()).filter((s) => s.length > 0);
+  return ids[0] ?? null;
+}
+var realContainerExec = (containerId, argv) => {
+  return new Promise((resolve, reject) => {
+    const child = spawn2("docker", ["exec", containerId, ...argv], {
+      // Inherit stdio so live git output reaches the user.
+      stdio: ["ignore", "inherit", "inherit"]
+    });
+    child.on("error", reject);
+    child.on("exit", (code) => resolve({ exitCode: code ?? 0 }));
+  });
+};
+
+// src/config/global.ts
+import { promises as fs3 } from "fs";
+import { z as z2 } from "zod";
+import { isMap, Pair, parseDocument as parseDocument2, Scalar, YAMLMap } from "yaml";
+var SCHEMA_VERSION = 1;
+var MonocerosConfigSchema = z2.object({
+  schemaVersion: z2.literal(SCHEMA_VERSION),
+  // .nullish() (= .optional().nullable()) on defaults so the shipped
+  // sample yml — where `defaults:` is uncommented but every sub-block
+  // is commented out — parses cleanly. YAML produces `defaults: null`
+  // in that case; without .nullish() the schema would reject it and
+  // we'd be back to forcing builders to comment-juggle three lines.
+  defaults: z2.object({
+    // .nullish() (not just .optional()) so the sample yml can leave
+    // `git:` uncommented as a category marker — YAML produces
+    // `git: null` for an empty mapping, which zod's plain
+    // `.optional()` would reject.
+    git: z2.object({
+      user: GitUserSchema.optional()
+    }).nullish(),
+    // .nullish() for the same reason as `git` — the sample keeps
+    // `features:` uncommented as a category marker.
+    features: z2.record(
+      z2.string().regex(
+        REGEX.featureRef,
+        "Invalid feature ref. Expected an OCI-image-style ref like 'ghcr.io/getmonoceros/monoceros-features/<name>:<tag>'."
+      ),
+      z2.record(z2.string(), FeatureOptionValueSchema)
+    ).nullish()
+  }).nullish(),
+  // Machine-global routing settings — one Traefik per builder, so
+  // host-port and similar live here rather than in any container yml.
+  // See ADR 0007.
+  routing: z2.object({
+    hostPort: z2.number().int().min(1).max(65535).optional().describe(
+      "Host port the Traefik singleton binds. Default 80. Set this when 80 is held by another service on your machine \u2014 URLs then become http://<name>.localhost:<port>/."
+    )
+  }).nullish()
+});
+async function readMonocerosConfig(opts = {}) {
+  const home = opts.monocerosHome ?? monocerosHome();
+  const filePath = monocerosConfigPath(home);
+  let text;
+  try {
+    text = await fs3.readFile(filePath, "utf8");
+  } catch {
+    return void 0;
+  }
+  const doc = parseDocument2(text, { prettyErrors: true });
+  if (doc.errors.length > 0) {
+    throw new Error(
+      `yaml parse error in ${filePath}: ${doc.errors[0].message}`
+    );
+  }
+  const result = MonocerosConfigSchema.safeParse(doc.toJS());
+  if (!result.success) {
+    const issues = result.error.issues.map((issue) => {
+      const where = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+      return `  - ${where}: ${issue.message}`;
+    }).join("\n");
+    throw new Error(
+      `Invalid ${filePath}:
+${issues}
+
+See ${filePath.replace(
+        /\.yml$/,
+        ".sample.yml"
+      )} for a valid example.`
+    );
+  }
+  return result.data;
+}
+var DEFAULT_PROXY_HOST_PORT = 80;
+function proxyHostPort(config) {
+  return config?.routing?.hostPort ?? DEFAULT_PROXY_HOST_PORT;
+}
+async function writeGlobalDefaultGitUser(user, opts = {}) {
+  const home = opts.monocerosHome ?? monocerosHome();
+  const filePath = monocerosConfigPath(home);
+  let text;
+  try {
+    text = await fs3.readFile(filePath, "utf8");
+  } catch {
+    text = void 0;
+  }
+  if (text === void 0) {
+    const fresh = [
+      "# Optional \u2014 global defaults for monoceros containers.",
+      "",
+      "schemaVersion: 1",
+      "",
+      "defaults:",
+      "  git:",
+      "    user:",
+      `      name: ${user.name}`,
+      `      email: ${user.email}`,
+      ""
+    ].join("\n");
+    await fs3.mkdir(home, { recursive: true });
+    await fs3.writeFile(filePath, fresh, "utf8");
+    return { filePath, created: true, alreadySet: false };
+  }
+  const doc = parseDocument2(text, { prettyErrors: true });
+  if (doc.errors.length > 0) {
+    throw new Error(
+      `yaml parse error in ${filePath}: ${doc.errors[0].message}`
+    );
+  }
+  const defaultsMap = ensureMap(doc, "defaults");
+  const gitMap = ensureSubMapAtTop(defaultsMap, "git");
+  const userMap = ensureSubMap(gitMap, "user");
+  const existingName = userMap.get("name");
+  const existingEmail = userMap.get("email");
+  if (typeof existingName === "string" && existingName.length > 0 && typeof existingEmail === "string" && existingEmail.length > 0) {
+    return { filePath, created: false, alreadySet: true };
+  }
+  relocateLeakedLeafComments(userMap, defaultsMap, "git");
+  userMap.set("name", user.name);
+  userMap.set("email", user.email);
+  const newText = String(doc);
+  await fs3.writeFile(filePath, newText, "utf8");
+  return { filePath, created: false, alreadySet: false };
+}
+function ensureMap(doc, key) {
+  const node = doc.get(key, true);
+  if (node && isMap(node)) return node;
+  const m = new YAMLMap();
+  doc.set(key, m);
+  return m;
+}
+function ensureSubMap(parent, key) {
+  const node = parent.get(key, true);
+  if (node && isMap(node)) return node;
+  const m = new YAMLMap();
+  parent.set(key, m);
+  return m;
+}
+function ensureSubMapAtTop(parent, key) {
+  const node = parent.get(key, true);
+  if (node && isMap(node)) return node;
+  const parentMaybe = parent;
+  const newKey = new Scalar(key);
+  if (parent.items.length > 0 && typeof parentMaybe.commentBefore === "string" && parentMaybe.commentBefore.length > 0) {
+    const cleaned = stripCommentedKeySkeleton(parentMaybe.commentBefore, key);
+    const blankMatch = cleaned.match(/\n[ \t]*\n/);
+    let head;
+    let tail;
+    if (blankMatch && blankMatch.index !== void 0) {
+      head = cleaned.slice(0, blankMatch.index);
+      tail = cleaned.slice(blankMatch.index + blankMatch[0].length);
+    } else {
+      head = cleaned;
+      tail = "";
+    }
+    if (head.length > 0) {
+      newKey.commentBefore = head;
+      if (parentMaybe.spaceBefore) newKey.spaceBefore = true;
+    }
+    if (tail.length > 0) {
+      const firstKey = parent.items[0].key;
+      if (firstKey && typeof firstKey === "object") {
+        const existing = firstKey.commentBefore ?? "";
+        firstKey.commentBefore = existing ? `${tail}
+${existing}` : tail;
+        firstKey.spaceBefore = true;
+      }
+    }
+    parentMaybe.commentBefore = null;
+    parentMaybe.spaceBefore = false;
+  }
+  const m = new YAMLMap();
+  const pair = new Pair(newKey, m);
+  parent.items.unshift(pair);
+  return m;
+}
+function stripCommentedKeySkeleton(commentBody, key) {
+  const lines = commentBody.split("\n");
+  const headRe = new RegExp(`^ ${escapeRegExp(key)}:\\s*$`);
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (headRe.test(line)) {
+      i++;
+      while (i < lines.length && /^ {2,}\S/.test(lines[i])) {
+        i++;
+      }
+      continue;
+    }
+    out.push(line);
+    i++;
+  }
+  return out.join("\n");
+}
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function relocateLeakedLeafComments(leafMap, parent, ancestorKey) {
+  const items = parent.items;
+  const ancestorIdx = items.findIndex((p) => {
+    const k = p.key;
+    const v = typeof k === "string" ? k : k?.value ?? null;
+    return v === ancestorKey;
+  });
+  if (ancestorIdx < 0 || ancestorIdx + 1 >= items.length) return;
+  const target = items[ancestorIdx + 1];
+  for (const pair of leafMap.items) {
+    const value = pair.value;
+    if (!value || typeof value !== "object") continue;
+    const leakedComment = value.comment;
+    const leakedSpace = value.spaceBefore;
+    if (!leakedComment && !leakedSpace) continue;
+    if (leakedComment) {
+      const targetKey = target.key;
+      if (targetKey && typeof targetKey === "object") {
+        const existing = targetKey.commentBefore ?? "";
+        targetKey.commentBefore = existing ? `${leakedComment}
+${existing}` : leakedComment;
+        if (leakedSpace) targetKey.spaceBefore = true;
+      }
+      value.comment = null;
+    }
+    if (leakedSpace) value.spaceBefore = false;
+  }
+}
+
+// src/proxy/index.ts
+import { spawn as spawn3 } from "child_process";
+import { promises as fs4 } from "fs";
+import path3 from "path";
+var PROXY_CONTAINER_NAME = "monoceros-proxy";
+var PROXY_NETWORK_NAME = "monoceros-proxy";
+var TRAEFIK_IMAGE = "traefik:v3.3";
+var defaultDockerExec = (args) => {
+  return new Promise((resolve, reject) => {
+    const child = spawn3("docker", args, {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", reject);
+    child.on(
+      "exit",
+      (code) => resolve({ stdout, stderr, exitCode: code ?? 0 })
+    );
+  });
+};
+var realDocker = defaultDockerExec;
+function proxyDynamicDir(home) {
+  return path3.join(home ?? monocerosHome(), "traefik", "dynamic");
+}
+async function ensureProxy(opts = {}) {
+  const docker = opts.docker ?? realDocker;
+  const dyn = proxyDynamicDir(opts.monocerosHome);
+  await fs4.mkdir(dyn, { recursive: true });
+  const netInspect = await docker(["network", "inspect", PROXY_NETWORK_NAME]);
+  if (netInspect.exitCode !== 0) {
+    const create = await docker(["network", "create", PROXY_NETWORK_NAME]);
+    if (create.exitCode !== 0) {
+      throw new Error(
+        `Could not create docker network ${PROXY_NETWORK_NAME}: ${create.stderr.trim() || `exit ${create.exitCode}`}`
+      );
+    }
+  }
+  const state = await docker([
+    "inspect",
+    "--format",
+    "{{.State.Running}}",
+    PROXY_CONTAINER_NAME
+  ]);
+  if (state.exitCode === 0) {
+    if (state.stdout.trim() === "true") return;
+    const start = await docker(["start", PROXY_CONTAINER_NAME]);
+    if (start.exitCode !== 0) {
+      throw new Error(
+        `Could not start existing ${PROXY_CONTAINER_NAME} container: ${start.stderr.trim() || `exit ${start.exitCode}`}`
+      );
+    }
+    return;
+  }
+  const hostPort = opts.hostPort ?? 80;
+  const run = await docker([
+    "run",
+    "-d",
+    "--name",
+    PROXY_CONTAINER_NAME,
+    "--network",
+    PROXY_NETWORK_NAME,
+    "-p",
+    `${hostPort}:80`,
+    "-v",
+    `${dyn}:/etc/traefik/dynamic:ro`,
+    "--label",
+    "monoceros.role=proxy",
+    TRAEFIK_IMAGE,
+    "--entrypoints.web.address=:80",
+    "--providers.file.directory=/etc/traefik/dynamic",
+    "--providers.file.watch=true",
+    "--providers.docker=false",
+    "--api.dashboard=false",
+    "--log.level=INFO"
+  ]);
+  if (run.exitCode !== 0) {
+    throw new Error(
+      `Could not start ${PROXY_CONTAINER_NAME}: ${run.stderr.trim() || `exit ${run.exitCode}`}`
+    );
+  }
+  opts.logger?.info(
+    `Started ${PROXY_CONTAINER_NAME} (Traefik on :${hostPort}).`
+  );
+}
+async function maybeStopProxy(opts = {}) {
+  const docker = opts.docker ?? realDocker;
+  const logger = opts.logger;
+  const inspect = await docker([
+    "network",
+    "inspect",
+    PROXY_NETWORK_NAME,
+    "--format",
+    "{{range $k, $v := .Containers}}{{$v.Name}}\n{{end}}"
+  ]);
+  if (inspect.exitCode !== 0) {
+    return;
+  }
+  const others = inspect.stdout.split("\n").map((n) => n.trim()).filter((n) => n.length > 0 && n !== PROXY_CONTAINER_NAME);
+  if (others.length > 0) return;
+  await docker(["rm", "-f", PROXY_CONTAINER_NAME]);
+  const netRm = await docker(["network", "rm", PROXY_NETWORK_NAME]);
+  if (netRm.exitCode !== 0) {
+    logger?.warn?.(
+      `Could not remove docker network ${PROXY_NETWORK_NAME}: ${netRm.stderr.trim() || `exit ${netRm.exitCode}`}`
+    );
+    return;
+  }
+  logger?.info(
+    `Stopped ${PROXY_CONTAINER_NAME} (no dev-containers with ports left).`
+  );
+}
+
+// src/proxy/dynamic.ts
+import { promises as fs5 } from "fs";
+import path4 from "path";
+async function writeDynamicConfig(name, ports, opts = {}) {
+  if (ports.length === 0) {
+    throw new Error(
+      `writeDynamicConfig requires at least one port. For empty port lists, call removeDynamicConfig(${JSON.stringify(name)}).`
+    );
+  }
+  const dir = proxyDynamicDir(opts.monocerosHome);
+  await fs5.mkdir(dir, { recursive: true });
+  const file = path4.join(dir, `${name}.yml`);
+  await fs5.writeFile(file, renderDynamicConfig(name, ports), "utf8");
+  return file;
+}
+async function removeDynamicConfig(name, opts = {}) {
+  const file = path4.join(proxyDynamicDir(opts.monocerosHome), `${name}.yml`);
+  await fs5.rm(file, { force: true });
+}
+function renderDynamicConfig(name, ports) {
   const lines = [];
   lines.push("# Generated by Monoceros \u2014 do not edit by hand.");
   lines.push(`# Container: ${name}`);
@@ -981,8 +1498,8 @@ function knownServices() {
 }
 
 // src/create/scaffold.ts
-import { existsSync as existsSync2, readFileSync, promises as fs5 } from "fs";
-import path4 from "path";
+import { existsSync as existsSync2, readFileSync, promises as fs6 } from "fs";
+import path5 from "path";
 
 // src/util/ref.ts
 var FEATURE_NAME_CHARSET = "[a-z0-9._-]+";
@@ -1153,7 +1670,7 @@ function resolveFeatures(opts) {
       if (match) {
         const name = match.name;
         const checkout = workbenchCheckoutRoot();
-        const localSourceDir = checkout ? path4.join(checkout, "images", "features", name) : null;
+        const localSourceDir = checkout ? path5.join(checkout, "images", "features", name) : null;
         if (localSourceDir && existsSync2(localSourceDir)) {
           const { paths, files } = readPersistentHomeEntries(localSourceDir);
           resolved.push({
@@ -1178,7 +1695,7 @@ function resolveFeatures(opts) {
   return resolved;
 }
 function readPersistentHomeEntries(localSourceDir) {
-  const manifestPath = path4.join(localSourceDir, "devcontainer-feature.json");
+  const manifestPath = path5.join(localSourceDir, "devcontainer-feature.json");
   try {
     const text = readFileSync(manifestPath, "utf8");
     const parsed = JSON.parse(text);
@@ -1266,7 +1783,10 @@ function buildDevcontainerJson(opts, dockerMode = "rootful") {
   }
   const mounts = [...homeMounts];
   const mountsField = mounts.length > 0 ? { mounts } : {};
-  const workspaceMountField = {};
+  const workspaceMountField = {
+    workspaceMount: `source=\${localWorkspaceFolder},target=/workspaces/${opts.name},type=bind,consistency=cached`,
+    workspaceFolder: `/workspaces/${opts.name}`
+  };
   const runArgs = ["--cap-add=NET_ADMIN"];
   if (ports.length > 0) {
     runArgs.push("--network=monoceros-proxy");
@@ -1347,6 +1867,23 @@ function buildCodeWorkspaceJson(opts) {
   }
   return { folders };
 }
+function mergeCodeWorkspace(existing, generated) {
+  if (!existing || typeof existing !== "object" || Array.isArray(existing) || !Array.isArray(existing.folders)) {
+    return { ...generated };
+  }
+  const existingObj = existing;
+  const existingFolders = existingObj.folders;
+  const existingPaths = new Set(
+    existingFolders.map((f) => f && typeof f === "object" ? f.path : void 0).filter((p) => typeof p === "string")
+  );
+  const merged = [...existingFolders];
+  for (const g of generated.folders) {
+    if (!existingPaths.has(g.path)) merged.push(g);
+  }
+  const out = { ...existingObj };
+  out.folders = merged;
+  return out;
+}
 function buildPostCreateScript(opts) {
   const lines = [
     "#!/usr/bin/env bash",
@@ -1443,83 +1980,98 @@ function buildPostCreateScript(opts) {
   return lines.join("\n") + "\n";
 }
 async function writePostCreateScript(devcontainerDir, opts) {
-  const dest = path4.join(devcontainerDir, "post-create.sh");
-  await fs5.writeFile(dest, buildPostCreateScript(opts));
-  await fs5.chmod(dest, 493);
+  const dest = path5.join(devcontainerDir, "post-create.sh");
+  await fs6.writeFile(dest, buildPostCreateScript(opts));
+  await fs6.chmod(dest, 493);
 }
 async function writeScaffold(opts, targetDir, scaffoldOpts = {}) {
   const dockerMode = scaffoldOpts.dockerMode ?? "rootful";
-  const devcontainerDir = path4.join(targetDir, ".devcontainer");
-  const monocerosDir = path4.join(targetDir, ".monoceros");
-  const projectsDir = path4.join(targetDir, "projects");
-  const homeDir = path4.join(targetDir, "home");
-  const dataDir = path4.join(targetDir, "data");
-  await fs5.mkdir(devcontainerDir, { recursive: true });
-  await fs5.mkdir(monocerosDir, { recursive: true });
-  await fs5.mkdir(projectsDir, { recursive: true });
-  await fs5.mkdir(homeDir, { recursive: true });
+  const devcontainerDir = path5.join(targetDir, ".devcontainer");
+  const monocerosDir = path5.join(targetDir, ".monoceros");
+  const projectsDir = path5.join(targetDir, "projects");
+  const homeDir = path5.join(targetDir, "home");
+  const dataDir = path5.join(targetDir, "data");
+  await fs6.mkdir(devcontainerDir, { recursive: true });
+  await fs6.mkdir(monocerosDir, { recursive: true });
+  await fs6.mkdir(projectsDir, { recursive: true });
+  await fs6.mkdir(homeDir, { recursive: true });
   if (needsCompose(opts)) {
-    await fs5.mkdir(dataDir, { recursive: true });
+    await fs6.mkdir(dataDir, { recursive: true });
     for (const svcId of opts.services) {
       const def = SERVICE_CATALOG[svcId];
       if (def?.dataMount) {
-        await fs5.mkdir(path4.join(dataDir, def.id), { recursive: true });
+        await fs6.mkdir(path5.join(dataDir, def.id), { recursive: true });
       }
     }
   }
-  const containerGitignore = path4.join(targetDir, ".gitignore");
-  await fs5.writeFile(containerGitignore, "/home/\n/.monoceros/\n/data/\n");
-  const gitkeep = path4.join(projectsDir, ".gitkeep");
+  const containerGitignore = path5.join(targetDir, ".gitignore");
+  await fs6.writeFile(containerGitignore, "/home/\n/.monoceros/\n/data/\n");
+  const gitkeep = path5.join(projectsDir, ".gitkeep");
   if (!existsSync2(gitkeep)) {
-    await fs5.writeFile(gitkeep, "");
+    await fs6.writeFile(gitkeep, "");
   }
-  await fs5.writeFile(
-    path4.join(monocerosDir, ".gitignore"),
+  await fs6.writeFile(
+    path5.join(monocerosDir, ".gitignore"),
     "git-credentials*\ngitconfig\n"
   );
   const devcontainerJson = buildDevcontainerJson(opts, dockerMode);
-  await fs5.writeFile(
-    path4.join(devcontainerDir, "devcontainer.json"),
+  await fs6.writeFile(
+    path5.join(devcontainerDir, "devcontainer.json"),
     JSON.stringify(devcontainerJson, null, 2) + "\n"
   );
-  const featuresDir = path4.join(devcontainerDir, "features");
+  const featuresDir = path5.join(devcontainerDir, "features");
   if (existsSync2(featuresDir)) {
-    await fs5.rm(featuresDir, { recursive: true, force: true });
+    await fs6.rm(featuresDir, { recursive: true, force: true });
   }
   const resolvedFeatures = resolveFeatures(opts);
   for (const f of resolvedFeatures) {
     if (!f.localSourceDir || !f.localName) continue;
-    const dest = path4.join(featuresDir, f.localName);
-    await fs5.mkdir(dest, { recursive: true });
-    await fs5.cp(f.localSourceDir, dest, { recursive: true });
+    const dest = path5.join(featuresDir, f.localName);
+    await fs6.mkdir(dest, { recursive: true });
+    await fs6.cp(f.localSourceDir, dest, { recursive: true });
   }
   for (const f of resolvedFeatures) {
     for (const sub of f.persistentHomePaths) {
-      await fs5.mkdir(path4.join(homeDir, sub), { recursive: true });
+      await fs6.mkdir(path5.join(homeDir, sub), { recursive: true });
     }
     for (const entry2 of f.persistentHomeFiles) {
-      const filePath = path4.join(homeDir, entry2.path);
-      await fs5.mkdir(path4.dirname(filePath), { recursive: true });
+      const filePath = path5.join(homeDir, entry2.path);
+      await fs6.mkdir(path5.dirname(filePath), { recursive: true });
       if (!existsSync2(filePath)) {
-        await fs5.writeFile(filePath, entry2.initialContent);
+        await fs6.writeFile(filePath, entry2.initialContent);
       }
     }
   }
   await writePostCreateScript(devcontainerDir, opts);
-  const composePath = path4.join(devcontainerDir, "compose.yaml");
+  const composePath = path5.join(devcontainerDir, "compose.yaml");
   if (needsCompose(opts)) {
-    await fs5.writeFile(composePath, buildComposeYaml(opts, dockerMode));
+    await fs6.writeFile(composePath, buildComposeYaml(opts, dockerMode));
   } else if (existsSync2(composePath)) {
-    await fs5.rm(composePath);
+    await fs6.rm(composePath);
   }
-  await fs5.writeFile(
-    path4.join(targetDir, `${opts.name}.code-workspace`),
-    JSON.stringify(buildCodeWorkspaceJson(opts), null, 2) + "\n"
-  );
+  const workspacePath = path5.join(targetDir, `${opts.name}.code-workspace`);
+  let existingWorkspace;
+  try {
+    const raw = await fs6.readFile(workspacePath, "utf8");
+    existingWorkspace = JSON.parse(raw);
+  } catch {
+    existingWorkspace = void 0;
+  }
+  const generated = buildCodeWorkspaceJson(opts);
+  const merged = mergeCodeWorkspace(existingWorkspace, generated);
+  await fs6.writeFile(workspacePath, JSON.stringify(merged, null, 2) + "\n");
 }
 
 // src/modify/yml.ts
-import { isMap, isScalar, isSeq, YAMLMap, YAMLSeq } from "yaml";
+import {
+  isMap as isMap2,
+  isScalar,
+  isSeq,
+  Pair as Pair2,
+  Scalar as Scalar2,
+  YAMLMap as YAMLMap2,
+  YAMLSeq
+} from "yaml";
 function ensureSeq(doc, key) {
   const existing = doc.get(key, true);
   if (existing && isSeq(existing)) return existing;
@@ -1558,12 +2110,108 @@ function addAptPackagesToDoc(doc, packages) {
   }
   return changed;
 }
+function setContainerGitUserInDoc(doc, user) {
+  const gitNode = doc.get("git", true);
+  let gitMap;
+  let createdNew = false;
+  if (gitNode && isMap2(gitNode)) {
+    gitMap = gitNode;
+  } else {
+    gitMap = new YAMLMap2();
+    insertTopLevelAfterName(doc, "git", gitMap, GIT_USER_HEADER_COMMENT);
+    createdNew = true;
+  }
+  const userNode = gitMap.get("user", true);
+  let userMap;
+  if (userNode && isMap2(userNode)) {
+    userMap = userNode;
+  } else {
+    userMap = new YAMLMap2();
+    gitMap.set("user", userMap);
+  }
+  const currentName = userMap.get("name");
+  const currentEmail = userMap.get("email");
+  if (!createdNew && currentName === user.name && currentEmail === user.email) {
+    return false;
+  }
+  userMap.set("name", user.name);
+  userMap.set("email", user.email);
+  relocateLeakedSectionComments(doc);
+  return true;
+}
+function relocateLeakedSectionComments(doc) {
+  const root = doc.contents;
+  if (!root || !isMap2(root)) return;
+  const items = root.items;
+  for (let i = 0; i < items.length - 1; i++) {
+    const here = items[i];
+    const next = items[i + 1];
+    const leak = takeTrailingLeafComment(here.value);
+    if (!leak) continue;
+    const nextKey = next.key;
+    if (!nextKey || typeof nextKey !== "object") continue;
+    const existing = nextKey.commentBefore ?? "";
+    nextKey.commentBefore = existing ? `${leak}
+${existing}` : leak;
+    nextKey.spaceBefore = true;
+  }
+}
+function takeTrailingLeafComment(node) {
+  if (!node) return null;
+  const c = node;
+  if (typeof c.comment === "string" && c.comment.length > 0) {
+    const blankMatch = c.comment.match(/\n[ \t]*\n/);
+    if (blankMatch && blankMatch.index !== void 0) {
+      const tail = c.comment.slice(blankMatch.index + blankMatch[0].length);
+      c.comment = c.comment.slice(0, blankMatch.index);
+      if (tail.length > 0) return tail;
+    }
+  }
+  if (isMap2(node) && node.items.length > 0) {
+    for (let i = node.items.length - 1; i >= 0; i--) {
+      const value = node.items[i].value;
+      const found = takeTrailingLeafComment(value);
+      if (found) return found;
+    }
+  }
+  if (isSeq(node) && node.items.length > 0) {
+    for (let i = node.items.length - 1; i >= 0; i--) {
+      const found = takeTrailingLeafComment(node.items[i]);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+function insertTopLevelAfterName(doc, key, value, comment) {
+  const root = doc.contents;
+  if (!root || !isMap2(root)) {
+    doc.set(key, value);
+    return;
+  }
+  const keyScalar = new Scalar2(key);
+  if (comment) {
+    keyScalar.commentBefore = comment;
+    keyScalar.spaceBefore = true;
+  }
+  const pair = new Pair2(keyScalar, value);
+  const nameIdx = root.items.findIndex((p) => {
+    const k = p.key;
+    return (typeof k === "string" ? k : k?.value ?? null) === "name";
+  });
+  const insertAt = nameIdx >= 0 ? nameIdx + 1 : Math.min(1, root.items.length);
+  root.items.splice(insertAt, 0, pair);
+}
+var GIT_USER_HEADER_COMMENT = [
+  " Git committer identity for this container. Overrides",
+  " monoceros-config.yml's defaults.git.user. Applies to every repo",
+  " below unless that repo declares its own `git.user` override."
+].join("\n");
 function portOfItem(item) {
   const scalar = scalarValue(item);
   if (typeof scalar === "number" && Number.isInteger(scalar)) {
     return scalar;
   }
-  if (isMap(item)) {
+  if (isMap2(item)) {
     const p = item.get("port");
     if (typeof p === "number" && Number.isInteger(p)) return p;
   }
@@ -1571,8 +2219,8 @@ function portOfItem(item) {
 }
 function ensureRoutingMap(doc) {
   const existing = doc.get("routing", true);
-  if (existing && isMap(existing)) return existing;
-  const map = new YAMLMap();
+  if (existing && isMap2(existing)) return existing;
+  const map = new YAMLMap2();
   doc.set("routing", map);
   return map;
 }
@@ -1616,7 +2264,7 @@ function addPortsToDoc(doc, ports) {
 }
 function removePortsFromDoc(doc, ports) {
   const routing = doc.get("routing", true);
-  if (!routing || !isMap(routing)) return false;
+  if (!routing || !isMap2(routing)) return false;
   const seq = routing.get("ports", true);
   if (!seq || !isSeq(seq)) return false;
   const targets = new Set(ports);
@@ -1643,7 +2291,7 @@ function addInstallUrlToDoc(doc, url) {
 function addFeatureToDoc(doc, ref, options = {}) {
   const seq = ensureSeq(doc, "features");
   for (const item of seq.items) {
-    if (!isMap(item)) continue;
+    if (!isMap2(item)) continue;
     const itemRef = item.get("ref");
     if (itemRef !== ref) continue;
     const itemJs = item.toJS(doc);
@@ -1655,7 +2303,7 @@ function addFeatureToDoc(doc, ref, options = {}) {
       `Feature ${ref} is already configured with different options. Remove it first (\`monoceros remove-feature ${ref}\`) before re-adding.`
     );
   }
-  const entry2 = new YAMLMap();
+  const entry2 = new YAMLMap2();
   entry2.set("ref", ref);
   if (Object.keys(options).length > 0) {
     entry2.set("options", options);
@@ -1666,16 +2314,16 @@ function addFeatureToDoc(doc, ref, options = {}) {
 function addRepoToDoc(doc, repo) {
   const seq = ensureSeq(doc, "repos");
   for (const item of seq.items) {
-    if (!isMap(item)) continue;
+    if (!isMap2(item)) continue;
     const url = item.get("url");
     if (url !== repo.url) continue;
     const existingPath = item.get("path");
     const effectivePath = typeof existingPath === "string" ? existingPath : deriveRepoName(url);
     if (effectivePath !== repo.path) continue;
     const existingGit = item.get("git", true);
-    const existingUser = existingGit && isMap(existingGit) ? existingGit.get("user", true) : null;
-    const existingName = existingUser && isMap(existingUser) ? existingUser.get("name") : null;
-    const existingEmail = existingUser && isMap(existingUser) ? existingUser.get("email") : null;
+    const existingUser = existingGit && isMap2(existingGit) ? existingGit.get("user", true) : null;
+    const existingName = existingUser && isMap2(existingUser) ? existingUser.get("name") : null;
+    const existingEmail = existingUser && isMap2(existingUser) ? existingUser.get("email") : null;
     const existingGitUser = typeof existingName === "string" && typeof existingEmail === "string" ? { name: existingName, email: existingEmail } : void 0;
     const sameGitUser = (existingGitUser?.name ?? null) === (repo.gitUser?.name ?? null) && (existingGitUser?.email ?? null) === (repo.gitUser?.email ?? null);
     const existingProvider = item.get("provider");
@@ -1684,8 +2332,8 @@ function addRepoToDoc(doc, repo) {
       return false;
     }
     if (repo.gitUser) {
-      const gitMap = new YAMLMap();
-      const userMap = new YAMLMap();
+      const gitMap = new YAMLMap2();
+      const userMap = new YAMLMap2();
       userMap.set("name", repo.gitUser.name);
       userMap.set("email", repo.gitUser.email);
       gitMap.set("user", userMap);
@@ -1698,16 +2346,18 @@ function addRepoToDoc(doc, repo) {
     } else {
       item.delete("provider");
     }
+    relocateLeakedSectionComments(doc);
     return true;
   }
-  const entry2 = new YAMLMap();
+  const entry2 = new YAMLMap2();
   entry2.set("url", repo.url);
-  if (repo.path !== deriveRepoName(repo.url)) {
+  const persistPath = repo.path !== deriveRepoName(repo.url);
+  if (persistPath) {
     entry2.set("path", repo.path);
   }
   if (repo.gitUser) {
-    const gitMap = new YAMLMap();
-    const userMap = new YAMLMap();
+    const gitMap = new YAMLMap2();
+    const userMap = new YAMLMap2();
     userMap.set("name", repo.gitUser.name);
     userMap.set("email", repo.gitUser.email);
     gitMap.set("user", userMap);
@@ -1716,7 +2366,20 @@ function addRepoToDoc(doc, repo) {
   if (repo.provider) {
     entry2.set("provider", repo.provider);
   }
+  const hintLines = [];
+  if (!persistPath) hintLines.push(" path:");
+  if (!repo.provider) hintLines.push(" provider:");
+  if (!repo.gitUser) {
+    hintLines.push(" git:");
+    hintLines.push("   user:");
+    hintLines.push("     name:");
+    hintLines.push("     email:");
+  }
+  if (hintLines.length > 0) {
+    entry2.comment = hintLines.join("\n");
+  }
   seq.add(entry2);
+  relocateLeakedSectionComments(doc);
   return true;
 }
 function removeLanguageFromDoc(doc, lang) {
@@ -1741,7 +2404,7 @@ function removeInstallUrlFromDoc(doc, url) {
 function removeFeatureFromDoc(doc, ref) {
   const seq = doc.get("features", true);
   if (!seq || !isSeq(seq)) return false;
-  const idx = seq.items.findIndex((i) => isMap(i) && i.get("ref") === ref);
+  const idx = seq.items.findIndex((i) => isMap2(i) && i.get("ref") === ref);
   if (idx < 0) return false;
   seq.items.splice(idx, 1);
   pruneEmptySeq(doc, "features");
@@ -1751,11 +2414,11 @@ function removeRepoFromDoc(doc, urlOrPath) {
   const seq = doc.get("repos", true);
   if (!seq || !isSeq(seq)) return false;
   const idx = seq.items.findIndex((item) => {
-    if (!isMap(item)) return false;
+    if (!isMap2(item)) return false;
     const url = item.get("url");
     if (url === urlOrPath) return true;
-    const path15 = item.get("path");
-    const effectivePath = typeof path15 === "string" ? path15 : typeof url === "string" ? deriveRepoName(url) : void 0;
+    const path16 = item.get("path");
+    const effectivePath = typeof path16 === "string" ? path16 : typeof url === "string" ? deriveRepoName(url) : void 0;
     return effectivePath === urlOrPath;
   });
   if (idx < 0) return false;
@@ -1805,7 +2468,7 @@ async function runAddRepo(input) {
       "Missing repo URL. Usage: monoceros add-repo <containername> <url>."
     );
   }
-  const path15 = (input.path ?? deriveRepoName(url)).trim();
+  const path16 = (input.path ?? deriveRepoName(url)).trim();
   const hasName = typeof input.gitName === "string" && input.gitName.trim().length > 0;
   const hasEmail = typeof input.gitEmail === "string" && input.gitEmail.trim().length > 0;
   if (hasName !== hasEmail) {
@@ -1834,7 +2497,7 @@ async function runAddRepo(input) {
   const providerToWrite = !canonical && explicitProvider ? explicitProvider : void 0;
   const entry2 = {
     url,
-    path: path15,
+    path: path16,
     ...hasName && hasEmail ? {
       gitUser: {
         name: input.gitName.trim(),
@@ -1843,7 +2506,117 @@ async function runAddRepo(input) {
     } : {},
     ...providerToWrite ? { provider: providerToWrite } : {}
   };
-  return mutate(input, (doc) => addRepoToDoc(doc, entry2));
+  const result = await mutate(input, (doc) => addRepoToDoc(doc, entry2));
+  if (result.status === "updated") {
+    await tryCloneInRunningContainer(input, entry2);
+  }
+  return result;
+}
+async function tryCloneInRunningContainer(input, entry2) {
+  const home = input.monocerosHome ?? monocerosHome();
+  const root = containerDir(input.name, home);
+  const logger = input.logger ?? defaultLogger();
+  let containerId;
+  try {
+    containerId = await findRunningContainerByLocalFolder(root, {
+      ...input.containerLookupDocker ? { docker: input.containerLookupDocker } : {}
+    });
+  } catch (err) {
+    logger.warn(
+      `Could not check whether the container is running: ${err instanceof Error ? err.message : String(err)}. The yml is updated \u2014 run \`monoceros apply ${input.name}\` to clone.`
+    );
+    return;
+  }
+  if (!containerId) {
+    logger.info(
+      `Container not running \u2014 yml updated only. Clone happens on \`monoceros apply ${input.name}\`.`
+    );
+    return;
+  }
+  let urlHost;
+  try {
+    urlHost = new URL(entry2.url).hostname;
+  } catch {
+    logger.warn(
+      `Cannot parse URL host from ${entry2.url}. The yml is updated \u2014 clone manually inside the container or rerun with a fixed URL.`
+    );
+    return;
+  }
+  const provider = resolveProvider(urlHost, entry2.provider);
+  if (provider === "unknown") {
+    logger.warn(
+      `Could not resolve provider for host ${urlHost}. The yml is updated; clone happens at the next \`monoceros apply\` if you set the provider.`
+    );
+    return;
+  }
+  try {
+    const credsResult = await collectGitCredentials(
+      root,
+      [{ host: urlHost, provider }],
+      {
+        ...input.credentialsSpawn ? { spawn: input.credentialsSpawn } : {},
+        logger: { info: () => {
+        }, warn: (m) => logger.warn(m) }
+      }
+    );
+    const status = credsResult.perHost.find((h) => h.host === urlHost);
+    if (!status || status.status !== "ok") {
+      const detail = status?.detail ? `: ${status.detail}` : "";
+      logger.warn(
+        `No HTTPS credentials available for ${urlHost}${detail}. The yml is updated; set up credentials (e.g. \`gh auth login\`) and re-run \`monoceros apply ${input.name}\` or rerun this add-repo.`
+      );
+      return;
+    }
+  } catch (err) {
+    logger.warn(
+      `Credential fetch for ${urlHost} failed: ${err instanceof Error ? err.message : String(err)}. The yml is updated.`
+    );
+    return;
+  }
+  const containerName = input.name;
+  const targetRel = `projects/${entry2.path}`;
+  const parentRel = entry2.path.includes("/") ? `projects/${entry2.path.split("/").slice(0, -1).join("/")}` : "projects";
+  const credentialsFile = `/workspaces/${containerName}/.monoceros/git-credentials`;
+  const credentialHelper = `store --file=${credentialsFile}`;
+  const script = [
+    `set -eu`,
+    `cd /workspaces/${containerName}`,
+    `if [ -d ${shquote(targetRel)} ]; then`,
+    `  echo "[add-repo] ${targetRel} already exists \u2014 skipping clone."`,
+    `  exit 0`,
+    `fi`,
+    `mkdir -p ${shquote(parentRel)}`,
+    `git -c ${shquote(`credential.helper=${credentialHelper}`)} clone ${shquote(entry2.url)} ${shquote(targetRel)}`
+  ];
+  if (entry2.gitUser) {
+    script.push(
+      `git -C ${shquote(targetRel)} config user.name ${shquote(entry2.gitUser.name)}`,
+      `git -C ${shquote(targetRel)} config user.email ${shquote(entry2.gitUser.email)}`
+    );
+  }
+  const execFn = input.containerExec ?? realContainerExec;
+  let exit;
+  try {
+    exit = await execFn(containerId, ["bash", "-c", script.join("\n")]);
+  } catch (err) {
+    logger.warn(
+      `In-container clone for ${entry2.url} failed: ${err instanceof Error ? err.message : String(err)}. The yml is updated; \`monoceros apply ${input.name}\` retries.`
+    );
+    return;
+  }
+  if (exit.exitCode !== 0) {
+    logger.warn(
+      `In-container clone for ${entry2.url} exited ${exit.exitCode}. The yml is updated; \`monoceros apply ${input.name}\` retries.`
+    );
+    return;
+  }
+  logger.info(
+    `Cloned ${entry2.url} into /workspaces/${containerName}/${targetRel} inside the running container.`
+  );
+  void path6;
+}
+function shquote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function normalizeProvider(raw) {
   if (typeof raw !== "string") return void 0;
@@ -1979,7 +2752,7 @@ async function mutate(opts, apply) {
   const logger = opts.logger ?? defaultLogger();
   let oldText;
   try {
-    oldText = await fs6.readFile(ymlPath, "utf8");
+    oldText = await fs7.readFile(ymlPath, "utf8");
   } catch {
     throw new Error(
       `No such config: ${ymlPath}. Run \`monoceros init <template> ${opts.name}\` first.`
@@ -2003,7 +2776,7 @@ async function mutate(opts, apply) {
       return { status: "aborted" };
     }
   }
-  await fs6.writeFile(ymlPath, newText, "utf8");
+  await fs7.writeFile(ymlPath, newText, "utf8");
   logger.success(`Updated ${ymlPath}.`);
   logger.info(
     `Run \`monoceros apply ${opts.name}\` to rebuild the dev-container and pick up the change.`
@@ -2261,179 +3034,21 @@ function printSecurityWarning(url) {
   w(
     "    2. Verify the maintainer is who you think they are (HTTPS cert, repo)."
   );
-  w("    3. Ideally, vendor the install steps as `add-apt-packages` or");
-  w(
-    "       `add-feature` instead \u2014 those reference signed/versioned artifacts."
-  );
-  w("");
-}
-
-// src/commands/add-repo.ts
-import { defineCommand as defineCommand4 } from "citty";
-import { consola as consola5 } from "consola";
-var addRepoCommand = defineCommand4({
-  meta: {
-    name: "add-repo",
-    group: "edit",
-    description: "Add a git repo to the container config. Cloned into projects/<path>/ on container build. Idempotent \u2014 existing project subfolders are left alone. Destination path derived from URL by default; override with --path (supports nested subfolders like apps/web). Branches/PRs are git-level concerns: clone, then `git checkout` inside the container."
-  },
-  args: {
-    name: {
-      type: "positional",
-      description: "Container name (yml in $MONOCEROS_HOME/container-configs/).",
-      required: true
-    },
-    url: {
-      type: "positional",
-      description: "Git URL (HTTPS or SSH/git@ form). E.g. https://github.com/foo/bar.git, git@github.com:foo/bar.git.",
-      required: true
-    },
-    path: {
-      type: "string",
-      description: "Destination under projects/. Subfolders via `/` (e.g. apps/web). Default: URL-derived single segment (bar.git \u2192 bar)."
-    },
-    "git-name": {
-      type: "string",
-      description: "Per-repo git committer name. Overrides the container-level git.user.name for this repo only. Pair with --git-email."
-    },
-    "git-email": {
-      type: "string",
-      description: "Per-repo git committer email. Overrides the container-level git.user.email for this repo only. Pair with --git-name."
-    },
-    provider: {
-      type: "string",
-      description: "Git provider for credential-helper guidance: github | gitlab | bitbucket. Required when the URL host is not github.com, gitlab.com, or bitbucket.org \u2014 Monoceros uses this to suggest the right CLI (gh / glab / Atlassian token) on missing credentials."
-    },
-    yes: {
-      type: "boolean",
-      description: "Skip the interactive confirmation and apply the diff.",
-      alias: ["y"],
-      default: false
-    }
-  },
-  async run({ args }) {
-    try {
-      const result = await runAddRepo({
-        name: args.name,
-        url: args.url,
-        ...typeof args.path === "string" ? { path: args.path } : {},
-        ...typeof args["git-name"] === "string" ? { gitName: args["git-name"] } : {},
-        ...typeof args["git-email"] === "string" ? { gitEmail: args["git-email"] } : {},
-        ...typeof args.provider === "string" ? { provider: args.provider } : {},
-        yes: args.yes
-      });
-      process.exit(result.status === "aborted" ? 1 : 0);
-    } catch (err) {
-      consola5.error(err instanceof Error ? err.message : String(err));
-      process.exit(1);
-    }
-  }
-});
-
-// src/commands/add-language.ts
-import { defineCommand as defineCommand5 } from "citty";
-import { consola as consola6 } from "consola";
-var addLanguageCommand = defineCommand5({
-  meta: {
-    name: "add-language",
-    group: "edit",
-    description: "Add a language toolchain (devcontainer feature) to the container config. Idempotent, prints a diff before writing."
-  },
-  args: {
-    name: {
-      type: "positional",
-      description: "Container name (yml in $MONOCEROS_HOME/container-configs/).",
-      required: true
-    },
-    language: {
-      type: "positional",
-      description: "Language identifier from the feature whitelist (e.g. python, java, rust).",
-      required: true
-    },
-    yes: {
-      type: "boolean",
-      description: "Skip the interactive confirmation and apply the diff.",
-      alias: ["y"],
-      default: false
-    }
-  },
-  async run({ args }) {
-    try {
-      const result = await runAddLanguage({
-        name: args.name,
-        language: args.language,
-        yes: args.yes
-      });
-      process.exit(result.status === "aborted" ? 1 : 0);
-    } catch (err) {
-      consola6.error(err instanceof Error ? err.message : String(err));
-      process.exit(1);
-    }
-  }
-});
-
-// src/commands/add-port.ts
-import { defineCommand as defineCommand6 } from "citty";
-import { consola as consola7 } from "consola";
-var addPortCommand = defineCommand6({
-  meta: {
-    name: "add-port",
-    group: "edit",
-    description: "Add one or more ports to the container config so they become reachable from the host via Traefik (`<container>.localhost` / `<container>-<port>.localhost`). Pass port numbers after `--` (e.g. `monoceros add-port sandbox -- 3000 5173 6006`). Idempotent. Persisted in the yml so later `monoceros apply` runs restore the routes. Pass `--default` together with a single port to make it the bare `<container>.localhost` route \u2014 the port is inserted at position 0 (or moved there if it already exists)."
-  },
-  args: {
-    name: {
-      type: "positional",
-      description: "Container name (yml in $MONOCEROS_HOME/container-configs/).",
-      required: true
-    },
-    yes: {
-      type: "boolean",
-      description: "Skip the interactive confirmation and apply the diff.",
-      alias: ["y"],
-      default: false
-    },
-    default: {
-      type: "boolean",
-      description: "Make the (single) port the new default route at `<container>.localhost`. Inserts the port at position 0 of `routing.ports`, or moves it there if it already exists. Errors when more than one port is passed.",
-      default: false
-    }
-  },
-  async run({ args }) {
-    const tokens = [...getInnerArgs()];
-    if (tokens.length === 0) {
-      consola7.error(
-        "No ports given. Usage: `monoceros add-port <containername> [--yes] [--default] -- <port> [<port> \u2026]`."
-      );
-      process.exit(1);
-    }
-    try {
-      const result = await runAddPort({
-        name: args.name,
-        ports: tokens.map(coerceToken),
-        yes: args.yes,
-        asDefault: args.default
-      });
-      process.exit(result.status === "aborted" ? 1 : 0);
-    } catch (err) {
-      consola7.error(err instanceof Error ? err.message : String(err));
-      process.exit(1);
-    }
-  }
-});
-function coerceToken(raw) {
-  const n = Number(raw);
-  return Number.isFinite(n) ? n : raw;
+  w("    3. Ideally, vendor the install steps as `add-apt-packages` or");
+  w(
+    "       `add-feature` instead \u2014 those reference signed/versioned artifacts."
+  );
+  w("");
 }
 
-// src/commands/add-service.ts
-import { defineCommand as defineCommand7 } from "citty";
-import { consola as consola8 } from "consola";
-var addServiceCommand = defineCommand7({
+// src/commands/add-repo.ts
+import { defineCommand as defineCommand4 } from "citty";
+import { consola as consola5 } from "consola";
+var addRepoCommand = defineCommand4({
   meta: {
-    name: "add-service",
+    name: "add-repo",
     group: "edit",
-    description: "Add a compose service (postgres, mysql, redis, \u2026) to the container config. Idempotent, prints a diff before writing."
+    description: "Add a git repo to the container config. Cloned into projects/<path>/ on container build. Idempotent \u2014 existing project subfolders are left alone. Destination path derived from URL by default; override with --path (supports nested subfolders like apps/web). Branches/PRs are git-level concerns: clone, then `git checkout` inside the container."
   },
   args: {
     name: {
@@ -2441,11 +3056,27 @@ var addServiceCommand = defineCommand7({
       description: "Container name (yml in $MONOCEROS_HOME/container-configs/).",
       required: true
     },
-    service: {
+    url: {
       type: "positional",
-      description: "Service identifier (postgres, mysql, redis).",
+      description: "Git URL (HTTPS or SSH/git@ form). E.g. https://github.com/foo/bar.git, git@github.com:foo/bar.git.",
       required: true
     },
+    path: {
+      type: "string",
+      description: "Destination under projects/. Subfolders via `/` (e.g. apps/web). Default: URL-derived single segment (bar.git \u2192 bar)."
+    },
+    "git-name": {
+      type: "string",
+      description: "Per-repo git committer name. Overrides the container-level git.user.name for this repo only. Pair with --git-email."
+    },
+    "git-email": {
+      type: "string",
+      description: "Per-repo git committer email. Overrides the container-level git.user.email for this repo only. Pair with --git-name."
+    },
+    provider: {
+      type: "string",
+      description: "Git provider for credential-helper guidance: github | gitlab | bitbucket. Required when the URL host is not github.com, gitlab.com, or bitbucket.org \u2014 Monoceros uses this to suggest the right CLI (gh / glab / Atlassian token) on missing credentials."
+    },
     yes: {
       type: "boolean",
       description: "Skip the interactive confirmation and apply the diff.",
@@ -2455,680 +3086,513 @@ var addServiceCommand = defineCommand7({
   },
   async run({ args }) {
     try {
-      const result = await runAddService({
+      const result = await runAddRepo({
         name: args.name,
-        service: args.service,
-        yes: args.yes
-      });
-      process.exit(result.status === "aborted" ? 1 : 0);
-    } catch (err) {
-      consola8.error(err instanceof Error ? err.message : String(err));
-      process.exit(1);
-    }
-  }
-});
-
-// src/commands/apply.ts
-import { defineCommand as defineCommand8 } from "citty";
-
-// src/apply/index.ts
-import { existsSync as existsSync4, promises as fs10 } from "fs";
-import { consola as consola11 } from "consola";
-
-// src/config/state.ts
-import { promises as fs7 } from "fs";
-import path5 from "path";
-function buildStateFile(opts) {
-  return {
-    schemaVersion: CONFIG_SCHEMA_VERSION,
-    origin: opts.origin,
-    monocerosCliVersion: opts.cliVersion,
-    materializedAt: (opts.now ?? /* @__PURE__ */ new Date()).toISOString()
-  };
-}
-function stateFilePath(targetDir) {
-  return path5.join(targetDir, ".monoceros", "state.json");
-}
-async function readStateFile(targetDir) {
-  try {
-    const content = await fs7.readFile(stateFilePath(targetDir), "utf8");
-    return JSON.parse(content);
-  } catch {
-    return void 0;
-  }
-}
-async function writeStateFile(targetDir, state) {
-  const monocerosDir = path5.join(targetDir, ".monoceros");
-  await fs7.mkdir(monocerosDir, { recursive: true });
-  await fs7.writeFile(
-    stateFilePath(targetDir),
-    JSON.stringify(state, null, 2) + "\n"
-  );
-}
-
-// src/config/transform.ts
-function solutionConfigToCreateOptions(config, featureDefaults = {}) {
-  const featureRecord = {};
-  for (const entry2 of config.features) {
-    const defaults = featureDefaults[entry2.ref] ?? {};
-    featureRecord[entry2.ref] = { ...defaults, ...entry2.options ?? {} };
-  }
-  const result = {
-    name: config.name,
-    languages: [...config.languages],
-    services: [...config.services]
-  };
-  if (config.externalServices.postgres !== void 0) {
-    result.postgresUrl = config.externalServices.postgres;
-  }
-  if (config.aptPackages.length > 0) {
-    result.aptPackages = [...config.aptPackages];
-  }
-  if (Object.keys(featureRecord).length > 0) {
-    result.features = featureRecord;
-  }
-  if (config.installUrls.length > 0) {
-    result.installUrls = [...config.installUrls];
-  }
-  if (config.repos.length > 0) {
-    result.repos = config.repos.map((r) => ({
-      url: r.url,
-      // `path` is optional in the yml; CreateOptions requires it.
-      // When the yml omits `path`, fall back to the URL-derived
-      // single-segment default (`https://.../foo.git` → `foo`),
-      // which lands the clone at `projects/foo/`.
-      path: r.path ?? deriveRepoName(r.url),
-      ...r.git?.user ? { gitUser: { name: r.git.user.name, email: r.git.user.email } } : {},
-      ...r.provider ? { provider: r.provider } : {}
-    }));
-  }
-  const routingPorts = config.routing?.ports ?? [];
-  if (routingPorts.length > 0) {
-    const seen = /* @__PURE__ */ new Set();
-    const ports = [];
-    for (const entry2 of routingPorts) {
-      const n = portNumber(entry2);
-      if (seen.has(n)) continue;
-      seen.add(n);
-      ports.push(n);
-    }
-    result.ports = ports;
-  }
-  if (config.routing?.vscodeAutoForward !== void 0) {
-    result.vscodeAutoForward = config.routing.vscodeAutoForward;
-  }
-  return result;
-}
-
-// src/util/format.ts
-var ESC = "\x1B[";
-var ANSI_BOLD2 = `${ESC}1m`;
-var ANSI_UNDERLINE2 = `${ESC}4m`;
-var ANSI_CYAN2 = `${ESC}36m`;
-var ANSI_GREY2 = `${ESC}90m`;
-var ANSI_RESET2 = `${ESC}0m`;
-function makeWrap(isTty2) {
-  return (s, ...codes) => isTty2 ? codes.join("") + s + ANSI_RESET2 : s;
-}
-function makePalette(isTty2) {
-  const wrap = makeWrap(isTty2);
-  return {
-    bold: (s) => wrap(s, ANSI_BOLD2),
-    underline: (s) => wrap(s, ANSI_UNDERLINE2),
-    cyan: (s) => wrap(s, ANSI_CYAN2),
-    dim: (s) => wrap(s, ANSI_GREY2),
-    sectionLine: (label) => wrap(`\u25B8 ${label}`, ANSI_BOLD2, ANSI_UNDERLINE2)
-  };
-}
-function colorsFor(stream) {
-  return makePalette(stream.isTTY ?? false);
-}
-var stderrPalette = makePalette(process.stderr.isTTY ?? false);
-var bold2 = stderrPalette.bold;
-var underline2 = stderrPalette.underline;
-var cyan2 = stderrPalette.cyan;
-var dim = stderrPalette.dim;
-var sectionLine = stderrPalette.sectionLine;
-
-// src/devcontainer/compose.ts
-import { spawn as spawn3 } from "child_process";
-import { existsSync as existsSync3 } from "fs";
-import path7 from "path";
-import { consola as consola9 } from "consola";
-
-// src/util/mask-secrets.ts
-import { Transform } from "stream";
-var PATTERNS = [
-  // Atlassian Cloud API token. Starts with literal `ATATT3xFf` plus
-  // a long URL-safe-base64 tail. Tightened to that prefix to avoid
-  // matching unrelated all-caps words.
-  { name: "atlassian-api", re: /ATATT3xFf[A-Za-z0-9+/=_-]{20,}/g },
-  // Bitbucket Cloud app password.
-  { name: "bitbucket-app", re: /ATBB[A-Za-z0-9+/=_-]{20,}/g },
-  // GitHub PAT (classic), OAuth, user, server, refresh — all share
-  // the `gh<lower-letter>_<base62>` shape per GitHub's token format.
-  { name: "github-token", re: /gh[a-z]_[A-Za-z0-9]{20,}/g },
-  // GitHub fine-grained PAT.
-  { name: "github-pat", re: /github_pat_[A-Za-z0-9_]{20,}/g },
-  // Anthropic API key.
-  { name: "anthropic-api", re: /sk-ant-[A-Za-z0-9_-]{20,}/g }
-];
-function maskSecrets(text) {
-  let result = text;
-  for (const { re } of PATTERNS) {
-    result = result.replace(re, maskOne);
-  }
-  return result;
-}
-function maskOne(token) {
-  if (token.length <= 12) return token;
-  return `${token.slice(0, 5)}\u2026${token.slice(-6)}`;
-}
-function createSecretMaskStream() {
-  let buffer = "";
-  return new Transform({
-    decodeStrings: true,
-    transform(chunk, _enc, cb) {
-      const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
-      buffer += text;
-      const lastNewline = buffer.lastIndexOf("\n");
-      if (lastNewline === -1) {
-        cb(null);
-        return;
-      }
-      const flushable = buffer.slice(0, lastNewline + 1);
-      buffer = buffer.slice(lastNewline + 1);
-      cb(null, maskSecrets(flushable));
-    },
-    flush(cb) {
-      if (buffer.length > 0) {
-        const tail = maskSecrets(buffer);
-        buffer = "";
-        cb(null, tail);
-        return;
-      }
-      cb(null);
-    }
-  });
-}
-
-// src/devcontainer/cli.ts
-import { spawn as spawn2 } from "child_process";
-import { readFileSync as readFileSync2 } from "fs";
-import { createRequire } from "module";
-import path6 from "path";
-var require_ = createRequire(import.meta.url);
-var cachedBinaryPath = null;
-function devcontainerCliPath() {
-  if (cachedBinaryPath) return cachedBinaryPath;
-  const pkgJsonPath = require_.resolve("@devcontainers/cli/package.json");
-  const pkg = JSON.parse(readFileSync2(pkgJsonPath, "utf8"));
-  const binEntry = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.devcontainer ?? "";
-  if (!binEntry) {
-    throw new Error("Could not resolve @devcontainers/cli bin entry.");
-  }
-  cachedBinaryPath = path6.resolve(path6.dirname(pkgJsonPath), binEntry);
-  return cachedBinaryPath;
-}
-var spawnDevcontainer = (args, cwd, options = {}) => {
-  const binPath = devcontainerCliPath();
-  return new Promise((resolve, reject) => {
-    if (options.interactive) {
-      const child2 = spawn2(process.execPath, [binPath, ...args], {
-        cwd,
-        stdio: "inherit"
+        url: args.url,
+        ...typeof args.path === "string" ? { path: args.path } : {},
+        ...typeof args["git-name"] === "string" ? { gitName: args["git-name"] } : {},
+        ...typeof args["git-email"] === "string" ? { gitEmail: args["git-email"] } : {},
+        ...typeof args.provider === "string" ? { provider: args.provider } : {},
+        yes: args.yes
       });
-      child2.on("error", reject);
-      child2.on("exit", (code) => resolve(code ?? 0));
-      return;
+      process.exit(result.status === "aborted" ? 1 : 0);
+    } catch (err) {
+      consola5.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
     }
-    const child = spawn2(process.execPath, [binPath, ...args], {
-      cwd,
-      stdio: ["ignore", "pipe", "pipe"]
-    });
-    if (options.quiet) {
-      const stdoutChunks = [];
-      const stderrChunks = [];
-      child.stdout?.on("data", (chunk) => stdoutChunks.push(chunk));
-      child.stderr?.on("data", (chunk) => stderrChunks.push(chunk));
-      child.on("error", reject);
-      child.on("exit", (code) => {
-        const exitCode = code ?? 0;
-        if (exitCode !== 0) {
-          process.stderr.write(
-            maskSecrets(Buffer.concat(stderrChunks).toString("utf8"))
-          );
-          process.stderr.write(
-            maskSecrets(Buffer.concat(stdoutChunks).toString("utf8"))
-          );
-        }
-        resolve(exitCode);
+  }
+});
+
+// src/commands/add-language.ts
+import { defineCommand as defineCommand5 } from "citty";
+import { consola as consola6 } from "consola";
+var addLanguageCommand = defineCommand5({
+  meta: {
+    name: "add-language",
+    group: "edit",
+    description: "Add a language toolchain (devcontainer feature) to the container config. Idempotent, prints a diff before writing."
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "Container name (yml in $MONOCEROS_HOME/container-configs/).",
+      required: true
+    },
+    language: {
+      type: "positional",
+      description: "Language identifier from the feature whitelist (e.g. python, java, rust).",
+      required: true
+    },
+    yes: {
+      type: "boolean",
+      description: "Skip the interactive confirmation and apply the diff.",
+      alias: ["y"],
+      default: false
+    }
+  },
+  async run({ args }) {
+    try {
+      const result = await runAddLanguage({
+        name: args.name,
+        language: args.language,
+        yes: args.yes
       });
-      return;
+      process.exit(result.status === "aborted" ? 1 : 0);
+    } catch (err) {
+      consola6.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
     }
-    child.stdout?.pipe(createSecretMaskStream()).pipe(process.stdout);
-    child.stderr?.pipe(createSecretMaskStream()).pipe(process.stderr);
-    child.on("error", reject);
-    child.on("exit", (code) => resolve(code ?? 0));
-  });
-};
-
-// src/devcontainer/compose.ts
-var spawnDockerCompose = (args, cwd) => {
-  return new Promise((resolve, reject) => {
-    const child = spawn3("docker", ["compose", ...args], {
-      cwd,
-      stdio: ["inherit", "pipe", "pipe"]
-    });
-    child.stdout?.pipe(createSecretMaskStream()).pipe(process.stdout);
-    child.stderr?.pipe(createSecretMaskStream()).pipe(process.stderr);
-    child.on("error", reject);
-    child.on("exit", (code) => resolve(code ?? 0));
-  });
-};
-var spawnBash = (args, cwd) => {
-  return new Promise((resolve, reject) => {
-    const child = spawn3("bash", args, {
-      cwd,
-      stdio: ["inherit", "pipe", "pipe"]
-    });
-    child.stdout?.pipe(createSecretMaskStream()).pipe(process.stdout);
-    child.stderr?.pipe(createSecretMaskStream()).pipe(process.stderr);
-    child.on("error", reject);
-    child.on("exit", (code) => resolve(code ?? 0));
-  });
-};
-function composeProjectName(root) {
-  return `${path7.basename(root)}_devcontainer`;
-}
-function resolveCompose(root) {
-  if (!existsSync3(path7.join(root, ".devcontainer"))) {
-    throw new Error(
-      `No .devcontainer/ at ${root}. Run \`monoceros apply <name>\` first.`
-    );
   }
-  const composeFile = path7.join(root, ".devcontainer", "compose.yaml");
-  if (!existsSync3(composeFile)) {
-    throw new Error(
-      `No compose.yaml at ${composeFile}. \`start\` / \`stop\` / \`status\` / \`logs\` require services configured via \`monoceros add-service <name> <svc>\`. Use \`monoceros shell <name>\` to enter the container directly.`
-    );
+});
+
+// src/commands/add-port.ts
+import { defineCommand as defineCommand6 } from "citty";
+import { consola as consola7 } from "consola";
+var addPortCommand = defineCommand6({
+  meta: {
+    name: "add-port",
+    group: "edit",
+    description: "Add one or more ports to the container config so they become reachable from the host via Traefik (`<container>.localhost` / `<container>-<port>.localhost`). Pass port numbers after `--` (e.g. `monoceros add-port sandbox -- 3000 5173 6006`). Idempotent. Persisted in the yml so later `monoceros apply` runs restore the routes. Pass `--default` together with a single port to make it the bare `<container>.localhost` route \u2014 the port is inserted at position 0 (or moved there if it already exists)."
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "Container name (yml in $MONOCEROS_HOME/container-configs/).",
+      required: true
+    },
+    yes: {
+      type: "boolean",
+      description: "Skip the interactive confirmation and apply the diff.",
+      alias: ["y"],
+      default: false
+    },
+    default: {
+      type: "boolean",
+      description: "Make the (single) port the new default route at `<container>.localhost`. Inserts the port at position 0 of `routing.ports`, or moves it there if it already exists. Errors when more than one port is passed.",
+      default: false
+    }
+  },
+  async run({ args }) {
+    const tokens = [...getInnerArgs()];
+    if (tokens.length === 0) {
+      consola7.error(
+        "No ports given. Usage: `monoceros add-port <containername> [--yes] [--default] -- <port> [<port> \u2026]`."
+      );
+      process.exit(1);
+    }
+    try {
+      const result = await runAddPort({
+        name: args.name,
+        ports: tokens.map(coerceToken),
+        yes: args.yes,
+        asDefault: args.default
+      });
+      process.exit(result.status === "aborted" ? 1 : 0);
+    } catch (err) {
+      consola7.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
   }
-  return { composeFile, projectName: composeProjectName(root) };
-}
-async function runComposeAction(buildSubArgs, opts) {
-  const { composeFile, projectName } = resolveCompose(opts.root);
-  const spawnFn = opts.spawn ?? spawnDockerCompose;
-  const subArgs = buildSubArgs(opts.service);
-  return spawnFn(["-f", composeFile, "-p", projectName, ...subArgs], opts.root);
-}
-async function runStart(opts) {
-  resolveCompose(opts.root);
-  const logger = opts.logger ?? { info: (msg) => consola9.info(msg) };
-  const spawnFn = opts.spawn ?? spawnDevcontainer;
-  logger.info(`Bringing devcontainer up at ${opts.root}\u2026`);
-  return spawnFn(
-    ["up", "--workspace-folder", opts.root, "--mount-workspace-git-root=false"],
-    opts.root
-  );
+});
+function coerceToken(raw) {
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : raw;
 }
-async function runContainerCycle(root, opts) {
-  const { hasCompose, logger } = opts;
-  if (hasCompose) {
-    const projectName = composeProjectName(root);
-    logger.info(
-      `Force-removing existing ${projectName} containers (volumes preserved)\u2026`
-    );
-    const cleanupSpawn = opts.cleanupSpawn ?? spawnBash;
-    const script = [
-      `set -u`,
-      `echo "[cleanup] checking project ${projectName}\u2026"`,
-      `by_label=$(docker ps -aq --filter "label=com.docker.compose.project=${projectName}" 2>/dev/null || true)`,
-      `by_name=$(docker ps -aq --filter "name=^${projectName}-" 2>/dev/null || true)`,
-      `to_remove=$(printf "%s\\n%s\\n" "$by_label" "$by_name" | sort -u | grep -v "^$" || true)`,
-      `if [ -n "$to_remove" ]; then echo "[cleanup] removing: $(echo $to_remove | tr "\\n" " ")"; docker rm -f $to_remove >/dev/null || true; else echo "[cleanup] no containers to remove"; fi`,
-      `docker network rm ${projectName}_default 2>/dev/null && echo "[cleanup] network ${projectName}_default removed" || echo "[cleanup] network ${projectName}_default not present"`,
-      `remaining_label=$(docker ps -aq --filter "label=com.docker.compose.project=${projectName}" 2>/dev/null || true)`,
-      `remaining_name=$(docker ps -aq --filter "name=^${projectName}-" 2>/dev/null || true)`,
-      `if [ -n "$remaining_label" ] || [ -n "$remaining_name" ]; then echo "" >&2; echo "ERROR: containers under project ${projectName} reappeared after removal." >&2; echo "This typically means VS Code's Remote Containers extension is connected to" >&2; echo "this devcontainer and auto-recreated it. Close the dev container session" >&2; echo "in VS Code (Cmd+Shift+P \u2192 'Dev Containers: Close Remote Connection')" >&2; echo "and retry \\\`monoceros apply\\\`." >&2; exit 1; fi`,
-      `echo "[cleanup] done"`
-    ].join("; ");
-    const cleanupCode = await cleanupSpawn(["-c", script], root);
-    if (cleanupCode !== 0) return cleanupCode;
-    return runStart({
-      root,
-      ...opts.devcontainerSpawn ? { spawn: opts.devcontainerSpawn } : {},
-      logger
-    });
-  }
-  logger.info(`Recreating image-mode devcontainer at ${root}\u2026`);
-  const spawnFn = opts.devcontainerSpawn ?? spawnDevcontainer;
-  return spawnFn(
-    [
-      "up",
-      "--workspace-folder",
-      root,
-      "--mount-workspace-git-root=false",
-      "--remove-existing-container"
-    ],
-    root
-  );
+
+// src/commands/add-service.ts
+import { defineCommand as defineCommand7 } from "citty";
+import { consola as consola8 } from "consola";
+var addServiceCommand = defineCommand7({
+  meta: {
+    name: "add-service",
+    group: "edit",
+    description: "Add a compose service (postgres, mysql, redis, \u2026) to the container config. Idempotent, prints a diff before writing."
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "Container name (yml in $MONOCEROS_HOME/container-configs/).",
+      required: true
+    },
+    service: {
+      type: "positional",
+      description: "Service identifier (postgres, mysql, redis).",
+      required: true
+    },
+    yes: {
+      type: "boolean",
+      description: "Skip the interactive confirmation and apply the diff.",
+      alias: ["y"],
+      default: false
+    }
+  },
+  async run({ args }) {
+    try {
+      const result = await runAddService({
+        name: args.name,
+        service: args.service,
+        yes: args.yes
+      });
+      process.exit(result.status === "aborted" ? 1 : 0);
+    } catch (err) {
+      consola8.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  }
+});
+
+// src/commands/apply.ts
+import { defineCommand as defineCommand8 } from "citty";
+
+// src/apply/index.ts
+import { existsSync as existsSync4, promises as fs10 } from "fs";
+import { consola as consola11 } from "consola";
+
+// src/config/state.ts
+import { promises as fs8 } from "fs";
+import path7 from "path";
+function buildStateFile(opts) {
+  return {
+    schemaVersion: CONFIG_SCHEMA_VERSION,
+    origin: opts.origin,
+    monocerosCliVersion: opts.cliVersion,
+    materializedAt: (opts.now ?? /* @__PURE__ */ new Date()).toISOString()
+  };
 }
-function runStop(opts) {
-  return runComposeAction(
-    (service) => ["stop", ...service ? [service] : []],
-    opts
-  );
+function stateFilePath(targetDir) {
+  return path7.join(targetDir, ".monoceros", "state.json");
 }
-function runStatus(opts) {
-  return runComposeAction(
-    (service) => ["ps", ...service ? [service] : []],
-    opts
-  );
+async function readStateFile(targetDir) {
+  try {
+    const content = await fs8.readFile(stateFilePath(targetDir), "utf8");
+    return JSON.parse(content);
+  } catch {
+    return void 0;
+  }
 }
-function runLogs(opts) {
-  const follow = opts.follow ?? true;
-  return runComposeAction(
-    (service) => [
-      "logs",
-      ...follow ? ["-f"] : [],
-      ...service ? [service] : []
-    ],
-    opts
+async function writeStateFile(targetDir, state) {
+  const monocerosDir = path7.join(targetDir, ".monoceros");
+  await fs8.mkdir(monocerosDir, { recursive: true });
+  await fs8.writeFile(
+    stateFilePath(targetDir),
+    JSON.stringify(state, null, 2) + "\n"
   );
 }
 
-// src/devcontainer/credentials.ts
-import { spawn as spawn4 } from "child_process";
-import { promises as fs8 } from "fs";
-import path8 from "path";
-var realGitCredentialFill = (input) => {
-  return new Promise((resolve, reject) => {
-    const child = spawn4("git", ["credential", "fill"], {
-      stdio: ["pipe", "pipe", "inherit"],
-      env: {
-        ...process.env,
-        GIT_TERMINAL_PROMPT: "0",
-        GIT_ASKPASS: "",
-        SSH_ASKPASS: ""
-      }
-    });
-    let stdout = "";
-    child.stdout.on("data", (chunk) => {
-      stdout += chunk.toString();
-    });
-    child.on("error", reject);
-    child.on("exit", (code) => resolve({ stdout, exitCode: code ?? 0 }));
-    child.stdin.write(input);
-    child.stdin.end();
-  });
-};
-function resolveProvider(host, explicit) {
-  const canonical = KNOWN_PROVIDER_HOSTS[host.toLowerCase()];
-  if (canonical) return canonical;
-  return explicit ?? "unknown";
-}
-function uniqueHttpsHosts(repos) {
-  const byHost = /* @__PURE__ */ new Map();
-  for (const repo of repos) {
-    if (!repo.url.startsWith("https://")) continue;
-    let host;
-    try {
-      host = new URL(repo.url).hostname;
-    } catch {
-      continue;
-    }
-    if (byHost.has(host)) continue;
-    byHost.set(host, { host, provider: resolveProvider(host, repo.provider) });
+// src/config/transform.ts
+function solutionConfigToCreateOptions(config, featureDefaults = {}) {
+  const featureRecord = {};
+  for (const entry2 of config.features) {
+    const defaults = featureDefaults[entry2.ref] ?? {};
+    const containerOpts = Object.fromEntries(
+      Object.entries(entry2.options ?? {}).filter(([, v]) => v !== "")
+    );
+    featureRecord[entry2.ref] = { ...defaults, ...containerOpts };
   }
-  return [...byHost.values()];
-}
-function installCommandForOS(opts) {
-  switch (process.platform) {
-    case "darwin":
-      return cyan2(opts.brew);
-    case "win32":
-      return cyan2(opts.winget);
-    default:
-      if (opts.linuxBrew) return cyan2(opts.linuxBrew);
-      return `See ${opts.linuxDocsUrl} for package instructions.`;
+  const result = {
+    name: config.name,
+    languages: [...config.languages],
+    services: [...config.services]
+  };
+  if (config.externalServices.postgres !== void 0) {
+    result.postgresUrl = config.externalServices.postgres;
   }
-}
-function providerSetupHint(host, provider) {
-  if (provider === "github") {
-    const isSaas = host.toLowerCase() === "github.com";
-    const hostArg = isSaas ? "" : ` --hostname ${host}`;
-    const install = installCommandForOS({
-      brew: "brew install gh",
-      winget: "winget install --id GitHub.cli",
-      linuxBrew: "brew install gh",
-      linuxDocsUrl: "https://github.com/cli/cli#installation"
-    });
-    return {
-      title: `${host} \u2014 GitHub`,
-      body: [
-        "Install the GitHub CLI:",
-        install,
-        "",
-        "Then run once:",
-        cyan2(`gh auth login${hostArg}`),
-        cyan2(`gh auth setup-git${hostArg}`),
-        "",
-        "`gh auth login` walks through OAuth in your browser.",
-        "`gh auth setup-git` wires gh into git as a credential helper."
-      ].join("\n")
-    };
+  if (config.aptPackages.length > 0) {
+    result.aptPackages = [...config.aptPackages];
   }
-  if (provider === "gitlab") {
-    const isSaas = host.toLowerCase() === "gitlab.com";
-    const hostArg = isSaas ? "" : ` --hostname ${host}`;
-    const install = installCommandForOS({
-      brew: "brew install glab",
-      winget: "winget install --id GLab.GLab",
-      linuxBrew: "brew install glab",
-      linuxDocsUrl: "https://gitlab.com/gitlab-org/cli#installation"
-    });
-    return {
-      title: `${host} \u2014 GitLab`,
-      body: [
-        "Install the GitLab CLI (glab):",
-        install,
-        "",
-        "Then run once:",
-        cyan2(`glab auth login${hostArg}`),
-        "",
-        "Choose `HTTPS` when asked for git-protocol, then accept",
-        '"Authenticate Git with your GitLab credentials" \u2014 glab',
-        "configures itself as the git credential helper."
-      ].join("\n")
-    };
+  if (Object.keys(featureRecord).length > 0) {
+    result.features = featureRecord;
   }
-  if (provider === "bitbucket") {
-    const isCloud = host.toLowerCase() === "bitbucket.org";
-    if (isCloud) {
-      return {
-        title: `${host} \u2014 Bitbucket Cloud`,
-        body: [
-          "Bitbucket has no first-party CLI for git-credentials, so this",
-          "is a manual one-time setup. Generate an Atlassian API token at",
-          "https://id.atlassian.com/manage-profile/security/api-tokens",
-          "",
-          "Then store it via your OS credential helper:",
-          cyan2(
-            `git credential approve <<< $'protocol=https\\nhost=${host}\\nusername=<your-atlassian-email>\\npassword=<token>\\n'`
-          )
-        ].join("\n")
-      };
+  if (config.installUrls.length > 0) {
+    result.installUrls = [...config.installUrls];
+  }
+  if (config.repos.length > 0) {
+    result.repos = config.repos.map((r) => ({
+      url: r.url,
+      // `path` is optional in the yml; CreateOptions requires it.
+      // When the yml omits `path`, fall back to the URL-derived
+      // single-segment default (`https://.../foo.git` → `foo`),
+      // which lands the clone at `projects/foo/`.
+      path: r.path ?? deriveRepoName(r.url),
+      // gitUser is forwarded only when BOTH name + email are set.
+      // The relaxed GitUserSchema accepts nullable / empty strings
+      // (so a yml placeholder `name:` parses without error), so we
+      // re-check here before downstream code, which expects both
+      // values to be non-empty.
+      ...r.git?.user?.name && r.git.user.email ? { gitUser: { name: r.git.user.name, email: r.git.user.email } } : {},
+      ...r.provider ? { provider: r.provider } : {}
+    }));
+  }
+  const routingPorts = config.routing?.ports ?? [];
+  if (routingPorts.length > 0) {
+    const seen = /* @__PURE__ */ new Set();
+    const ports = [];
+    for (const entry2 of routingPorts) {
+      const n = portNumber(entry2);
+      if (seen.has(n)) continue;
+      seen.add(n);
+      ports.push(n);
     }
-    return {
-      title: `${host} \u2014 Bitbucket Data Center`,
-      body: [
-        "Bitbucket has no first-party CLI for git-credentials, so this",
-        "is a manual one-time setup. Generate a personal HTTP access",
-        `token in your Bitbucket UI: profile picture (top right on ${host})`,
-        "\u2192 Manage account \u2192 HTTP access tokens \u2192 Create token. Give it",
-        "at least repo-read + repo-write scopes for the repos you need.",
-        "",
-        "Then store it via your OS credential helper:",
-        cyan2(
-          `git credential approve <<< $'protocol=https\\nhost=${host}\\nusername=<your-bitbucket-username>\\npassword=<token>\\n'`
-        )
-      ].join("\n")
-    };
+    result.ports = ports;
   }
-  return {
-    title: `${host} \u2014 Gitea`,
-    body: [
-      "Gitea has no first-party CLI helper for git-credentials (the",
-      "`tea` CLI logs into its own config, not into your git credential",
-      "helper), so this is a manual one-time setup. Generate an access",
-      `token in your Gitea UI: profile picture (top right on ${host}) \u2192`,
-      'Settings \u2192 Applications \u2192 "Generate New Token". Give it at',
-      "least the `read:repository` scope (add `write:repository` if you",
-      "need push from the container).",
-      "",
-      "Then store it via your OS credential helper:",
-      cyan2(
-        `git credential approve <<< $'protocol=https\\nhost=${host}\\nusername=<your-gitea-username>\\npassword=<token>\\n'`
-      )
-    ].join("\n")
-  };
+  if (config.routing?.vscodeAutoForward !== void 0) {
+    result.vscodeAutoForward = config.routing.vscodeAutoForward;
+  }
+  return result;
 }
-function parseCredentialFillOutput(output) {
-  const result = {};
-  for (const line of output.split("\n")) {
-    const eqIdx = line.indexOf("=");
-    if (eqIdx <= 0) continue;
-    const key = line.slice(0, eqIdx);
-    const value = line.slice(eqIdx + 1);
-    if (key === "username") result.username = value;
-    if (key === "password") result.password = value;
+
+// src/devcontainer/compose.ts
+import { spawn as spawn5 } from "child_process";
+import { existsSync as existsSync3 } from "fs";
+import path9 from "path";
+import { consola as consola9 } from "consola";
+
+// src/util/mask-secrets.ts
+import { Transform } from "stream";
+var PATTERNS = [
+  // Atlassian Cloud API token. Starts with literal `ATATT3xFf` plus
+  // a long URL-safe-base64 tail. Tightened to that prefix to avoid
+  // matching unrelated all-caps words.
+  { name: "atlassian-api", re: /ATATT3xFf[A-Za-z0-9+/=_-]{20,}/g },
+  // Bitbucket Cloud app password.
+  { name: "bitbucket-app", re: /ATBB[A-Za-z0-9+/=_-]{20,}/g },
+  // GitHub PAT (classic), OAuth, user, server, refresh — all share
+  // the `gh<lower-letter>_<base62>` shape per GitHub's token format.
+  { name: "github-token", re: /gh[a-z]_[A-Za-z0-9]{20,}/g },
+  // GitHub fine-grained PAT.
+  { name: "github-pat", re: /github_pat_[A-Za-z0-9_]{20,}/g },
+  // Anthropic API key.
+  { name: "anthropic-api", re: /sk-ant-[A-Za-z0-9_-]{20,}/g }
+];
+function maskSecrets(text) {
+  let result = text;
+  for (const { re } of PATTERNS) {
+    result = result.replace(re, maskOne);
   }
   return result;
 }
-function formatCredentialLine(host, username, password) {
-  const encUser = encodeURIComponent(username);
-  const encPass = encodeURIComponent(password);
-  return `https://${encUser}:${encPass}@${host}`;
+function maskOne(token) {
+  if (token.length <= 12) return token;
+  return `${token.slice(0, 5)}\u2026${token.slice(-6)}`;
 }
-async function collectGitCredentials(devContainerRoot, hosts, options = {}) {
-  const credsDir = path8.join(devContainerRoot, ".monoceros");
-  const credentialsPath = path8.join(credsDir, "git-credentials");
-  const spawnFn = options.spawn ?? realGitCredentialFill;
-  const logger = options.logger ?? { info: () => {
-  }, warn: () => {
-  } };
-  const lines = [];
-  const perHost = [];
-  for (const { host, provider } of hosts) {
-    if (provider === "unknown") {
-      perHost.push({
-        host,
-        provider: "github",
-        // placeholder — never rendered because pre-flight already bailed
-        status: "no-credentials",
-        detail: "provider not declared (internal: should not reach here)"
-      });
-      continue;
+function createSecretMaskStream() {
+  let buffer = "";
+  return new Transform({
+    decodeStrings: true,
+    transform(chunk, _enc, cb) {
+      const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      buffer += text;
+      const lastNewline = buffer.lastIndexOf("\n");
+      if (lastNewline === -1) {
+        cb(null);
+        return;
+      }
+      const flushable = buffer.slice(0, lastNewline + 1);
+      buffer = buffer.slice(lastNewline + 1);
+      cb(null, maskSecrets(flushable));
+    },
+    flush(cb) {
+      if (buffer.length > 0) {
+        const tail = maskSecrets(buffer);
+        buffer = "";
+        cb(null, tail);
+        return;
+      }
+      cb(null);
     }
-    logger.info(`Fetching credentials for ${host} from host git\u2026`);
-    const input = `protocol=https
-host=${host}
+  });
+}
 
-`;
-    let result;
-    try {
-      result = await spawnFn(input);
-    } catch (err) {
-      const detail = err instanceof Error ? err.message : String(err);
-      perHost.push({ host, provider, status: "spawn-error", detail });
-      continue;
-    }
-    if (result.exitCode !== 0) {
-      perHost.push({
-        host,
-        provider,
-        status: "non-zero-exit",
-        detail: `exit code ${result.exitCode}`
+// src/devcontainer/cli.ts
+import { spawn as spawn4 } from "child_process";
+import { readFileSync as readFileSync2 } from "fs";
+import { createRequire } from "module";
+import path8 from "path";
+var require_ = createRequire(import.meta.url);
+var cachedBinaryPath = null;
+function devcontainerCliPath() {
+  if (cachedBinaryPath) return cachedBinaryPath;
+  const pkgJsonPath = require_.resolve("@devcontainers/cli/package.json");
+  const pkg = JSON.parse(readFileSync2(pkgJsonPath, "utf8"));
+  const binEntry = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.devcontainer ?? "";
+  if (!binEntry) {
+    throw new Error("Could not resolve @devcontainers/cli bin entry.");
+  }
+  cachedBinaryPath = path8.resolve(path8.dirname(pkgJsonPath), binEntry);
+  return cachedBinaryPath;
+}
+var spawnDevcontainer = (args, cwd, options = {}) => {
+  const binPath = devcontainerCliPath();
+  return new Promise((resolve, reject) => {
+    if (options.interactive) {
+      const child2 = spawn4(process.execPath, [binPath, ...args], {
+        cwd,
+        stdio: "inherit"
       });
-      continue;
+      child2.on("error", reject);
+      child2.on("exit", (code) => resolve(code ?? 0));
+      return;
     }
-    const { username, password } = parseCredentialFillOutput(result.stdout);
-    if (!username || !password) {
-      perHost.push({
-        host,
-        provider,
-        status: "no-credentials",
-        detail: "host credential helper returned no username/password"
+    const child = spawn4(process.execPath, [binPath, ...args], {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    if (options.quiet) {
+      const stdoutChunks = [];
+      const stderrChunks = [];
+      child.stdout?.on("data", (chunk) => stdoutChunks.push(chunk));
+      child.stderr?.on("data", (chunk) => stderrChunks.push(chunk));
+      child.on("error", reject);
+      child.on("exit", (code) => {
+        const exitCode = code ?? 0;
+        if (exitCode !== 0) {
+          process.stderr.write(
+            maskSecrets(Buffer.concat(stderrChunks).toString("utf8"))
+          );
+          process.stderr.write(
+            maskSecrets(Buffer.concat(stdoutChunks).toString("utf8"))
+          );
+        }
+        resolve(exitCode);
       });
-      continue;
+      return;
     }
-    lines.push(formatCredentialLine(host, username, password));
-    perHost.push({ host, provider, status: "ok", detail: "" });
+    child.stdout?.pipe(createSecretMaskStream()).pipe(process.stdout);
+    child.stderr?.pipe(createSecretMaskStream()).pipe(process.stderr);
+    child.on("error", reject);
+    child.on("exit", (code) => resolve(code ?? 0));
+  });
+};
+
+// src/devcontainer/compose.ts
+var spawnDockerCompose = (args, cwd) => {
+  return new Promise((resolve, reject) => {
+    const child = spawn5("docker", ["compose", ...args], {
+      cwd,
+      stdio: ["inherit", "pipe", "pipe"]
+    });
+    child.stdout?.pipe(createSecretMaskStream()).pipe(process.stdout);
+    child.stderr?.pipe(createSecretMaskStream()).pipe(process.stderr);
+    child.on("error", reject);
+    child.on("exit", (code) => resolve(code ?? 0));
+  });
+};
+var spawnBash = (args, cwd) => {
+  return new Promise((resolve, reject) => {
+    const child = spawn5("bash", args, {
+      cwd,
+      stdio: ["inherit", "pipe", "pipe"]
+    });
+    child.stdout?.pipe(createSecretMaskStream()).pipe(process.stdout);
+    child.stderr?.pipe(createSecretMaskStream()).pipe(process.stderr);
+    child.on("error", reject);
+    child.on("exit", (code) => resolve(code ?? 0));
+  });
+};
+function composeProjectName(root) {
+  return `${path9.basename(root)}_devcontainer`;
+}
+function resolveCompose(root) {
+  if (!existsSync3(path9.join(root, ".devcontainer"))) {
+    throw new Error(
+      `No .devcontainer/ at ${root}. Run \`monoceros apply <name>\` first.`
+    );
   }
-  await fs8.mkdir(credsDir, { recursive: true });
-  await fs8.writeFile(
-    credentialsPath,
-    lines.join("\n") + (lines.length > 0 ? "\n" : ""),
-    {
-      mode: 384
-    }
+  const composeFile = path9.join(root, ".devcontainer", "compose.yaml");
+  if (!existsSync3(composeFile)) {
+    throw new Error(
+      `No compose.yaml at ${composeFile}. \`start\` / \`stop\` / \`status\` / \`logs\` require services configured via \`monoceros add-service <name> <svc>\`. Use \`monoceros shell <name>\` to enter the container directly.`
+    );
+  }
+  return { composeFile, projectName: composeProjectName(root) };
+}
+async function runComposeAction(buildSubArgs, opts) {
+  const { composeFile, projectName } = resolveCompose(opts.root);
+  const spawnFn = opts.spawn ?? spawnDockerCompose;
+  const subArgs = buildSubArgs(opts.service);
+  return spawnFn(["-f", composeFile, "-p", projectName, ...subArgs], opts.root);
+}
+async function runStart(opts) {
+  resolveCompose(opts.root);
+  const logger = opts.logger ?? { info: (msg) => consola9.info(msg) };
+  const spawnFn = opts.spawn ?? spawnDevcontainer;
+  logger.info(`Bringing devcontainer up at ${opts.root}\u2026`);
+  return spawnFn(
+    ["up", "--workspace-folder", opts.root, "--mount-workspace-git-root=false"],
+    opts.root
+  );
+}
+async function runContainerCycle(root, opts) {
+  const { hasCompose, logger } = opts;
+  if (hasCompose) {
+    const projectName = composeProjectName(root);
+    logger.info(
+      `Force-removing existing ${projectName} containers (volumes preserved)\u2026`
+    );
+    const cleanupSpawn = opts.cleanupSpawn ?? spawnBash;
+    const script = [
+      `set -u`,
+      `echo "[cleanup] checking project ${projectName}\u2026"`,
+      `by_label=$(docker ps -aq --filter "label=com.docker.compose.project=${projectName}" 2>/dev/null || true)`,
+      `by_name=$(docker ps -aq --filter "name=^${projectName}-" 2>/dev/null || true)`,
+      `to_remove=$(printf "%s\\n%s\\n" "$by_label" "$by_name" | sort -u | grep -v "^$" || true)`,
+      `if [ -n "$to_remove" ]; then echo "[cleanup] removing: $(echo $to_remove | tr "\\n" " ")"; docker rm -f $to_remove >/dev/null || true; else echo "[cleanup] no containers to remove"; fi`,
+      `docker network rm ${projectName}_default 2>/dev/null && echo "[cleanup] network ${projectName}_default removed" || echo "[cleanup] network ${projectName}_default not present"`,
+      `remaining_label=$(docker ps -aq --filter "label=com.docker.compose.project=${projectName}" 2>/dev/null || true)`,
+      `remaining_name=$(docker ps -aq --filter "name=^${projectName}-" 2>/dev/null || true)`,
+      `if [ -n "$remaining_label" ] || [ -n "$remaining_name" ]; then echo "" >&2; echo "ERROR: containers under project ${projectName} reappeared after removal." >&2; echo "This typically means VS Code's Remote Containers extension is connected to" >&2; echo "this devcontainer and auto-recreated it. Close the dev container session" >&2; echo "in VS Code (Cmd+Shift+P \u2192 'Dev Containers: Close Remote Connection')" >&2; echo "and retry \\\`monoceros apply\\\`." >&2; exit 1; fi`,
+      `echo "[cleanup] done"`
+    ].join("; ");
+    const cleanupCode = await cleanupSpawn(["-c", script], root);
+    if (cleanupCode !== 0) return cleanupCode;
+    return runStart({
+      root,
+      ...opts.devcontainerSpawn ? { spawn: opts.devcontainerSpawn } : {},
+      logger
+    });
+  }
+  logger.info(`Recreating image-mode devcontainer at ${root}\u2026`);
+  const spawnFn = opts.devcontainerSpawn ?? spawnDevcontainer;
+  return spawnFn(
+    [
+      "up",
+      "--workspace-folder",
+      root,
+      "--mount-workspace-git-root=false",
+      "--remove-existing-container"
+    ],
+    root
   );
-  return {
-    hostsWritten: lines.length,
-    hostsSkipped: perHost.filter((p) => p.status !== "ok").length,
-    perHost,
-    credentialsPath
-  };
 }
-function formatMissingCredentialsError(missing) {
-  if (missing.length === 1) {
-    const m = missing[0];
-    const hint = providerSetupHint(m.host, m.provider);
-    return [
-      `Missing Git credentials: ${hint.title}`,
-      "",
-      hint.body,
-      "",
-      `Then re-run ${cyan2("monoceros apply")}.`
-    ].join("\n");
-  }
-  const lines = [
-    `Missing Git credentials for ${missing.length} hosts:`,
-    ""
-  ];
-  for (const m of missing) {
-    const hint = providerSetupHint(m.host, m.provider);
-    lines.push(hint.title);
-    lines.push("");
-    lines.push(hint.body);
-    lines.push("");
-  }
-  lines.push(`Then re-run ${cyan2("monoceros apply")}.`);
-  return lines.join("\n");
+function runStop(opts) {
+  return runComposeAction(
+    (service) => ["stop", ...service ? [service] : []],
+    opts
+  );
 }
-function formatUnknownProviderError(hosts) {
-  const sorted = [...new Set(hosts)].sort();
-  const lines = [
-    sorted.length === 1 ? `Unknown Git provider for host ${sorted[0]}.` : `Unknown Git provider for ${sorted.length} hosts: ${sorted.join(", ")}.`,
-    "",
-    "Monoceros auto-detects only github.com / gitlab.com / bitbucket.org.",
-    "For any other host (self-hosted GitLab, Gitea, Bitbucket Server, \u2026)",
-    "declare the provider explicitly in the yml. Edit the repo entry:",
-    "",
-    cyan2("  repos:"),
-    cyan2(`    - url: https://${sorted[0]}/\u2026`),
-    cyan2("      provider: gitlab   # or: github, bitbucket, gitea"),
-    "",
-    `Or re-add with ${cyan2("monoceros add-repo <name> <url> --provider=<github|gitlab|bitbucket|gitea>")}.`
-  ];
-  return lines.join("\n");
+function runStatus(opts) {
+  return runComposeAction(
+    (service) => ["ps", ...service ? [service] : []],
+    opts
+  );
+}
+function runLogs(opts) {
+  const follow = opts.follow ?? true;
+  return runComposeAction(
+    (service) => [
+      "logs",
+      ...follow ? ["-f"] : [],
+      ...service ? [service] : []
+    ],
+    opts
+  );
 }
 
 // src/devcontainer/repo-reachability.ts
-import { spawn as spawn5 } from "child_process";
+import { spawn as spawn6 } from "child_process";
 var realGitLsRemote = (url) => {
   return new Promise((resolve, reject) => {
-    const child = spawn5("git", ["ls-remote", "--heads", "--", url], {
+    const child = spawn6("git", ["ls-remote", "--heads", "--", url], {
       stdio: ["ignore", "pipe", "pipe"],
       env: {
         ...process.env,
@@ -3266,10 +3730,10 @@ function adviceForKind(kind) {
 }
 
 // src/devcontainer/docker-mode.ts
-import { spawn as spawn6 } from "child_process";
+import { spawn as spawn7 } from "child_process";
 var realDockerInfo = () => {
   return new Promise((resolve, reject) => {
-    const child = spawn6(
+    const child = spawn7(
       "docker",
       ["info", "--format", "{{json .SecurityOptions}}"],
       {
@@ -3328,13 +3792,13 @@ function formatRootlessNotSupportedError() {
 }
 
 // src/devcontainer/identity.ts
-import { spawn as spawn7 } from "child_process";
+import { spawn as spawn8 } from "child_process";
 import { promises as fs9 } from "fs";
-import path9 from "path";
+import path10 from "path";
 import { consola as consola10 } from "consola";
 var realGitConfigGet = (key) => {
   return new Promise((resolve, reject) => {
-    const child = spawn7("git", ["config", "--global", "--get", key], {
+    const child = spawn8("git", ["config", "--global", "--get", key], {
       stdio: ["ignore", "pipe", "inherit"]
     });
     let stdout = "";
@@ -3358,20 +3822,51 @@ var realIdentityPrompt = async (key) => {
   const trimmed = value.trim();
   return trimmed.length > 0 ? trimmed : void 0;
 };
-async function collectGitIdentity(devContainerRoot, options = {}) {
-  const gitconfigDir = path9.join(devContainerRoot, ".monoceros");
-  const gitconfigPath = path9.join(gitconfigDir, "gitconfig");
+var realScopePrompt = async (ctx) => {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return ctx.reason === "prompt" ? "g" : "n";
+  }
+  const heading = ctx.reason === "persisted" ? `Found identity in .monoceros/gitconfig: ${ctx.name} <${ctx.email}>. Promote where?` : "Save this identity where?";
+  const choice = await consola10.prompt(heading, {
+    type: "select",
+    options: [
+      {
+        label: "Globally \u2014 every container uses it as default",
+        value: "g"
+      },
+      {
+        label: "In this container only",
+        value: "c"
+      },
+      {
+        label: "Both \u2014 global default plus container-level entry",
+        value: "b"
+      },
+      {
+        label: "Keep as-is \u2014 do not write to monoceros-config or yml",
+        value: "n"
+      }
+    ],
+    initial: "g"
+  });
+  if (choice === "g" || choice === "c" || choice === "b" || choice === "n") {
+    return choice;
+  }
+  return void 0;
+};
+async function resolveIdentityWithPrompt(options = {}) {
   const spawnFn = options.spawn ?? realGitConfigGet;
   const promptFn = options.prompt ?? realIdentityPrompt;
+  const scopePromptFn = options.scopePrompt ?? realScopePrompt;
   const logger = options.logger ?? { info: () => {
   }, warn: () => {
   } };
-  const existing = await readExistingGitconfig(gitconfigPath);
+  const persisted = options.persistedValues ?? {};
   const name = await resolveKey("user.name", {
     override: options.containerOverride?.name,
     defaultValue: options.defaults?.name,
     spawnFn,
-    persistedValue: existing.name,
+    persistedValue: persisted.name,
     promptFn,
     logger
   });
@@ -3379,35 +3874,77 @@ async function collectGitIdentity(devContainerRoot, options = {}) {
     override: options.containerOverride?.email,
     defaultValue: options.defaults?.email,
     spawnFn,
-    persistedValue: existing.email,
+    persistedValue: persisted.email,
     promptFn,
     logger
   });
+  const alreadyCanonical = !!options.containerOverride?.name || !!options.containerOverride?.email || !!options.defaults?.name || !!options.defaults?.email;
+  const promptableSources = [
+    "prompt",
+    "persisted"
+  ];
+  const bothPromotable = name?.source !== void 0 && email?.source !== void 0 && promptableSources.includes(name.source) && promptableSources.includes(email.source) && name.source === email.source;
+  let promptedScope;
+  if (!alreadyCanonical && bothPromotable && name?.value && email?.value) {
+    promptedScope = await scopePromptFn({
+      reason: name.source,
+      name: name.value,
+      email: email.value
+    });
+  }
+  return {
+    ...name?.value !== void 0 ? { name: name.value } : {},
+    ...email?.value !== void 0 ? { email: email.value } : {},
+    // Only surface `prompted` when the scope is a persistence target
+    // (`g`/`c`/`b`). `'n'` means "do nothing" — no point passing it
+    // to the caller as a "go persist" signal.
+    ...promptedScope && promptedScope !== "n" && name?.value && email?.value ? {
+      prompted: {
+        name: name.value,
+        email: email.value,
+        scope: promptedScope
+      }
+    } : {}
+  };
+}
+async function collectGitIdentity(devContainerRoot, options = {}) {
+  const gitconfigDir = path10.join(devContainerRoot, ".monoceros");
+  const gitconfigPath = path10.join(gitconfigDir, "gitconfig");
+  const logger = options.logger ?? { info: () => {
+  }, warn: () => {
+  } };
+  const existing = await readExistingGitconfig(gitconfigPath);
+  const resolved = await resolveIdentityWithPrompt({
+    ...options,
+    persistedValues: existing,
+    logger
+  });
   const lines = ["[user]"];
-  if (name !== void 0) lines.push(`	name = ${name}`);
-  if (email !== void 0) lines.push(`	email = ${email}`);
+  if (resolved.name !== void 0) lines.push(`	name = ${resolved.name}`);
+  if (resolved.email !== void 0) lines.push(`	email = ${resolved.email}`);
   await fs9.mkdir(gitconfigDir, { recursive: true });
   await fs9.writeFile(gitconfigPath, lines.join("\n") + "\n");
   return {
-    ...name !== void 0 ? { name } : {},
-    ...email !== void 0 ? { email } : {},
-    gitconfigPath
+    ...resolved.name !== void 0 ? { name: resolved.name } : {},
+    ...resolved.email !== void 0 ? { email: resolved.email } : {},
+    gitconfigPath,
+    ...resolved.prompted ? { prompted: resolved.prompted } : {}
   };
 }
 async function resolveKey(key, opts) {
   if (opts.override !== void 0 && opts.override.length > 0) {
-    return opts.override;
+    return { value: opts.override, source: "container" };
   }
   if (opts.defaultValue !== void 0 && opts.defaultValue.length > 0) {
-    return opts.defaultValue;
+    return { value: opts.defaultValue, source: "defaults" };
   }
   const hostValue = await readKeyFromHost(opts.spawnFn, key, opts.logger);
-  if (hostValue !== void 0) return hostValue;
+  if (hostValue !== void 0) return { value: hostValue, source: "host" };
   if (opts.persistedValue !== void 0 && opts.persistedValue.length > 0) {
-    return opts.persistedValue;
+    return { value: opts.persistedValue, source: "persisted" };
   }
   const prompted = await opts.promptFn(key);
-  if (prompted !== void 0) return prompted;
+  if (prompted !== void 0) return { value: prompted, source: "prompt" };
   opts.logger.warn(
     `No ${key} resolvable (yml override, monoceros-config.yml defaults, host \`git config --global\`, persisted .monoceros/gitconfig, prompt). Container git will have no ${key} until set explicitly.`
   );
@@ -3489,13 +4026,17 @@ ${sectionLine(label)}
     warn: logger.warn ?? logger.info
   };
   if (hasRepos || hasContainerGitUser || hasDefaultGitUser) {
-    await collectGitIdentity(targetDir, {
+    const identity = await collectGitIdentity(targetDir, {
       ...opts.identitySpawn ? { spawn: opts.identitySpawn } : {},
       ...opts.identityPrompt ? { prompt: opts.identityPrompt } : {},
+      ...opts.identityScopePrompt ? { scopePrompt: opts.identityScopePrompt } : {},
       ...parsed.config.git?.user ? { containerOverride: parsed.config.git.user } : {},
       ...globalConfig?.defaults?.git?.user ? { defaults: globalConfig.defaults.git.user } : {},
       logger: idLogger
     });
+    if (identity.prompted) {
+      await persistPromptedIdentity(identity.prompted, ymlPath, home, logger);
+    }
   }
   const hostsToFetch = uniqueHttpsHosts(createOpts.repos ?? []);
   const unknownProviderHosts = hostsToFetch.filter((h) => h.provider === "unknown").map((h) => h.host);
@@ -3628,9 +4169,59 @@ function warnOnDeprecatedFeatureRefs(containerFeatures, globalConfig, logger) {
     }
   }
 }
+async function persistPromptedIdentity(prompted, ymlPath, home, logger) {
+  const wantGlobal = prompted.scope === "g" || prompted.scope === "b";
+  const wantContainer = prompted.scope === "c" || prompted.scope === "b";
+  if (wantGlobal) {
+    try {
+      const result = await writeGlobalDefaultGitUser(
+        { name: prompted.name, email: prompted.email },
+        { monocerosHome: home }
+      );
+      if (result.alreadySet) {
+        logger.warn?.(
+          `monoceros-config.yml already has a defaults.git.user \u2014 left it alone. To replace, edit ${prettyPath(result.filePath)} by hand.`
+        );
+      } else if (result.created) {
+        logger.info(
+          `Saved identity globally \u2014 created ${prettyPath(result.filePath)} with defaults.git.user.`
+        );
+      } else {
+        logger.info(
+          `Saved identity globally \u2014 wrote defaults.git.user into ${prettyPath(result.filePath)}.`
+        );
+      }
+    } catch (err) {
+      logger.warn?.(
+        `Could not persist identity to monoceros-config.yml: ${err instanceof Error ? err.message : String(err)}. The values are still active for this apply via .monoceros/gitconfig.`
+      );
+    }
+  }
+  if (wantContainer) {
+    try {
+      const text = await fs10.readFile(ymlPath, "utf8");
+      const parsed = parseConfig(text, ymlPath);
+      const changed = setContainerGitUserInDoc(parsed.doc, {
+        name: prompted.name,
+        email: prompted.email
+      });
+      if (changed) {
+        const out = stringifyConfig(parsed.doc);
+        await fs10.writeFile(ymlPath, out, "utf8");
+        logger.info(
+          `Saved identity in this container \u2014 wrote git.user into ${prettyPath(ymlPath)}.`
+        );
+      }
+    } catch (err) {
+      logger.warn?.(
+        `Could not persist identity to ${prettyPath(ymlPath)}: ${err instanceof Error ? err.message : String(err)}. The values are still active for this apply via .monoceros/gitconfig.`
+      );
+    }
+  }
+}
 
 // src/version.ts
-var CLI_VERSION = true ? "1.7.4" : "dev";
+var CLI_VERSION = true ? "1.8.0" : "dev";
 
 // src/commands/_dispatch.ts
 import { consola as consola12 } from "consola";
@@ -3892,7 +4483,7 @@ import { consola as consola13 } from "consola";
 
 // src/init/components.ts
 import { existsSync as existsSync5, promises as fs11 } from "fs";
-import path10 from "path";
+import path11 from "path";
 import { z as z3 } from "zod";
 import { parse as parseYaml } from "yaml";
 var CategorySchema = z3.enum(["language", "service", "feature"]);
@@ -3949,14 +4540,14 @@ async function loadComponentCatalog(rootDir = componentsDir()) {
 async function walk(baseDir, currentDir, out) {
   const entries = await fs11.readdir(currentDir, { withFileTypes: true });
   for (const entry2 of entries) {
-    const full = path10.join(currentDir, entry2.name);
+    const full = path11.join(currentDir, entry2.name);
     if (entry2.isDirectory()) {
       await walk(baseDir, full, out);
       continue;
     }
     if (!entry2.isFile() || !entry2.name.endsWith(".yml")) continue;
-    const relative = path10.relative(baseDir, full);
-    const name = relative.replace(/\.yml$/, "").split(path10.sep).join("/");
+    const relative = path11.relative(baseDir, full);
+    const name = relative.replace(/\.yml$/, "").split(path11.sep).join("/");
     const text = await fs11.readFile(full, "utf8");
     let raw;
     try {
@@ -4056,35 +4647,49 @@ Available: ${available.join(", ")}.`
 }
 
 // src/init/generator.ts
-var SCHEMA_HEADER = [
-  "# Monoceros solution-config. Edit freely, then run",
-  "# `monoceros apply <name>` to materialize a dev-container.",
-  "#",
-  "# Each section below carries inline comments for the options it",
-  "# accepts. Features expose additional knobs as commented hints",
-  "# under their `options:` block \u2014 un-comment what you need."
-];
+var SCHEMA_HEADER_ACTIVE = "# Solution-config \u2014 describes what should be inside your dev-container.\n# Edit any section, then run `monoceros apply <name>` to (re-)build.";
+var SCHEMA_HEADER_DOCUMENTED = "# Solution-config \u2014 describes what should be inside your dev-container.\n# Every section is commented out by default; un-comment what you need\n# (strip one `#` per line of the block), then run `monoceros apply <name>`.";
+var COMMENT_WIDTH = 76;
 function generateComposedYml(name, components, lookupManifest, repoUrls = [], ports = []) {
   const merged = mergeComponents(components);
   const lines = [];
-  for (const h of SCHEMA_HEADER) lines.push(h);
+  pushHeader(lines, SCHEMA_HEADER_ACTIVE, name);
   lines.push("");
   lines.push("schemaVersion: 1");
   lines.push(`name: ${name}`);
   lines.push("");
   if (merged.languages.length > 0) {
+    pushSectionHeader(
+      lines,
+      LANGUAGES_HEADER,
+      /* commented */
+      false
+    );
     lines.push("languages:");
     for (const lang of merged.languages) lines.push(`  - ${lang}`);
     lines.push("");
   }
   if (merged.services.length > 0) {
+    pushSectionHeader(
+      lines,
+      SERVICES_HEADER,
+      /* commented */
+      false
+    );
     lines.push("services:");
     for (const svc of merged.services) lines.push(`  - ${svc}`);
     lines.push("");
   }
   if (merged.features.length > 0) {
+    pushSectionHeader(
+      lines,
+      FEATURES_HEADER_ACTIVE,
+      /* commented */
+      false
+    );
     lines.push("features:");
     for (const f of merged.features) {
+      lines.push("");
       renderFeatureBlock(
         lines,
         f,
@@ -4096,87 +4701,86 @@ function generateComposedYml(name, components, lookupManifest, repoUrls = [], po
     lines.push("");
   }
   if (repoUrls.length > 0) {
-    renderReposBlock(
+    pushSectionHeader(
       lines,
-      repoUrls,
+      REPOS_HEADER,
       /* commented */
       false
     );
+    lines.push("repos:");
+    for (const url of repoUrls) {
+      lines.push(`  - url: ${url}`);
+      lines.push("    # path:");
+      lines.push("    # provider:");
+      lines.push("    # git:");
+      lines.push("    #   user:");
+      lines.push("    #     name:");
+      lines.push("    #     email:");
+    }
+    lines.push("");
   }
   if (ports.length > 0) {
-    renderActiveRoutingBlock(lines, name, ports);
+    pushSectionHeader(
+      lines,
+      routingHeader(name),
+      /* commented */
+      false
+    );
+    lines.push("routing:");
+    lines.push("  ports:");
+    for (const port of ports) {
+      lines.push(`    - ${port}`);
+    }
+    lines.push("  # vscodeAutoForward: false");
+    lines.push("");
   }
   return ensureTrailingNewline(lines.join("\n"));
 }
 function generateDocumentedYml(name, catalog, lookupManifest, repoUrls = [], ports = []) {
   const byCategory = groupByCategory(catalog);
   const lines = [];
-  for (const h of SCHEMA_HEADER) lines.push(h);
-  lines.push("#");
-  lines.push("# Below is the full set of components shipped with this");
-  lines.push("# workbench, every one commented out. Un-comment the lines");
-  lines.push("# you want active. The same effect (and a cleaner yml) is");
-  lines.push("# achievable by running `monoceros init <name> --with=\u2026`");
-  lines.push("# with a comma-separated list of component names.");
+  pushHeader(lines, SCHEMA_HEADER_DOCUMENTED, name);
   lines.push("");
   lines.push("schemaVersion: 1");
   lines.push(`name: ${name}`);
   lines.push("");
   if (byCategory.language.length > 0) {
-    const items = byCategory.language.flatMap(
-      (c) => (c.file.contributes.languages ?? []).map((lang) => ({
-        value: lang,
-        label: c.file.displayName
-      }))
+    pushSectionHeader(
+      lines,
+      LANGUAGES_HEADER,
+      /* commented */
+      true
     );
-    const width = Math.max(...items.map((i) => i.value.length)) + 2;
-    lines.push("# Languages \u2014 runtime toolchains.");
     lines.push("# languages:");
-    for (const item of items) {
-      const pad = " ".repeat(width - item.value.length);
-      lines.push(`#   - ${item.value}${pad}# ${item.label}`);
+    for (const c of byCategory.language) {
+      for (const lang of c.file.contributes.languages ?? []) {
+        lines.push(`#   - ${lang}`);
+      }
     }
     lines.push("");
   }
   if (byCategory.service.length > 0) {
-    const items = byCategory.service.flatMap(
-      (c) => (c.file.contributes.services ?? []).map((svc) => ({
-        value: svc,
-        label: c.file.displayName
-      }))
+    pushSectionHeader(
+      lines,
+      SERVICES_HEADER,
+      /* commented */
+      true
     );
-    const width = Math.max(...items.map((i) => i.value.length)) + 2;
-    lines.push("# Services \u2014 compose-mode siblings of the workspace");
-    lines.push("# container (compose mode kicks in as soon as at least");
-    lines.push("# one service is active).");
     lines.push("# services:");
-    for (const item of items) {
-      const pad = " ".repeat(width - item.value.length);
-      lines.push(`#   - ${item.value}${pad}# ${item.label}`);
+    for (const c of byCategory.service) {
+      for (const svc of c.file.contributes.services ?? []) {
+        lines.push(`#   - ${svc}`);
+      }
     }
     lines.push("");
   }
   if (byCategory.feature.length > 0) {
-    lines.push("# Features \u2014 devcontainer features installed inside the");
-    lines.push("# container. Each entry has an OCI-style `ref` plus an");
-    lines.push("# optional `options` map. Credentials/auth keys appear");
-    lines.push("# as commented hints; set them here per container, or");
-    lines.push("# globally in monoceros-config.yml under");
-    lines.push("# `defaults.features.<ref>`.");
-    lines.push("#");
-    lines.push("# Catalog:");
-    lines.push("#");
-    const nameColumnWidth = Math.max(...byCategory.feature.map((c) => c.name.length)) + 2;
-    for (const c of byCategory.feature) {
-      const pad = " ".repeat(nameColumnWidth - c.name.length);
-      lines.push(`#   ${c.name}${pad}${c.file.displayName}`);
-    }
-    lines.push("#");
-    lines.push("# Below: one block per feature ref. Un-comment what");
-    lines.push("# you want active. Sub-components share their parent's");
-    lines.push("# block \u2014 pick the parent for the full preset, swap to");
-    lines.push("# a sub-component name for a partial install.");
-    lines.push("#");
+    pushSectionHeader(
+      lines,
+      FEATURES_HEADER_DOCUMENTED,
+      /* commented */
+      true
+    );
     lines.push("# features:");
     const renderedRefs = /* @__PURE__ */ new Set();
     const topLevel = byCategory.feature.filter((c) => !c.name.includes("/"));
@@ -4184,6 +4788,7 @@ function generateDocumentedYml(name, catalog, lookupManifest, repoUrls = [], por
       for (const f of c.file.contributes.features ?? []) {
         if (renderedRefs.has(f.ref)) continue;
         renderedRefs.add(f.ref);
+        lines.push("#");
         renderFeatureBlock(
           lines,
           f,
@@ -4198,6 +4803,7 @@ function generateDocumentedYml(name, catalog, lookupManifest, repoUrls = [], por
       for (const f of c.file.contributes.features ?? []) {
         if (renderedRefs.has(f.ref)) continue;
         renderedRefs.add(f.ref);
+        lines.push("#");
         renderFeatureBlock(
           lines,
           f,
@@ -4209,165 +4815,156 @@ function generateDocumentedYml(name, catalog, lookupManifest, repoUrls = [], por
     }
     lines.push("");
   }
-  renderReposBlock(
-    lines,
-    repoUrls,
-    /* commented */
-    repoUrls.length === 0
-  );
+  if (repoUrls.length > 0) {
+    pushSectionHeader(
+      lines,
+      REPOS_HEADER,
+      /* commented */
+      false
+    );
+    lines.push("repos:");
+    for (const url of repoUrls) {
+      lines.push(`  - url: ${url}`);
+    }
+    lines.push("");
+  } else {
+    pushSectionHeader(
+      lines,
+      REPOS_HEADER,
+      /* commented */
+      true
+    );
+    lines.push("# repos:");
+    lines.push("#   - url: https://github.com/<org>/<repo>.git");
+    lines.push("#     path: <folder>");
+    lines.push("#     provider: github");
+    lines.push("#     git:");
+    lines.push("#       user:");
+    lines.push("#         name: Your Name");
+    lines.push("#         email: you@example.com");
+    lines.push("");
+  }
   if (ports.length > 0) {
-    renderActiveRoutingBlock(lines, name, ports);
+    pushSectionHeader(
+      lines,
+      routingHeader(name),
+      /* commented */
+      false
+    );
+    lines.push("routing:");
+    lines.push("  ports:");
+    for (const port of ports) {
+      lines.push(`    - ${port}`);
+    }
+    lines.push("  # vscodeAutoForward: false");
+    lines.push("");
   } else {
-    renderRoutingHintBlock(lines);
+    pushSectionHeader(
+      lines,
+      routingHeader(name),
+      /* commented */
+      true
+    );
+    lines.push("# routing:");
+    lines.push("#   ports:");
+    lines.push("#     - 3000");
+    lines.push("#     - 5173");
+    lines.push("#   vscodeAutoForward: false");
+    lines.push("");
   }
   return ensureTrailingNewline(lines.join("\n"));
 }
-var COMMENT_WIDTH = 72;
+var LANGUAGES_HEADER = "Language runtimes installed inside the dev-container. Pick the ones your projects build against. The catalog of available runtimes is shown by `monoceros list-components`.";
+var SERVICES_HEADER = "Sibling containers that run alongside the dev-container (databases, caches, message queues, \u2026). Each service is reachable from inside the dev-container by its name as hostname (e.g. `postgres://postgres:5432`). Activating any service switches the container to docker-compose mode automatically.";
+var FEATURES_HEADER_ACTIVE = "A Monoceros dev-container is shaped by features \u2014 pluggable units that drop tooling (AI assistants, language CLIs, cloud SDKs, \u2026) into the container and bring their own options. The features active for this container are listed below; adjust their options as needed. Shared credentials used across containers belong in monoceros-config.yml under `defaults.features.<ref>` rather than here. Full catalog: `monoceros list-components`.";
+var FEATURES_HEADER_DOCUMENTED = "A Monoceros dev-container is shaped by features \u2014 pluggable units that drop tooling (AI assistants, language CLIs, cloud SDKs, \u2026) into the container and bring their own options. Un-comment the blocks below for the features you want active. Shared credentials used across containers belong in monoceros-config.yml under `defaults.features.<ref>` rather than here. Full catalog: `monoceros list-components`.";
+var REPOS_HEADER = "Git repositories cloned into `projects/` on container start-up. HTTPS URLs only. The provider is auto-detected for github.com / gitlab.com / bitbucket.org; for any other host (self-hosted GitLab, Gitea, \u2026) declare `provider:` explicitly. Add more later with `monoceros add-repo`.";
+function routingHeader(name) {
+  return `Container ports exposed to the host through Traefik. Reach them in your browser as ${name}-<port>.localhost (e.g. ${name}-3000.localhost). The first entry is the default route and is also reachable as the bare ${name}.localhost. Manage the list with \`monoceros add-port\`.`;
+}
 function renderFeatureBlock(out, feature, summary, commented) {
-  const c = commented ? "#   " : "  ";
-  const optionHints = summary?.optionHints ?? [];
-  const optionDescriptions = summary?.optionDescriptions ?? {};
-  const usageNotes = summary?.usageNotes ?? [];
-  for (let i = 0; i < usageNotes.length; i++) {
-    if (i > 0) out.push(`${c}#`);
-    for (const line of wrapToComment(
-      usageNotes[i],
-      COMMENT_WIDTH - c.length
-    )) {
-      out.push(`${c}# ${line}`);
-    }
-  }
-  out.push(`${c}- ref: ${feature.ref}`);
+  const yamlPrefix = commented ? "# " : "";
+  const headerLines = buildHeaderLines(summary);
+  for (const line of headerLines) {
+    const wrapped = wrapToComment(line, COMMENT_WIDTH - 2);
+    for (const wl of wrapped) {
+      out.push(`# ${wl}`.trimEnd());
+    }
+  }
+  out.push(`${yamlPrefix}  - ref: ${feature.ref}`);
   const options = feature.options ?? {};
-  const activeOptions = Object.entries(options);
-  const remainingHints = optionHints.filter((h) => !(h in options));
-  if (activeOptions.length > 0) {
-    out.push(`${c}  options:`);
-    for (const [key, value] of activeOptions) {
-      out.push(`${c}    ${key}: ${renderScalarValue(value)}`);
-    }
-    if (remainingHints.length > 0) {
-      out.push(
-        `${c}    # Optional \u2014 override monoceros-config.yml defaults.features:`
-      );
-      for (const hint of remainingHints) {
-        emitHint(out, hint, optionDescriptions[hint], `${c}    `);
-      }
+  const activeKeys = Object.entries(options);
+  const hintKeys = (summary?.optionHints ?? []).filter((h) => !(h in options));
+  if (activeKeys.length === 0 && hintKeys.length === 0) return;
+  if (commented) {
+    out.push(`${yamlPrefix}    options:`);
+    for (const [key, value] of activeKeys) {
+      out.push(`${yamlPrefix}      ${key}: ${renderScalarValue(value)}`);
     }
-  } else if (remainingHints.length > 0) {
-    out.push(
-      `${c}  # Optional \u2014 override monoceros-config.yml defaults.features:`
-    );
-    out.push(`${c}  # options:`);
-    for (const hint of remainingHints) {
-      emitHint(out, hint, optionDescriptions[hint], `${c}  #   `);
+    for (const key of hintKeys) {
+      out.push(`${yamlPrefix}      ${key}:`);
+    }
+    return;
+  }
+  if (activeKeys.length > 0) {
+    out.push(`    options:`);
+    for (const [key, value] of activeKeys) {
+      out.push(`      ${key}: ${renderScalarValue(value)}`);
     }
   }
-}
-function emitHint(out, hint, description, linePrefix) {
-  if (description) {
-    for (const line of wrapToComment(
-      description,
-      COMMENT_WIDTH - linePrefix.length
-    )) {
-      out.push(`${linePrefix}# ${line}`);
+  if (hintKeys.length > 0) {
+    out.push(`    # options:`);
+    for (const key of hintKeys) {
+      out.push(`    #   ${key}:`);
     }
   }
-  out.push(`${linePrefix}${hint}:`);
 }
-function renderReposBlock(out, urls, commented) {
-  out.push("# Repos \u2014 git repositories cloned into projects/ during");
-  out.push("# post-create. HTTPS URLs only. Provider auto-detected");
-  out.push("# for github.com, gitlab.com, bitbucket.org; for any other host");
-  out.push("# (self-hosted GitLab, Bitbucket Data Center, Gitea/Forgejo,");
-  out.push("# GitHub Enterprise, \u2026) declare provider explicitly.");
-  out.push("#");
-  if (commented) {
-    out.push("# repos:");
-    out.push("#   - url: https://github.com/<org>/<repo>.git");
-    out.push(
-      "#     # path: <folder>           # subfolder under projects/; default: URL-derived"
-    );
-    out.push(
-      "#     # provider: github         # github | gitlab | bitbucket | gitea"
-    );
-    out.push(
-      "#     # git:                     # per-repo committer identity override"
-    );
-    out.push("#     #   user:");
-    out.push("#     #     name: Your Name");
-    out.push("#     #     email: you@example.com");
-    out.push("");
-    return;
+function buildHeaderLines(summary) {
+  const out = [];
+  if (!summary) {
+    return out;
+  }
+  const tagline = summary.name?.trim();
+  const description = summary.description?.trim();
+  if (tagline && description) {
+    out.push(`${tagline} \u2014 ${description}`);
+  } else if (tagline) {
+    out.push(tagline);
+  } else if (description) {
+    out.push(description);
+  }
+  for (const note of summary.usageNotes) {
+    const trimmed = note.trim();
+    if (trimmed.length > 0) out.push(trimmed);
+  }
+  if (summary.optionHints.length > 0) {
+    const parts = summary.optionHints.map((key) => {
+      const desc = summary.optionDescriptions[key];
+      const short = desc ? shortenOptionDescription(desc) : void 0;
+      return short ? `${key} (${short})` : key;
+    });
+    out.push(`Options: ${parts.join(", ")}.`);
   }
-  out.push("repos:");
-  for (const url of urls) {
-    const derivedPath = deriveDefaultPath(url);
-    out.push(`  - url: ${url}`);
-    out.push(
-      `    # path: ${derivedPath}            # subfolder under projects/; default: URL-derived (${derivedPath})`
-    );
-    out.push(
-      "    # provider: github         # github | gitlab | bitbucket | gitea"
-    );
-    out.push(
-      "    # git:                     # per-repo committer identity override"
-    );
-    out.push("    #   user:");
-    out.push("    #     name: Your Name");
-    out.push("    #     email: you@example.com");
-  }
-  out.push("");
-}
-function renderRoutingHintBlock(out) {
-  out.push("# Routing \u2014 expose container ports to the host through the");
-  out.push("# shared Traefik singleton. Once any port is declared the");
-  out.push("# container joins the monoceros-proxy network and the proxy");
-  out.push("# routes <name>.localhost (default port) and");
-  out.push("# <name>-<port>.localhost (explicit). `monoceros add-port`");
-  out.push("# manages the list; the block appears on first add. You can");
-  out.push("# also pre-seed at init time via `--with-ports=3000,5173,\u2026`.");
-  out.push("#");
-  out.push("# routing:");
-  out.push("#   ports:                    # internal container ports");
-  out.push(
-    "#     - 3000                  # first entry doubles as <name>.localhost"
-  );
-  out.push("#     - 5173");
-  out.push(
-    "#   vscodeAutoForward: false  # default: false. Traefik is the single"
-  );
-  out.push(
-    "#                             # source of truth \u2014 set true only if you"
-  );
-  out.push(
-    "#                             # want VS Code's port panel as primary."
-  );
-  out.push("");
-}
-function renderActiveRoutingBlock(out, name, ports) {
-  out.push("# Routing \u2014 expose these container ports to the host through");
-  out.push("# the shared Traefik singleton. First entry doubles as");
-  out.push(`# http://${name}.localhost (the default route).`);
-  out.push("routing:");
-  out.push("  ports:");
-  ports.forEach((port, idx) => {
-    if (idx === 0) {
-      out.push(`    - ${port} # default \u2192 http://${name}.localhost`);
-    } else {
-      out.push(`    - ${port}`);
-    }
-  });
-  out.push("  # vscodeAutoForward: false   # set true to keep VS Code's");
-  out.push("  #                            # port-panel alongside Traefik");
-  out.push("");
+  if (summary.documentationURL) {
+    out.push(`See ${summary.documentationURL} for further information.`);
+  }
+  return out;
 }
-function deriveDefaultPath(url) {
-  let last = url;
-  const slash = url.lastIndexOf("/");
-  if (slash >= 0) last = url.slice(slash + 1);
-  if (last.endsWith(".git")) last = last.slice(0, -4);
-  return last || "repo";
+function shortenOptionDescription(desc) {
+  const firstSentence = desc.split(/(?<=[.!?])\s+/)[0]?.trim() ?? desc.trim();
+  return firstSentence.replace(/[.!?]+$/, "").trim();
+}
+function pushHeader(out, header, name) {
+  for (const line of header.replace(/<name>/g, name).split("\n")) {
+    out.push(line);
+  }
+}
+function pushSectionHeader(out, text, _commented) {
+  void _commented;
+  const wrapped = wrapToComment(text, COMMENT_WIDTH - 2);
+  for (const wl of wrapped) {
+    out.push(`# ${wl}`.trimEnd());
+  }
 }
 function wrapToComment(text, width) {
   const words = text.split(/\s+/).filter((w) => w.length > 0);
@@ -4416,10 +5013,10 @@ function ensureTrailingNewline(s) {
 
 // src/init/manifest.ts
 import { existsSync as existsSync6, readFileSync as readFileSync3 } from "fs";
-import path11 from "path";
+import path12 from "path";
 function resolveManifestPath(name, checkoutRoot) {
   if (checkoutRoot) {
-    const checkoutPath = path11.join(
+    const checkoutPath = path12.join(
       checkoutRoot,
       "images",
       "features",
@@ -4428,7 +5025,7 @@ function resolveManifestPath(name, checkoutRoot) {
     );
     if (existsSync6(checkoutPath)) return checkoutPath;
   }
-  const bundlePath = path11.join(
+  const bundlePath = path12.join(
     bundledFeaturesDir(),
     name,
     "devcontainer-feature.json"
@@ -4460,7 +5057,18 @@ function loadFeatureManifestSummary(ref, checkoutRoot = workbenchCheckoutRoot())
         }
       }
     }
-    return { optionHints, optionDescriptions, usageNotes };
+    const name = typeof parsed.name === "string" ? parsed.name : "";
+    const description = typeof parsed.description === "string" ? parsed.description : "";
+    const rawUrl = typeof parsed.documentationURL === "string" ? parsed.documentationURL.trim() : "";
+    const documentationURL = rawUrl.length > 0 && rawUrl.toLowerCase() !== "tbd" ? rawUrl : void 0;
+    return {
+      name,
+      description,
+      documentationURL,
+      optionHints,
+      optionDescriptions,
+      usageNotes
+    };
   } catch {
     return void 0;
   }
@@ -4538,6 +5146,17 @@ async function runInit(opts) {
     seenPorts.add(raw);
     ports.push(raw);
   }
+  let promptedIdentity;
+  if (repos.length > 0) {
+    const globalConfig = await readMonocerosConfig({ monocerosHome: home });
+    promptedIdentity = await resolveIdentityWithPrompt({
+      ...opts.identitySpawn ? { spawn: opts.identitySpawn } : {},
+      ...opts.identityPrompt ? { prompt: opts.identityPrompt } : {},
+      ...opts.identityScopePrompt ? { scopePrompt: opts.identityScopePrompt } : {},
+      ...globalConfig?.defaults?.git?.user ? { defaults: globalConfig.defaults.git.user } : {},
+      logger: { info: logger.info, warn: logger.info }
+    });
+  }
   let text;
   const requested = opts.with ?? [];
   if (requested.length === 0) {
@@ -4548,6 +5167,51 @@ async function runInit(opts) {
   }
   await fs12.mkdir(containerConfigsDir(home), { recursive: true });
   await fs12.writeFile(dest, text, "utf8");
+  if (promptedIdentity?.prompted) {
+    const { name, email, scope } = promptedIdentity.prompted;
+    if (scope === "g" || scope === "b") {
+      try {
+        const result = await writeGlobalDefaultGitUser(
+          { name, email },
+          { monocerosHome: home }
+        );
+        if (result.alreadySet) {
+          logger.info(
+            `monoceros-config.yml already had a defaults.git.user \u2014 left it alone.`
+          );
+        } else if (result.created) {
+          logger.info(
+            `Saved identity globally \u2014 created ${prettyPath(result.filePath)} with defaults.git.user.`
+          );
+        } else {
+          logger.info(
+            `Saved identity globally to ${prettyPath(result.filePath)}.`
+          );
+        }
+      } catch (err) {
+        logger.info(
+          `Could not persist identity to monoceros-config.yml: ${err instanceof Error ? err.message : String(err)}. \`monoceros apply\` will re-prompt.`
+        );
+      }
+    }
+    if (scope === "c" || scope === "b") {
+      try {
+        const written = await fs12.readFile(dest, "utf8");
+        const parsed = parseConfig(written, dest);
+        const changed = setContainerGitUserInDoc(parsed.doc, { name, email });
+        if (changed) {
+          await fs12.writeFile(dest, stringifyConfig(parsed.doc), "utf8");
+          logger.info(
+            `Saved identity in ${prettyPath(dest)} (container-level git.user).`
+          );
+        }
+      } catch (err) {
+        logger.info(
+          `Could not persist identity into ${prettyPath(dest)}: ${err instanceof Error ? err.message : String(err)}. \`monoceros apply\` will re-prompt.`
+        );
+      }
+    }
+  }
   const documented = requested.length === 0;
   const displayPath = prettyPath(dest);
   if (documented) {
@@ -4971,7 +5635,7 @@ import { createInterface } from "readline/promises";
 
 // src/remove/index.ts
 import { existsSync as existsSync8, promises as fs13 } from "fs";
-import path12 from "path";
+import path13 from "path";
 import { consola as consola19 } from "consola";
 async function runRemove(opts) {
   const home = opts.monocerosHome ?? monocerosHome();
@@ -5022,13 +5686,13 @@ async function runRemove(opts) {
   let backupPath = null;
   if (!opts.noBackup && (hasYml || hasContainer)) {
     const ts = (opts.now ?? /* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-    backupPath = path12.join(home, "container-backups", `${opts.name}-${ts}`);
+    backupPath = path13.join(home, "container-backups", `${opts.name}-${ts}`);
     await fs13.mkdir(backupPath, { recursive: true });
     if (hasYml) {
-      await fs13.copyFile(ymlPath, path12.join(backupPath, `${opts.name}.yml`));
+      await fs13.copyFile(ymlPath, path13.join(backupPath, `${opts.name}.yml`));
     }
     if (hasContainer) {
-      await fs13.cp(containerPath, path12.join(backupPath, "container"), {
+      await fs13.cp(containerPath, path13.join(backupPath, "container"), {
         recursive: true
       });
     }
@@ -5141,7 +5805,7 @@ import { consola as consola22 } from "consola";
 
 // src/restore/index.ts
 import { existsSync as existsSync9, promises as fs14 } from "fs";
-import path13 from "path";
+import path14 from "path";
 import { consola as consola21 } from "consola";
 async function runRestore(opts) {
   const home = opts.monocerosHome ?? monocerosHome();
@@ -5149,7 +5813,7 @@ async function runRestore(opts) {
     info: (msg) => consola21.info(msg),
     success: (msg) => consola21.success(msg)
   };
-  const backup = path13.resolve(opts.backupPath);
+  const backup = path14.resolve(opts.backupPath);
   if (!existsSync9(backup)) {
     throw new Error(`Backup not found: ${backup}.`);
   }
@@ -5171,7 +5835,7 @@ async function runRestore(opts) {
   }
   const ymlFile = ymlFiles[0];
   const name = ymlFile.replace(/\.yml$/, "");
-  const containerInBackup = path13.join(backup, "container");
+  const containerInBackup = path14.join(backup, "container");
   const hasContainer = existsSync9(containerInBackup);
   const destYml = containerConfigPath(name, home);
   const destContainer = containerDir(name, home);
@@ -5186,7 +5850,7 @@ async function runRestore(opts) {
     );
   }
   await fs14.mkdir(containerConfigsDir(home), { recursive: true });
-  await fs14.copyFile(path13.join(backup, ymlFile), destYml);
+  await fs14.copyFile(path14.join(backup, ymlFile), destYml);
   if (hasContainer) {
     await fs14.cp(containerInBackup, destContainer, { recursive: true });
   }
@@ -5447,7 +6111,7 @@ import { consola as consola28 } from "consola";
 
 // src/devcontainer/shell.ts
 import { existsSync as existsSync10 } from "fs";
-import path14 from "path";
+import path15 from "path";
 async function runShell(opts) {
   assertContainerExists(opts.root);
   const spawnFn = opts.spawn ?? spawnDevcontainer;
@@ -5470,7 +6134,7 @@ async function runShell(opts) {
   );
 }
 function assertContainerExists(root) {
-  if (!existsSync10(path14.join(root, ".devcontainer"))) {
+  if (!existsSync10(path15.join(root, ".devcontainer"))) {
     throw new Error(
       `No .devcontainer/ at ${root}. Run \`monoceros apply <name>\` first.`
     );