@getmonoceros/workbench 1.11.11 → 1.13.0

package/dist/bin.js

@@ -51,111 +51,23 @@ function shellQuote(arg) {
   return `'${arg.replace(/'/g, "'\\''")}'`;
 }
 
-// src/devcontainer/wsl-backend-bootstrap.ts
-import { spawnSync as spawnSync2 } from "child_process";
-
-// src/util/format.ts
-var ESC = "\x1B[";
-var ANSI_BOLD = `${ESC}1m`;
-var ANSI_UNDERLINE = `${ESC}4m`;
-var ANSI_CYAN = `${ESC}36m`;
-var ANSI_GREY = `${ESC}90m`;
-var ANSI_RESET = `${ESC}0m`;
-function makeWrap(isTty2) {
-  return (s, ...codes) => isTty2 ? codes.join("") + s + ANSI_RESET : s;
-}
-function makePalette(isTty2) {
-  const wrap = makeWrap(isTty2);
-  return {
-    bold: (s) => wrap(s, ANSI_BOLD),
-    underline: (s) => wrap(s, ANSI_UNDERLINE),
-    cyan: (s) => wrap(s, ANSI_CYAN),
-    dim: (s) => wrap(s, ANSI_GREY),
-    sectionLine: (label) => wrap(`\u25B8 ${label}`, ANSI_BOLD, ANSI_UNDERLINE)
-  };
-}
-function colorsFor(stream) {
-  return makePalette(stream.isTTY ?? false);
-}
-var stderrPalette = makePalette(process.stderr.isTTY ?? false);
-var bold = stderrPalette.bold;
-var underline = stderrPalette.underline;
-var cyan = stderrPalette.cyan;
-var dim = stderrPalette.dim;
-var sectionLine = stderrPalette.sectionLine;
-
-// src/devcontainer/wsl-backend-bootstrap.ts
-function bootstrapWslBackend(opts = {}) {
-  const platform = opts.platform ?? process.platform;
-  if (platform !== "win32") return;
-  const listDistros = opts.wslDistros ?? defaultWslDistros;
-  const raw = listDistros();
-  if (raw !== null && hasWsl2Distro(raw)) return;
-  const probe = opts.probe ?? defaultProbe2;
-  if (probe("docker", ["--version"]) !== 0) return;
-  const warn = opts.warn ?? ((m) => process.stderr.write(`${m}
-`));
-  warn(formatWslBackendHint());
-}
-function hasWsl2Distro(raw) {
-  const text = raw.split(String.fromCharCode(0)).join("");
-  for (const line of text.split(/\r?\n/)) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    if (/\bNAME\b/i.test(trimmed) && /\bVERSION\b/i.test(trimmed)) continue;
-    const tokens = trimmed.replace(/^\*\s*/, "").split(/\s+/);
-    if (tokens[tokens.length - 1] === "2") return true;
-  }
-  return false;
-}
-function formatWslBackendHint() {
-  return [
-    `Docker's daemon isn't reachable, and no WSL 2 distro is registered.`,
-    `Docker Desktop runs on the WSL 2 backend, so without a distro it`,
-    `can't start -- often shown as the misleading "Virtualization support`,
-    `not detected" (even with virtualization enabled in BIOS).`,
-    ``,
-    `Fix it in an elevated PowerShell:`,
-    ``,
-    cyan(`  wsl --set-default-version 2`),
-    cyan(`  wsl --update`),
-    cyan(`  wsl --install -d Ubuntu`),
-    ``,
-    `Then reboot and start Docker Desktop.`
-  ].join("\n");
-}
-function defaultProbe2(cmd, args) {
-  const result = spawnSync2(cmd, [...args], { stdio: "ignore", timeout: 1e4 });
-  return result.status ?? 1;
-}
-function defaultWslDistros() {
-  const result = spawnSync2("wsl", ["-l", "-v"], {
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "ignore"],
-    env: { ...process.env, WSL_UTF8: "1" },
-    timeout: 5e3
-  });
-  if (result.status !== 0 || typeof result.stdout !== "string") return null;
-  return result.stdout;
-}
-
 // src/help.ts
-var ANSI_BOLD2 = "\x1B[1m";
-var ANSI_UNDERLINE2 = "\x1B[4m";
-var ANSI_CYAN2 = "\x1B[36m";
-var ANSI_GREY2 = "\x1B[90m";
-var ANSI_RESET2 = "\x1B[0m";
+var ANSI_BOLD = "\x1B[1m";
+var ANSI_UNDERLINE = "\x1B[4m";
+var ANSI_CYAN = "\x1B[36m";
+var ANSI_GREY = "\x1B[90m";
+var ANSI_RESET = "\x1B[0m";
 function isTty() {
   return process.stdout.isTTY ?? false;
 }
 function color(text, ...codes) {
   if (!isTty()) return text;
-  return codes.join("") + text + ANSI_RESET2;
+  return codes.join("") + text + ANSI_RESET;
 }
-var bold2 = (s) => color(s, ANSI_BOLD2);
-var underline2 = (s) => color(s, ANSI_UNDERLINE2);
-var cyan2 = (s) => color(s, ANSI_CYAN2);
-var grey = (s) => color(s, ANSI_GREY2);
+var bold = (s) => color(s, ANSI_BOLD);
+var underline = (s) => color(s, ANSI_UNDERLINE);
+var cyan = (s) => color(s, ANSI_CYAN);
+var grey = (s) => color(s, ANSI_GREY);
 var GROUPS = [
   { key: "lifecycle", label: "Container lifecycle" },
   { key: "run", label: "Run + inspect" },
@@ -248,7 +160,7 @@ function collectSubCommands(cmd) {
 function renderCommandsBlock(entries) {
   if (entries.length === 0) return [];
   const lines = [];
-  lines.push(underline2(bold2("COMMANDS")));
+  lines.push(underline(bold("COMMANDS")));
   const byGroup = /* @__PURE__ */ new Map();
   for (const entry2 of entries) {
     const arr = byGroup.get(entry2.group) ?? [];
@@ -258,10 +170,10 @@ function renderCommandsBlock(entries) {
   const renderSection = (label, items) => {
     if (items.length === 0) return;
     lines.push("");
-    lines.push(underline2(grey(label)));
+    lines.push(underline(grey(label)));
     lines.push("");
     const rows = items.map((e) => [
-      cyan2(e.name),
+      cyan(e.name),
       e.description
     ]);
     lines.push(alignTable(rows, ""));
@@ -298,27 +210,27 @@ function renderUsageBlock(cmd, commandPath) {
   lines.push(grey(wrapText(header, terminalWidth(), "")));
   lines.push("");
   lines.push(
-    `${underline2(bold2("USAGE"))} ${cyan2([fullName, ...usageTokens].join(" "))}`
+    `${underline(bold("USAGE"))} ${cyan([fullName, ...usageTokens].join(" "))}`
   );
   lines.push("");
   if (positionals.length > 0) {
-    lines.push(underline2(bold2("ARGUMENTS")));
+    lines.push(underline(bold("ARGUMENTS")));
     lines.push("");
     const rows = positionals.map((p) => {
       const isRequired = p.required !== false && p.default === void 0;
-      return [cyan2(p.name.toUpperCase()), renderArgDescription(p, isRequired)];
+      return [cyan(p.name.toUpperCase()), renderArgDescription(p, isRequired)];
     });
     lines.push(alignTable(rows, "  "));
     lines.push("");
   }
   if (flags.length > 0) {
-    lines.push(underline2(bold2("OPTIONS")));
+    lines.push(underline(bold("OPTIONS")));
     lines.push("");
     const rows = flags.map((f) => {
       const isRequired = f.required === true && f.default === void 0;
       const aliases = (Array.isArray(f.alias) ? f.alias : f.alias ? [f.alias] : []).map((a) => `-${a}`);
       const label = [...aliases, `--${f.name}`].join(", ") + renderValueHint(f);
-      return [cyan2(label), renderArgDescription(f, isRequired)];
+      return [cyan(label), renderArgDescription(f, isRequired)];
     });
     lines.push(alignTable(rows, "  "));
     lines.push("");
@@ -328,7 +240,7 @@ function renderUsageBlock(cmd, commandPath) {
       lines.push(line);
     }
     lines.push(
-      `Use ${cyan2(`${fullName} <command> --help`)} for more information about a command.`
+      `Use ${cyan(`${fullName} <command> --help`)} for more information about a command.`
     );
     lines.push("");
   }
@@ -339,25 +251,25 @@ function detectHelpRequest(argv, main2) {
   const separatorIdx = argv.indexOf("--");
   if (helpIdx === -1) return null;
   if (separatorIdx !== -1 && separatorIdx < helpIdx) return null;
-  const path18 = [];
+  const path21 = [];
   const tokens = argv.slice(
     0,
     separatorIdx === -1 ? argv.length : separatorIdx
   );
   let cursor = main2;
   const mainName = (main2.meta ?? {}).name ?? "monoceros";
-  path18.push(mainName);
+  path21.push(mainName);
   for (const tok of tokens) {
     if (tok.startsWith("-")) continue;
     const subs = cursor.subCommands ?? {};
     if (tok in subs) {
       cursor = subs[tok];
-      path18.push(tok);
+      path21.push(tok);
       continue;
     }
     break;
   }
-  return { path: path18, cmd: cursor };
+  return { path: path21, cmd: cursor };
 }
 async function maybeRenderHelp(argv, main2) {
   const hit = detectHelpRequest(argv, main2);
@@ -393,13 +305,13 @@ import { defineCommand as defineCommand30 } from "citty";
 
 // src/commands/add-apt-packages.ts
 import { defineCommand } from "citty";
-import { consola as consola3 } from "consola";
+import { consola as consola2 } from "consola";
 
 // src/modify/index.ts
 import { promises as fs8 } from "fs";
-import { consola as consola2 } from "consola";
+import { consola } from "consola";
 import { createPatch } from "diff";
-import path10 from "path";
+import path9 from "path";
 
 // src/config/io.ts
 import { promises as fs } from "fs";
@@ -492,6 +404,68 @@ var RoutingSchema = z.object({
   ports: z.array(PortEntrySchema).default([]),
   vscodeAutoForward: z.boolean().optional()
 });
+var SERVICE_NAME_RE = /^[a-z0-9][a-z0-9_-]*$/;
+var ServiceEnvValueSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]).transform((v) => v === null ? "" : String(v));
+var ServiceHealthcheckSchema = z.object({
+  // Compose accepts both forms and they differ semantically:
+  //   - string         → run via the shell (CMD-SHELL)
+  //   - ["CMD", …]      → exec the args directly, no shell
+  //   - ["CMD-SHELL", …]
+  // We accept either and render it back faithfully.
+  test: z.union([
+    z.string().min(1, "Healthcheck test must not be empty."),
+    z.array(z.string().min(1)).min(1, "Healthcheck test array must not be empty.")
+  ]),
+  interval: z.string().optional(),
+  timeout: z.string().optional(),
+  retries: z.number().int().min(1).optional(),
+  startPeriod: z.string().optional()
+});
+var SERVICE_RESTART_VALUES = [
+  "no",
+  "always",
+  "on-failure",
+  "unless-stopped"
+];
+function isValidServiceVolume(spec) {
+  const parts = spec.split(":");
+  if (parts.length < 2 || parts.length > 3) return false;
+  const [src, dest, mode] = parts;
+  if (!src || !dest) return false;
+  if (!dest.startsWith("/")) return false;
+  if (mode !== void 0 && !/^(ro|rw|cached|delegated|z|Z)$/.test(mode)) {
+    return false;
+  }
+  if (src === "data") return true;
+  if (src.startsWith("/")) return false;
+  const looksLikePath = src.startsWith("./") || src.includes("/");
+  if (!looksLikePath) return false;
+  const normalized = src.startsWith("./") ? src.slice(2) : src;
+  if (normalized.split("/").some((s) => s === ".." || s === ".")) return false;
+  return true;
+}
+var ServiceObjectSchema = z.object({
+  name: z.string().regex(
+    SERVICE_NAME_RE,
+    "Invalid service name. Use lowercase letters, digits, '_' or '-' (must start with a letter or digit)."
+  ),
+  image: z.string().min(1, "Service image must not be empty."),
+  // In-container port the service listens on. Used by
+  // `monoceros tunnel <name> <service>` to forward without an explicit
+  // port argument. NOT a host port mapping — host exposure goes through
+  // routing.ports (Traefik) or `monoceros tunnel`.
+  port: z.number().int().min(1, "Port must be \u2265 1.").max(65535).optional(),
+  env: z.record(z.string(), ServiceEnvValueSchema).optional(),
+  volumes: z.array(
+    z.string().refine(
+      isValidServiceVolume,
+      "Invalid volume. Use 'data:/container/path' for the per-service persistent dir, or a relative host path ('projects/app/init.sql:/...:ro', './config:/...'). Docker named volumes (a bare name like 'rustfs_data') are not supported; absolute host paths and '..' are rejected."
+    )
+  ).optional(),
+  healthcheck: ServiceHealthcheckSchema.optional(),
+  restart: z.enum(SERVICE_RESTART_VALUES).optional(),
+  command: z.string().optional()
+});
 var ExternalServicesSchema = z.object({
   postgres: z.string().regex(
     POSTGRES_URL_RE,
@@ -518,7 +492,7 @@ var SolutionConfigSchema = z.object({
       "Invalid install URL. Must start with 'https://' and contain only URL-safe characters (no shell metacharacters)."
     )
   ).default([]),
-  services: z.array(z.string().min(1)).default([]),
+  services: z.array(ServiceObjectSchema).default([]),
   repos: z.array(RepoEntrySchema).default([]),
   routing: RoutingSchema.optional(),
   externalServices: ExternalServicesSchema.default({}),
@@ -637,6 +611,9 @@ function containerConfigsDir(home = monocerosHome()) {
 function containerConfigPath(name, home = monocerosHome()) {
   return path.join(containerConfigsDir(home), `${name}.yml`);
 }
+function containerEnvPath(name, home = monocerosHome()) {
+  return path.join(containerConfigsDir(home), `${name}.env`);
+}
 function containersDir(home = monocerosHome()) {
   return path.join(home, "container");
 }
@@ -657,813 +634,667 @@ function prettyPath(p) {
   return p;
 }
 
-// src/devcontainer/credentials.ts
-import { spawn } from "child_process";
-import { promises as fs2 } from "fs";
+// src/config/env-file.ts
+import { existsSync as existsSync2, readFileSync, promises as fsp } from "fs";
 import path2 from "path";
-var realGitCredentialFill = (input) => {
-  return new Promise((resolve, reject) => {
-    const child = spawn("git", ["credential", "fill"], {
-      stdio: ["pipe", "pipe", "inherit"],
-      env: {
-        ...process.env,
-        GIT_TERMINAL_PROMPT: "0"
-      }
-    });
-    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();
-  });
-};
-var realGitCredentialApprove = (input) => {
-  return new Promise((resolve, reject) => {
-    const child = spawn("git", ["credential", "approve"], {
-      stdio: ["pipe", "ignore", "inherit"],
-      env: {
-        ...process.env,
-        GIT_TERMINAL_PROMPT: "0"
-      }
-    });
-    child.on("error", reject);
-    child.on("exit", () => resolve());
-    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) });
+var ENV_LINE_RE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/;
+function parseEnvFile(content) {
+  const out = {};
+  for (const raw of content.split(/\r?\n/)) {
+    const trimmed = raw.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const m = ENV_LINE_RE.exec(raw);
+    if (!m) continue;
+    const key = m[1];
+    let val = m[2].trim();
+    if (val.length >= 2 && (val.startsWith('"') && val.endsWith('"') || val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    out[key] = val;
   }
-  return [...byHost.values()];
+  return out;
 }
-var BREW_INSTALL_COMMAND = '/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"';
-function installCommandForOS(opts) {
-  const withBrewBootstrap = (cmd) => [
-    "",
-    cyan(BREW_INSTALL_COMMAND),
-    cyan(cmd),
-    "",
-    dim("(Skip the first line if you already have Homebrew.)")
-  ].join("\n");
-  switch (process.platform) {
-    case "darwin":
-      return withBrewBootstrap(opts.brew);
-    case "win32":
-      return ["", cyan(opts.winget)].join("\n");
-    default:
-      if (opts.linuxBrew) return withBrewBootstrap(opts.linuxBrew);
-      return `See ${opts.linuxDocsUrl} for package instructions.`;
-  }
+function readEnvFile(envPath) {
+  if (!existsSync2(envPath)) return {};
+  return parseEnvFile(readFileSync(envPath, "utf8"));
+}
+async function ensureEnvGitignored(configsDir) {
+  const gitignorePath = path2.join(configsDir, ".gitignore");
+  const pattern = "*.env";
+  let existing = "";
+  if (existsSync2(gitignorePath)) {
+    existing = readFileSync(gitignorePath, "utf8");
+    const lines = existing.split(/\r?\n/).map((l) => l.trim());
+    if (lines.includes(pattern)) return;
+  }
+  const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+  const header = existing.length === 0 ? "# Per-container env files hold the secrets behind the yml ${VAR}\n# references. Never commit them.\n" : "";
+  await fsp.appendFile(gitignorePath, `${prefix}${header}${pattern}
+`);
 }
-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:",
-        cyan(`gh auth login${hostArg}`),
-        cyan(`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")
+var VAR_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+function interpolate(value, vars) {
+  const missing = [];
+  const out = value.replace(VAR_RE, (_match, name) => {
+    if (Object.prototype.hasOwnProperty.call(vars, name)) return vars[name];
+    missing.push(name);
+    return _match;
+  });
+  return { value: out, missing };
+}
+function interpolateServices(services, vars) {
+  const missing = [];
+  const resolved = services.map((svc) => {
+    const interp = (raw, field) => {
+      const r = interpolate(raw, vars);
+      for (const name of r.missing) {
+        missing.push({ location: `services.${svc.name}.${field}`, name });
+      }
+      return r.value;
     };
-  }
-  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:",
-        cyan(`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")
+    const next = {
+      ...svc,
+      image: interp(svc.image, "image"),
+      env: Object.fromEntries(
+        Object.entries(svc.env).map(([k, v]) => [k, interp(v, `env.${k}`)])
+      ),
+      volumes: svc.volumes.map((v, i) => interp(v, `volumes[${i}]`))
     };
-  }
-  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:",
-          cyan(
-            `git credential approve <<< $'protocol=https\\nhost=${host}\\nusername=<your-atlassian-email>\\npassword=<token>\\n'`
-          )
-        ].join("\n")
+    if (svc.command !== void 0) {
+      next.command = interp(svc.command, "command");
+    }
+    if (svc.healthcheck) {
+      const hc = svc.healthcheck;
+      next.healthcheck = {
+        ...hc,
+        test: Array.isArray(hc.test) ? hc.test.map((t, i) => interp(t, `healthcheck.test[${i}]`)) : interp(hc.test, "healthcheck.test"),
+        ...hc.interval !== void 0 ? { interval: interp(hc.interval, "healthcheck.interval") } : {},
+        ...hc.timeout !== void 0 ? { timeout: interp(hc.timeout, "healthcheck.timeout") } : {},
+        ...hc.startPeriod !== void 0 ? { startPeriod: interp(hc.startPeriod, "healthcheck.startPeriod") } : {}
       };
     }
-    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:",
-        cyan(
-          `git credential approve <<< $'protocol=https\\nhost=${host}\\nusername=<your-bitbucket-username>\\npassword=<token>\\n'`
-        )
-      ].join("\n")
-    };
+    return next;
+  });
+  return { services: resolved, missing };
+}
+function interpolateFeatures(features, vars) {
+  const missing = [];
+  const out = {};
+  for (const [ref, options] of Object.entries(features)) {
+    const next = {};
+    for (const [key, value] of Object.entries(options)) {
+      if (typeof value !== "string") {
+        next[key] = value;
+        continue;
+      }
+      const r = interpolate(value, vars);
+      for (const name of r.missing) {
+        missing.push({ location: `features.${ref}.${key}`, name });
+      }
+      next[key] = r.value;
+    }
+    out[ref] = next;
   }
-  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:",
-      cyan(
-        `git credential approve <<< $'protocol=https\\nhost=${host}\\nusername=<your-gitea-username>\\npassword=<token>\\n'`
-      )
-    ].join("\n")
-  };
+  return { features: out, missing };
 }
-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;
+function buildEnvStub(name) {
+  return `# Secrets and values for \${VAR} references in ${name}.yml.
+`;
+}
+async function ensureEnvVars(envPath, name, vars) {
+  const exists = existsSync2(envPath);
+  let content = exists ? readFileSync(envPath, "utf8") : buildEnvStub(name);
+  const present = new Set(Object.keys(parseEnvFile(content)));
+  const added = [...new Set(vars)].filter((v) => !present.has(v));
+  if (!exists || added.length > 0) {
+    if (content.length > 0 && !content.endsWith("\n")) content += "\n";
+    for (const v of added) content += `${v}=
+`;
+    await fsp.mkdir(path2.dirname(envPath), { recursive: true });
+    await fsp.writeFile(envPath, content);
   }
-  return result;
+  return { created: !exists, added };
 }
-function formatCredentialLine(host, username, password) {
-  const encUser = encodeURIComponent(username);
-  const encPass = encodeURIComponent(password);
-  return `https://${encUser}:${encPass}@${host}`;
+function formatMissingVarsError(missing, envPathPretty) {
+  const lines = missing.map((m) => `  - \${${m.name}} (${m.location})`);
+  const uniqueNames = [...new Set(missing.map((m) => m.name))];
+  return `Unresolved \${VAR} references in the container yml:
+${lines.join("\n")}
+
+Define them in ${envPathPretty}, e.g.
+` + uniqueNames.map((n) => `  ${n}=<value>`).join("\n");
 }
-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 approveFn = options.approve ?? realGitCredentialApprove;
-  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: "" });
-    const approveInput = `protocol=https
-host=${host}
-username=${username}
-password=${password}
-
-`;
-    try {
-      await approveFn(approveInput);
-    } catch {
-    }
-  }
-  await fs2.mkdir(credsDir, { recursive: true });
-  await fs2.writeFile(
-    credentialsPath,
-    lines.join("\n") + (lines.length > 0 ? "\n" : ""),
-    {
-      mode: 384
+// src/init/feature-doc.ts
+function buildFeatureHeaderLines(summary, width) {
+  const paragraphs = buildHeaderParagraphs(summary);
+  const wrapped = [];
+  for (const para of paragraphs) {
+    for (const line of wrapToComment(para, width)) {
+      wrapped.push(line);
     }
-  );
-  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 ${cyan("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 ${cyan("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:",
-    "",
-    cyan("  repos:"),
-    cyan(`    - url: https://${sorted[0]}/\u2026`),
-    cyan("      provider: gitlab   # or: github, bitbucket, gitea"),
-    "",
-    `Or re-add with ${cyan("monoceros add-repo <name> <url> --provider=<github|gitlab|bitbucket|gitea>")}.`
-  ];
-  return lines.join("\n");
-}
-
-// src/devcontainer/locate-running.ts
-import { spawn as spawn5 } from "child_process";
-
-// src/devcontainer/compose.ts
-import { spawn as spawn4 } from "child_process";
-import { existsSync as existsSync2 } from "fs";
-import path5 from "path";
-import { consola } from "consola";
-
-// src/proxy/index.ts
-import { spawn as spawn2 } from "child_process";
-import { promises as fs3 } 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 = 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 })
-    );
-  });
-};
-var realDocker = defaultDockerExec;
-function proxyDynamicDir(home) {
-  return path3.join(home ?? monocerosHome(), "traefik", "dynamic");
+  return wrapped;
 }
-async function kickProxyReload(opts = {}) {
-  if (process.platform !== "win32") return;
-  const docker = opts.docker ?? realDocker;
-  const inspect = await docker([
-    "inspect",
-    "--format",
-    "{{.State.Running}}",
-    PROXY_CONTAINER_NAME
-  ]);
-  if (inspect.exitCode !== 0) return;
-  if (inspect.stdout.trim() !== "true") return;
-  await docker(["restart", PROXY_CONTAINER_NAME]);
+function buildFeatureHeaderCommentBefore(summary, width) {
+  const lines = buildFeatureHeaderLines(summary, width);
+  return lines.map((l) => ` ${l}`).join("\n");
 }
-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}`}`
-      );
-    }
-    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}`}`
-    );
+function buildHeaderParagraphs(summary) {
+  if (!summary) return [];
+  const 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);
   }
-  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;
+  for (const note of summary.usageNotes) {
+    const trimmed = note.trim();
+    if (trimmed.length > 0) out.push(trimmed);
   }
-  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 (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(", ")}.`);
   }
-  logger?.info(
-    `Stopped ${PROXY_CONTAINER_NAME} (no dev-containers with ports left).`
-  );
-}
-
-// 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);
+  if (summary.documentationURL) {
+    out.push(`See ${summary.documentationURL} for further information.`);
   }
-  return result;
+  return out;
 }
-function maskOne(token) {
-  if (token.length <= 12) return token;
-  return `${token.slice(0, 5)}\u2026${token.slice(-6)}`;
+function shortenOptionDescription(desc) {
+  const firstSentence = desc.split(/(?<=[.!?])\s+/)[0]?.trim() ?? desc.trim();
+  return firstSentence.replace(/[.!?]+$/, "").trim();
 }
-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);
+function wrapToComment(text, width) {
+  const words = text.split(/\s+/).filter((w) => w.length > 0);
+  if (words.length === 0) return [""];
+  const usable = Math.max(width, 20);
+  const lines = [];
+  let current = "";
+  for (const w of words) {
+    if (current.length === 0) {
+      current = w;
+      continue;
+    }
+    if (current.length + 1 + w.length <= usable) {
+      current += " " + w;
+    } else {
+      lines.push(current);
+      current = w;
     }
+  }
+  if (current.length > 0) lines.push(current);
+  return lines;
+}
+var FEATURE_HEADER_WIDTH = 76 - 2;
+function featureOptionVarName(ref, optionKey) {
+  const leaf = ref.split("/").pop() ?? ref;
+  const id = leaf.split("@")[0].split(":")[0];
+  const idSnake = id.replace(/[^A-Za-z0-9]+/g, "_").toUpperCase();
+  const optSnake = optionKey.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[^A-Za-z0-9]+/g, "_").toUpperCase();
+  return `${idSnake}_${optSnake}`;
+}
+function featureOptionHints(summary, ref, activeKeys = []) {
+  return (summary?.optionHints ?? []).filter((key) => !activeKeys.includes(key)).map((key) => {
+    const envVar = featureOptionVarName(ref, key);
+    return { key, envVar, placeholder: `\${${envVar}}` };
   });
 }
 
-// src/devcontainer/cli.ts
-import { spawn as spawn3 } from "child_process";
-import { readFileSync } from "fs";
-import { createRequire } from "module";
-import path4 from "path";
+// src/init/manifest.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+import path3 from "path";
 
-// src/devcontainer/runtime-pull-hint.ts
-import { Transform as Transform2 } from "stream";
-var RUNTIME_PULL_MARKER = "No manifest found for ghcr.io/getmonoceros/monoceros-runtime";
-var RUNTIME_PULL_HINT = 'Downloading the Monoceros runtime image now -- expected on first apply, takes ~1-2 min (Docker pulls the multi-arch base with no progress output). The "No manifest found" line above is harmless. Please wait...';
-function createRuntimePullHintStream(state) {
-  let buffer = "";
-  const appendHintIfMarker = (block) => {
-    if (state.hinted || !block.includes(RUNTIME_PULL_MARKER)) return block;
-    state.hinted = true;
-    return `${block}${dim(`(i) ${RUNTIME_PULL_HINT}`)}
-`;
-  };
-  return new Transform2({
-    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, appendHintIfMarker(flushable));
-    },
-    flush(cb) {
-      if (buffer.length === 0) {
-        cb(null);
-        return;
-      }
-      const tail = buffer;
-      buffer = "";
-      cb(null, appendHintIfMarker(tail));
-    }
-  });
+// src/util/ref.ts
+var FEATURE_NAME_CHARSET = "[a-z0-9._-]+";
+var FEATURE_TAG_CHARSET = "[a-z0-9._-]+";
+var MONOCEROS_FEATURE_RE = new RegExp(
+  `^ghcr\\.io/getmonoceros/monoceros-features/(${FEATURE_NAME_CHARSET}):${FEATURE_TAG_CHARSET}$`
+);
+var DEPRECATED_MONOCEROS_FEATURE_RE = new RegExp(
+  `^ghcr\\.io/monoceros/features/(${FEATURE_NAME_CHARSET}):(${FEATURE_TAG_CHARSET})$`
+);
+function matchMonocerosFeature(ref) {
+  const match = MONOCEROS_FEATURE_RE.exec(ref);
+  if (!match) return null;
+  return { name: match[1] };
+}
+function migrateDeprecatedFeatureRef(ref) {
+  const match = DEPRECATED_MONOCEROS_FEATURE_RE.exec(ref);
+  if (!match) return null;
+  const name = match[1];
+  const tag = match[2];
+  return `ghcr.io/getmonoceros/monoceros-features/${name}:${tag}`;
 }
 
-// src/devcontainer/cli.ts
-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(readFileSync(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.");
+// src/init/manifest.ts
+function resolveManifestPath(name, checkoutRoot) {
+  if (checkoutRoot) {
+    const checkoutPath = path3.join(
+      checkoutRoot,
+      "images",
+      "features",
+      name,
+      "devcontainer-feature.json"
+    );
+    if (existsSync3(checkoutPath)) return checkoutPath;
   }
-  cachedBinaryPath = path4.resolve(path4.dirname(pkgJsonPath), binEntry);
-  return cachedBinaryPath;
+  const bundlePath = path3.join(
+    bundledFeaturesDir(),
+    name,
+    "devcontainer-feature.json"
+  );
+  if (existsSync3(bundlePath)) return bundlePath;
+  return null;
 }
-var spawnDevcontainer = (args, cwd, options = {}) => {
-  const binPath = devcontainerCliPath();
-  return new Promise((resolve, reject) => {
-    if (options.interactive) {
-      const child2 = spawn3(process.execPath, [binPath, ...args], {
-        cwd,
-        stdio: "inherit"
-      });
-      child2.on("error", reject);
-      child2.on("exit", (code) => resolve(code ?? 0));
-      return;
-    }
-    const child = spawn3(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"))
-          );
+function loadFeatureManifestSummary(ref, checkoutRoot = workbenchCheckoutRoot()) {
+  const match = matchMonocerosFeature(ref);
+  if (!match) return void 0;
+  const manifestPath = resolveManifestPath(match.name, checkoutRoot);
+  if (!manifestPath) return void 0;
+  try {
+    const text = readFileSync2(manifestPath, "utf8");
+    const parsed = JSON.parse(text);
+    const rawHints = parsed["x-monoceros"]?.optionHints;
+    const optionHints = Array.isArray(rawHints) ? rawHints.filter(
+      (x) => typeof x === "string" && x.length > 0
+    ) : [];
+    const rawNotes = parsed["x-monoceros"]?.usageNotes;
+    const usageNotes = Array.isArray(rawNotes) ? rawNotes.filter(
+      (x) => typeof x === "string" && x.length > 0
+    ) : [];
+    const optionDescriptions = {};
+    const optionTypes = {};
+    const optionNames = [];
+    if (parsed.options) {
+      for (const [key, opt] of Object.entries(parsed.options)) {
+        if (!opt || typeof opt !== "object") continue;
+        optionNames.push(key);
+        if (typeof opt.description === "string" && opt.description.length > 0) {
+          optionDescriptions[key] = opt.description;
         }
-        resolve(exitCode);
-      });
-      return;
+        if (opt.type === "boolean") {
+          optionTypes[key] = "boolean";
+        } else if (opt.type === "string") {
+          optionTypes[key] = "string";
+        }
+      }
     }
-    const pullHint = { hinted: false };
-    child.stdout?.pipe(createSecretMaskStream()).pipe(createRuntimePullHintStream(pullHint)).pipe(process.stdout);
-    child.stderr?.pipe(createSecretMaskStream()).pipe(createRuntimePullHintStream(pullHint)).pipe(process.stderr);
-    child.on("error", reject);
-    child.on("exit", (code) => resolve(code ?? 0));
-  });
-};
+    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,
+      optionNames,
+      optionTypes,
+      usageNotes
+    };
+  } catch {
+    return void 0;
+  }
+}
 
-// src/devcontainer/compose.ts
-var spawnDockerCompose = (args, cwd) => {
+// src/devcontainer/credentials.ts
+import { spawn } from "child_process";
+import { promises as fs2 } from "fs";
+import path4 from "path";
+
+// 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/credentials.ts
+var realGitCredentialFill = (input) => {
   return new Promise((resolve, reject) => {
-    const child = spawn4("docker", ["compose", ...args], {
-      cwd,
-      stdio: ["inherit", "pipe", "pipe"]
+    const child = spawn("git", ["credential", "fill"], {
+      stdio: ["pipe", "pipe", "inherit"],
+      env: {
+        ...process.env,
+        GIT_TERMINAL_PROMPT: "0"
+      }
+    });
+    let stdout = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
     });
-    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));
+    child.on("exit", (code) => resolve({ stdout, exitCode: code ?? 0 }));
+    child.stdin.write(input);
+    child.stdin.end();
   });
 };
-var spawnDocker = (args) => {
+var realGitCredentialApprove = (input) => {
   return new Promise((resolve, reject) => {
-    const child = spawn4("docker", args, {
-      stdio: ["ignore", "pipe", "pipe"]
-    });
-    let stdout = "";
-    let stderr = "";
-    child.stdout?.on("data", (chunk) => {
-      stdout += chunk.toString("utf8");
-    });
-    child.stderr?.on("data", (chunk) => {
-      stderr += chunk.toString("utf8");
+    const child = spawn("git", ["credential", "approve"], {
+      stdio: ["pipe", "ignore", "inherit"],
+      env: {
+        ...process.env,
+        GIT_TERMINAL_PROMPT: "0"
+      }
     });
     child.on("error", reject);
-    child.on(
-      "exit",
-      (code) => resolve({ exitCode: code ?? 0, stdout, stderr })
-    );
+    child.on("exit", () => resolve());
+    child.stdin.write(input);
+    child.stdin.end();
   });
 };
-async function findContainerIds(filters, exec = spawnDocker) {
-  const ids = /* @__PURE__ */ new Set();
-  for (const filter of filters) {
-    const result = await exec(["ps", "-aq", "--filter", filter]);
-    if (result.exitCode !== 0) continue;
-    for (const line of result.stdout.split(/\r?\n/)) {
-      const id = line.trim();
-      if (id) ids.add(id);
+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) });
   }
-  return [...ids];
+  return [...byHost.values()];
 }
-async function cleanupDockerObjects(opts) {
-  const exec = opts.exec ?? spawnDocker;
-  const tag = opts.logTag ?? "cleanup";
-  opts.logger.info(`[${tag}] tearing down docker project ${opts.projectName}\u2026`);
-  const ids = await findContainerIds(opts.filters, exec);
-  let rmExit = 0;
-  if (ids.length > 0) {
-    opts.logger.info(`[${tag}] removing containers: ${ids.join(" ")}`);
-    const rmResult = await exec(["rm", "-f", ...ids]);
-    rmExit = rmResult.exitCode;
-    if (rmExit !== 0 && rmResult.stderr.trim()) {
-      opts.logger.info(`[${tag}] ${rmResult.stderr.trim()}`);
+var BREW_INSTALL_COMMAND = '/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"';
+function installCommandForOS(opts) {
+  const withBrewBootstrap = (cmd) => [
+    "",
+    cyan2(BREW_INSTALL_COMMAND),
+    cyan2(cmd),
+    "",
+    dim("(Skip the first line if you already have Homebrew.)")
+  ].join("\n");
+  if (process.platform === "darwin") return withBrewBootstrap(opts.brew);
+  if (opts.linuxBrew) return withBrewBootstrap(opts.linuxBrew);
+  return `See ${opts.linuxDocsUrl} for package instructions.`;
+}
+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",
+      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",
+      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")
+      };
     }
-  } else {
-    opts.logger.info(`[${tag}] no containers found`);
+    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")
+    };
   }
-  if (opts.network) {
-    const netResult = await exec(["network", "rm", opts.network]);
-    if (netResult.exitCode === 0) {
-      opts.logger.info(`[${tag}] network ${opts.network} removed`);
+  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 = path4.join(devContainerRoot, ".monoceros");
+  const credentialsPath = path4.join(credsDir, "git-credentials");
+  const spawnFn = options.spawn ?? realGitCredentialFill;
+  const approveFn = options.approve ?? realGitCredentialApprove;
+  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: "" });
+    const approveInput = `protocol=https
+host=${host}
+username=${username}
+password=${password}
+
+`;
+    try {
+      await approveFn(approveInput);
+    } catch {
     }
   }
-  opts.logger.info(`[${tag}] docker cleanup done`);
-  return { exitCode: rmExit, removedIds: ids };
-}
-function dockerLocalFolderLabel(p) {
-  if (process.platform !== "win32") return p;
-  return p.replace(
-    /^([A-Z]):/,
-    (_, drive) => `${drive.toLowerCase()}:`
+  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 composeProjectName(root) {
-  return `${path5.basename(root)}_devcontainer`;
-}
-function resolveCompose(root) {
-  if (!existsSync2(path5.join(root, ".devcontainer"))) {
-    throw new Error(
-      `No .devcontainer/ at ${root}. Run \`monoceros apply <name>\` first.`
-    );
-  }
-  const composeFile = path5.join(root, ".devcontainer", "compose.yaml");
-  if (!existsSync2(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.`
-    );
+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");
   }
-  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) => consola.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 exec = opts.dockerExec ?? spawnDocker;
-    const filters = [
-      `label=com.docker.compose.project=${projectName}`,
-      `name=^${projectName}-`
-    ];
-    const { exitCode: rmExit } = await cleanupDockerObjects({
-      projectName,
-      filters,
-      network: `${projectName}_default`,
-      logger,
-      exec
-    });
-    if (rmExit !== 0) return rmExit;
-    const remaining = await findContainerIds(filters, exec);
-    if (remaining.length > 0) {
-      const warn = logger.warn ?? logger.info;
-      warn(
-        `ERROR: containers under project ${projectName} reappeared after removal.
-This typically means VS Code's Remote Containers extension is connected
-to this devcontainer and auto-recreated it. Close the dev container
-session in VS Code (Cmd+Shift+P \u2192 'Dev Containers: Close Remote Connection')
-and retry \`monoceros apply\`.`
-      );
-      return 1;
-    }
-    return runStart({
-      root,
-      ...opts.devcontainerSpawn ? { spawn: opts.devcontainerSpawn } : {},
-      logger
-    });
+  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("");
   }
-  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
-  );
-}
-function runStop(opts) {
-  return runComposeAction(
-    (service) => ["stop", ...service ? [service] : []],
-    opts
-  );
-}
-function runStatus(opts) {
-  return runComposeAction(
-    (service) => ["ps", ...service ? [service] : []],
-    opts
-  );
+  lines.push(`Then re-run ${cyan2("monoceros apply")}.`);
+  return lines.join("\n");
 }
-function runLogs(opts) {
-  const follow = opts.follow ?? true;
-  return runComposeAction(
-    (service) => [
-      "logs",
-      ...follow ? ["-f"] : [],
-      ...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");
 }
 
 // src/devcontainer/locate-running.ts
+import { spawn as spawn2 } from "child_process";
 var realDockerLookup = (args) => {
   return new Promise((resolve, reject) => {
-    const child = spawn5("docker", args, {
+    const child = spawn2("docker", args, {
       stdio: ["ignore", "pipe", "pipe"]
     });
     let stdout = "";
@@ -1487,7 +1318,7 @@ async function findRunningContainerByLocalFolder(containerPath, opts = {}) {
     "ps",
     "-q",
     "--filter",
-    `label=devcontainer.local_folder=${dockerLocalFolderLabel(containerPath)}`,
+    `label=devcontainer.local_folder=${containerPath}`,
     "--filter",
     "status=running"
   ]);
@@ -1497,7 +1328,7 @@ async function findRunningContainerByLocalFolder(containerPath, opts = {}) {
 }
 var realContainerExec = (containerId, argv) => {
   return new Promise((resolve, reject) => {
-    const child = spawn5("docker", ["exec", containerId, ...argv], {
+    const child = spawn2("docker", ["exec", containerId, ...argv], {
       // Inherit stdio so live git output reaches the user.
       stdio: ["ignore", "inherit", "inherit"]
     });
@@ -1507,7 +1338,7 @@ var realContainerExec = (containerId, argv) => {
 };
 
 // src/config/global.ts
-import { promises as fs4 } from "fs";
+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;
@@ -1550,7 +1381,7 @@ async function readMonocerosConfig(opts = {}) {
   const filePath = monocerosConfigPath(home);
   let text;
   try {
-    text = await fs4.readFile(filePath, "utf8");
+    text = await fs3.readFile(filePath, "utf8");
   } catch {
     return void 0;
   }
@@ -1587,7 +1418,7 @@ async function writeGlobalDefaultGitUser(user, opts = {}) {
   const filePath = monocerosConfigPath(home);
   let text;
   try {
-    text = await fs4.readFile(filePath, "utf8");
+    text = await fs3.readFile(filePath, "utf8");
   } catch {
     text = void 0;
   }
@@ -1604,8 +1435,8 @@ async function writeGlobalDefaultGitUser(user, opts = {}) {
       `      email: ${user.email}`,
       ""
     ].join("\n");
-    await fs4.mkdir(home, { recursive: true });
-    await fs4.writeFile(filePath, fresh, "utf8");
+    await fs3.mkdir(home, { recursive: true });
+    await fs3.writeFile(filePath, fresh, "utf8");
     return { filePath, created: true, alreadySet: false };
   }
   const doc = parseDocument2(text, { prettyErrors: true });
@@ -1626,7 +1457,7 @@ async function writeGlobalDefaultGitUser(user, opts = {}) {
   userMap.set("name", user.name);
   userMap.set("email", user.email);
   const newText = String(doc);
-  await fs4.writeFile(filePath, newText, "utf8");
+  await fs3.writeFile(filePath, newText, "utf8");
   return { filePath, created: false, alreadySet: false };
 }
 function ensureMap(doc, key) {
@@ -1733,8 +1564,8 @@ ${existing}` : leakedComment;
 }
 
 // src/init/components.ts
-import { existsSync as existsSync3, promises as fs5 } from "fs";
-import path6 from "path";
+import { existsSync as existsSync4, promises as fs4 } from "fs";
+import path5 from "path";
 import { z as z3 } from "zod";
 import { parse as parseYaml } from "yaml";
 var CategorySchema = z3.enum(["language", "service", "feature"]);
@@ -1781,7 +1612,7 @@ var ComponentFileSchema = z3.object({
   }
 });
 async function loadComponentCatalog(rootDir = componentsDir()) {
-  if (!existsSync3(rootDir)) {
+  if (!existsSync4(rootDir)) {
     return /* @__PURE__ */ new Map();
   }
   const out = /* @__PURE__ */ new Map();
@@ -1789,17 +1620,17 @@ async function loadComponentCatalog(rootDir = componentsDir()) {
   return out;
 }
 async function walk(baseDir, currentDir, out) {
-  const entries = await fs5.readdir(currentDir, { withFileTypes: true });
+  const entries = await fs4.readdir(currentDir, { withFileTypes: true });
   for (const entry2 of entries) {
-    const full = path6.join(currentDir, entry2.name);
+    const full = path5.join(currentDir, entry2.name);
     if (entry2.isDirectory()) {
       await walk(baseDir, full, out);
       continue;
     }
     if (!entry2.isFile() || !entry2.name.endsWith(".yml")) continue;
-    const relative = path6.relative(baseDir, full);
-    const name = relative.replace(/\.yml$/, "").split(path6.sep).join("/");
-    const text = await fs5.readFile(full, "utf8");
+    const relative = path5.relative(baseDir, full);
+    const name = relative.replace(/\.yml$/, "").split(path5.sep).join("/");
+    const text = await fs4.readFile(full, "utf8");
     let raw;
     try {
       raw = parseYaml(text);
@@ -1820,42 +1651,6 @@ ${issues}`);
     out.set(name, { name, sourcePath: full, file: parsed.data });
   }
 }
-function mergeComponents(resolved) {
-  const languages = [];
-  const services = [];
-  const featureByRef = /* @__PURE__ */ new Map();
-  for (const entry2 of resolved) {
-    const c = isResolvedComponent(entry2) ? entry2.component : entry2;
-    const version = isResolvedComponent(entry2) ? entry2.version : void 0;
-    const ct = c.file.contributes;
-    for (const lang of ct.languages ?? []) {
-      const value = version !== void 0 ? `${lang}:${version}` : lang;
-      if (!languages.includes(value)) languages.push(value);
-    }
-    for (const svc of ct.services ?? []) {
-      if (!services.includes(svc)) services.push(svc);
-    }
-    for (const f of ct.features ?? []) {
-      const existing = featureByRef.get(f.ref);
-      if (!existing) {
-        featureByRef.set(f.ref, {
-          ref: f.ref,
-          options: { ...f.options ?? {} }
-        });
-        continue;
-      }
-      existing.options = mergeFeatureOptions(existing.options, f.options ?? {});
-    }
-  }
-  return {
-    languages,
-    services,
-    features: [...featureByRef.values()]
-  };
-}
-function isResolvedComponent(x) {
-  return "component" in x;
-}
 function mergeFeatureOptions(a, b) {
   const result = { ...a };
   for (const [key, valueB] of Object.entries(b)) {
@@ -1868,33 +1663,124 @@ function mergeFeatureOptions(a, b) {
   }
   return result;
 }
-function resolveComponents(catalog, names) {
-  const unknown = [];
-  const out = [];
-  for (const raw of names) {
-    const colon = raw.indexOf(":");
-    const name = colon === -1 ? raw : raw.slice(0, colon);
-    const version = colon === -1 ? void 0 : raw.slice(colon + 1);
-    const c = catalog.get(name);
-    if (!c) {
-      unknown.push(raw);
-      continue;
+
+// src/proxy/index.ts
+import { spawn as spawn3 } from "child_process";
+import { promises as fs5 } from "fs";
+import path6 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 path6.join(home ?? monocerosHome(), "traefik", "dynamic");
+}
+async function ensureProxy(opts = {}) {
+  const docker = opts.docker ?? realDocker;
+  const dyn = proxyDynamicDir(opts.monocerosHome);
+  await fs5.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}`}`
+      );
     }
-    if (version !== void 0 && c.file.category !== "language") {
+  }
+  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(
-        `Component '${name}' is a ${c.file.category}, not a language \u2014 a ':${version}' suffix has no meaning here.`
+        `Could not start existing ${PROXY_CONTAINER_NAME} container: ${start.stderr.trim() || `exit ${start.exitCode}`}`
       );
     }
-    out.push({ component: c, ...version !== void 0 ? { version } : {} });
+    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;
   }
-  if (unknown.length > 0) {
-    const available = [...catalog.keys()].sort();
-    throw new Error(
-      `Unknown component${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}.
-Available: ${available.join(", ")}.`
+  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;
   }
-  return out;
+  logger?.info(
+    `Stopped ${PROXY_CONTAINER_NAME} (no dev-containers with ports left).`
+  );
 }
 
 // src/proxy/dynamic.ts
@@ -2116,34 +2002,97 @@ function knownLanguages() {
 function knownServices() {
   return Object.keys(SERVICE_CATALOG).sort();
 }
+function resolveService(entry2) {
+  return {
+    name: entry2.name,
+    image: entry2.image,
+    ...entry2.port !== void 0 ? { port: entry2.port } : {},
+    env: entry2.env ? { ...entry2.env } : {},
+    volumes: entry2.volumes ? [...entry2.volumes] : [],
+    ...entry2.healthcheck ? { healthcheck: entry2.healthcheck } : {},
+    ...entry2.restart ? { restart: entry2.restart } : {},
+    ...entry2.command ? { command: entry2.command } : {}
+  };
+}
+function isCuratedService(name) {
+  return Object.prototype.hasOwnProperty.call(SERVICE_CATALOG, name);
+}
+function expandCuratedService(name) {
+  const def = SERVICE_CATALOG[name];
+  if (!def) {
+    throw new Error(
+      `Unknown service '${name}'. Known catalog services: ${knownServices().join(", ")}.`
+    );
+  }
+  return {
+    name: def.id,
+    image: def.image,
+    port: def.defaultPort,
+    ...def.env ? { env: { ...def.env } } : {},
+    ...def.dataMount ? { volumes: [`data:${def.dataMount}`] } : {}
+  };
+}
+function deriveServiceName(image) {
+  const lastSegment = image.split("/").pop() ?? image;
+  const noTag = lastSegment.split("@")[0].split(":")[0];
+  return noTag.toLowerCase().replace(/[^a-z0-9_-]/g, "-");
+}
 
-// src/create/scaffold.ts
-import { existsSync as existsSync4, readFileSync as readFileSync2, promises as fs7 } from "fs";
-import path8 from "path";
-
-// src/util/ref.ts
-var FEATURE_NAME_CHARSET = "[a-z0-9._-]+";
-var FEATURE_TAG_CHARSET = "[a-z0-9._-]+";
-var MONOCEROS_FEATURE_RE = new RegExp(
-  `^ghcr\\.io/getmonoceros/monoceros-features/(${FEATURE_NAME_CHARSET}):${FEATURE_TAG_CHARSET}$`
-);
-var DEPRECATED_MONOCEROS_FEATURE_RE = new RegExp(
-  `^ghcr\\.io/monoceros/features/(${FEATURE_NAME_CHARSET}):(${FEATURE_TAG_CHARSET})$`
-);
-function matchMonocerosFeature(ref) {
-  const match = MONOCEROS_FEATURE_RE.exec(ref);
-  if (!match) return null;
-  return { name: match[1] };
+// src/init/service-doc.ts
+function renderServiceObjectBody(svc) {
+  const lines = [`name: ${svc.name}`, `image: ${svc.image}`];
+  if (svc.port !== void 0) lines.push(`port: ${svc.port}`);
+  if (svc.env && Object.keys(svc.env).length > 0) {
+    lines.push("env:");
+    for (const [k, v] of Object.entries(svc.env)) {
+      lines.push(`  ${k}: ${v}`);
+    }
+  }
+  if (svc.volumes && svc.volumes.length > 0) {
+    lines.push("volumes:");
+    for (const vol of svc.volumes) lines.push(`  - ${vol}`);
+  }
+  if (svc.restart) lines.push(`restart: ${svc.restart}`);
+  if (svc.command !== void 0) lines.push(`command: ${svc.command}`);
+  if (svc.healthcheck) {
+    lines.push("healthcheck:");
+    const test = svc.healthcheck.test;
+    lines.push(
+      Array.isArray(test) ? `  test: [${test.map((t) => JSON.stringify(t)).join(", ")}]` : `  test: ${test}`
+    );
+    if (svc.healthcheck.interval)
+      lines.push(`  interval: ${svc.healthcheck.interval}`);
+    if (svc.healthcheck.timeout)
+      lines.push(`  timeout: ${svc.healthcheck.timeout}`);
+    if (svc.healthcheck.retries !== void 0)
+      lines.push(`  retries: ${svc.healthcheck.retries}`);
+    if (svc.healthcheck.startPeriod)
+      lines.push(`  startPeriod: ${svc.healthcheck.startPeriod}`);
+  }
+  return lines;
 }
-function migrateDeprecatedFeatureRef(ref) {
-  const match = DEPRECATED_MONOCEROS_FEATURE_RE.exec(ref);
-  if (!match) return null;
-  const name = match[1];
-  const tag = match[2];
-  return `ghcr.io/getmonoceros/monoceros-features/${name}:${tag}`;
+function renderCustomService(name, image) {
+  const bodyLines = [`name: ${name}`, `image: ${image}`];
+  const comment = [
+    " port: 8080                 # in-container port \u2192 `monoceros tunnel`",
+    " env:                       # values resolved from <name>.env",
+    "   KEY: ${SOME_VAR}",
+    " volumes:",
+    `   - data:/data             # persistent host bind-mount under data/${name}`,
+    "   - rel/host/path:/in/container:ro",
+    " healthcheck:",
+    "   test: curl -f http://localhost:8080/health",
+    " restart: unless-stopped"
+  ].join("\n");
+  return { bodyLines, comment };
+}
+function customServiceHint(name) {
+  return `'${name}' is a custom image \u2014 Monoceros doesn't know its env, ports or volumes. Review the commented block under services[].${name} in the yml and fill in what the image needs.`;
 }
 
 // src/create/scaffold.ts
+import { existsSync as existsSync5, readFileSync as readFileSync3, promises as fs7 } from "fs";
+import path8 from "path";
 var APT_PACKAGE_NAME_RE2 = /^[a-z0-9][a-z0-9.+-]*$/;
 var FEATURE_REF_RE2 = /^[a-z0-9.-]+(\/[a-z0-9._-]+)+:[a-z0-9._-]+$/;
 var INSTALL_URL_RE2 = /^https:\/\/[A-Za-z0-9.\-_~/:?#[\]@!&'()*+,;=%]+$/;
@@ -2173,12 +2122,24 @@ function validateOptions(opts) {
       );
     }
   }
+  const seenServiceNames = /* @__PURE__ */ new Set();
   for (const svc of opts.services) {
-    if (!SERVICE_CATALOG[svc]) {
+    if (!svc.image) {
+      throw new Error(
+        `Service ${JSON.stringify(svc.name)} has no image. Every service needs an 'image:'.`
+      );
+    }
+    if (svc.name === "workspace") {
       throw new Error(
-        `Unknown service: ${svc}. Known: ${knownServices().join(", ")}.`
+        `Invalid service name 'workspace': it collides with the reserved devcontainer workspace service. Pick another name.`
       );
     }
+    if (seenServiceNames.has(svc.name)) {
+      throw new Error(
+        `Duplicate service name: ${JSON.stringify(svc.name)}. Each services[] entry must have a unique name.`
+      );
+    }
+    seenServiceNames.add(svc.name);
   }
   for (const pkg of opts.aptPackages ?? []) {
     if (!APT_PACKAGE_NAME_RE2.test(pkg)) {
@@ -2228,10 +2189,14 @@ function validateOptions(opts) {
 }
 function normalizeOptions(opts) {
   const languages = [...new Set(opts.languages)].sort();
-  let services = [...new Set(opts.services)].sort();
-  if (opts.postgresUrl) {
-    services = services.filter((s) => s !== "postgres");
+  const serviceByName = /* @__PURE__ */ new Map();
+  for (const svc of opts.services) {
+    if (opts.postgresUrl && svc.name === "postgres") continue;
+    serviceByName.set(svc.name, svc);
   }
+  const services = [...serviceByName.values()].sort(
+    (a, b) => a.name.localeCompare(b.name)
+  );
   const aptPackages = [...new Set(opts.aptPackages ?? [])].sort();
   const features = opts.features ? Object.fromEntries(
     Object.entries(opts.features).sort(([a], [b]) => a.localeCompare(b))
@@ -2291,7 +2256,7 @@ function resolveFeatures(opts) {
         const name = match.name;
         const checkout = workbenchCheckoutRoot();
         const localSourceDir = checkout ? path8.join(checkout, "images", "features", name) : null;
-        if (localSourceDir && existsSync4(localSourceDir)) {
+        if (localSourceDir && existsSync5(localSourceDir)) {
           const { paths, files } = readPersistentHomeEntries(localSourceDir);
           resolved.push({
             devcontainerKey: `./features/${name}`,
@@ -2317,7 +2282,7 @@ function resolveFeatures(opts) {
 function readPersistentHomeEntries(localSourceDir) {
   const manifestPath = path8.join(localSourceDir, "devcontainer-feature.json");
   try {
-    const text = readFileSync2(manifestPath, "utf8");
+    const text = readFileSync3(manifestPath, "utf8");
     const parsed = JSON.parse(text);
     return {
       paths: filterSubpaths(parsed["x-monoceros"]?.persistentHomePaths),
@@ -2392,7 +2357,7 @@ function buildDevcontainerJson(opts, dockerMode = "rootful") {
       name: opts.name,
       dockerComposeFile: "compose.yaml",
       service: "workspace",
-      ...opts.services.length > 0 ? { runServices: opts.services } : {},
+      ...opts.services.length > 0 ? { runServices: opts.services.map((s) => s.name) } : {},
       workspaceFolder: `/workspaces/${opts.name}`,
       remoteUser: "node",
       forwardPorts: ports,
@@ -2425,6 +2390,18 @@ function buildDevcontainerJson(opts, dockerMode = "rootful") {
     ...customizationsField ?? {}
   };
 }
+function composeScalar(value) {
+  const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\t/g, "\\t");
+  return `"${escaped}"`;
+}
+function composeVolumeSource(spec, serviceName) {
+  const parts = spec.split(":");
+  const src = parts[0];
+  const rest = parts.slice(1).join(":");
+  if (src === "data") return `../data/${serviceName}:${rest}`;
+  const relative = src.startsWith("./") ? src.slice(2) : src;
+  return `../${relative}:${rest}`;
+}
 function buildComposeYaml(opts, dockerMode = "rootful") {
   void dockerMode;
   const hasPorts = (opts.ports?.length ?? 0) > 0;
@@ -2453,20 +2430,42 @@ function buildComposeYaml(opts, dockerMode = "rootful") {
       lines.push(`      - ../home/${sub}:/home/node/${sub}`);
     }
   }
-  for (const svcId of opts.services) {
-    const def = SERVICE_CATALOG[svcId];
-    if (!def) continue;
-    lines.push(`  ${def.id}:`);
-    lines.push(`    image: ${def.image}`);
-    if (def.env) {
+  for (const svc of opts.services) {
+    lines.push(`  ${svc.name}:`);
+    lines.push(`    image: ${svc.image}`);
+    if (svc.restart) {
+      lines.push(`    restart: ${svc.restart}`);
+    }
+    if (svc.command !== void 0) {
+      lines.push(`    command: ${composeScalar(svc.command)}`);
+    }
+    const envKeys = Object.keys(svc.env);
+    if (envKeys.length > 0) {
       lines.push("    environment:");
-      for (const [k, v] of Object.entries(def.env)) {
-        lines.push(`      ${k}: ${v}`);
+      for (const k of envKeys) {
+        lines.push(`      ${k}: ${composeScalar(svc.env[k])}`);
       }
     }
-    if (def.dataMount) {
+    if (svc.volumes.length > 0) {
       lines.push("    volumes:");
-      lines.push(`      - ../data/${def.id}:${def.dataMount}`);
+      for (const vol of svc.volumes) {
+        lines.push(`      - ${composeVolumeSource(vol, svc.name)}`);
+      }
+    }
+    if (svc.healthcheck) {
+      const hc = svc.healthcheck;
+      lines.push("    healthcheck:");
+      if (Array.isArray(hc.test)) {
+        lines.push(`      test: [${hc.test.map(composeScalar).join(", ")}]`);
+      } else {
+        lines.push(`      test: ${composeScalar(hc.test)}`);
+      }
+      if (hc.interval) lines.push(`      interval: ${hc.interval}`);
+      if (hc.timeout) lines.push(`      timeout: ${hc.timeout}`);
+      if (hc.retries !== void 0) lines.push(`      retries: ${hc.retries}`);
+      if (hc.startPeriod) {
+        lines.push(`      start_period: ${hc.startPeriod}`);
+      }
     }
   }
   if (hasPorts) {
@@ -2602,243 +2601,97 @@ function buildPostCreateScript(opts) {
 async function writePostCreateScript(devcontainerDir, opts) {
   const dest = path8.join(devcontainerDir, "post-create.sh");
   await fs7.writeFile(dest, buildPostCreateScript(opts));
-  await fs7.chmod(dest, 493);
-}
-async function writeScaffold(opts, targetDir, scaffoldOpts = {}) {
-  const dockerMode = scaffoldOpts.dockerMode ?? "rootful";
-  const devcontainerDir = path8.join(targetDir, ".devcontainer");
-  const monocerosDir = path8.join(targetDir, ".monoceros");
-  const projectsDir = path8.join(targetDir, "projects");
-  const homeDir = path8.join(targetDir, "home");
-  const dataDir = path8.join(targetDir, "data");
-  await fs7.mkdir(devcontainerDir, { recursive: true });
-  await fs7.mkdir(monocerosDir, { recursive: true });
-  await fs7.mkdir(projectsDir, { recursive: true });
-  await fs7.mkdir(homeDir, { recursive: true });
-  if (needsCompose(opts)) {
-    await fs7.mkdir(dataDir, { recursive: true });
-    for (const svcId of opts.services) {
-      const def = SERVICE_CATALOG[svcId];
-      if (def?.dataMount) {
-        await fs7.mkdir(path8.join(dataDir, def.id), { recursive: true });
-      }
-    }
-  }
-  const containerGitignore = path8.join(targetDir, ".gitignore");
-  await fs7.writeFile(containerGitignore, "/home/\n/.monoceros/\n/data/\n");
-  const gitkeep = path8.join(projectsDir, ".gitkeep");
-  if (!existsSync4(gitkeep)) {
-    await fs7.writeFile(gitkeep, "");
-  }
-  await fs7.writeFile(
-    path8.join(monocerosDir, ".gitignore"),
-    "git-credentials*\ngitconfig\n"
-  );
-  const devcontainerJson = buildDevcontainerJson(opts, dockerMode);
-  await fs7.writeFile(
-    path8.join(devcontainerDir, "devcontainer.json"),
-    JSON.stringify(devcontainerJson, null, 2) + "\n"
-  );
-  const featuresDir = path8.join(devcontainerDir, "features");
-  if (existsSync4(featuresDir)) {
-    await fs7.rm(featuresDir, { recursive: true, force: true });
-  }
-  const resolvedFeatures = resolveFeatures(opts);
-  for (const f of resolvedFeatures) {
-    if (!f.localSourceDir || !f.localName) continue;
-    const dest = path8.join(featuresDir, f.localName);
-    await fs7.mkdir(dest, { recursive: true });
-    await fs7.cp(f.localSourceDir, dest, { recursive: true });
-  }
-  for (const f of resolvedFeatures) {
-    for (const sub of f.persistentHomePaths) {
-      await fs7.mkdir(path8.join(homeDir, sub), { recursive: true });
-    }
-    for (const entry2 of f.persistentHomeFiles) {
-      const filePath = path8.join(homeDir, entry2.path);
-      await fs7.mkdir(path8.dirname(filePath), { recursive: true });
-      if (!existsSync4(filePath)) {
-        await fs7.writeFile(filePath, entry2.initialContent);
-      }
-    }
-  }
-  await writePostCreateScript(devcontainerDir, opts);
-  const composePath = path8.join(devcontainerDir, "compose.yaml");
-  if (needsCompose(opts)) {
-    await fs7.writeFile(composePath, buildComposeYaml(opts, dockerMode));
-  } else if (existsSync4(composePath)) {
-    await fs7.rm(composePath);
-  }
-  const workspacePath = path8.join(targetDir, `${opts.name}.code-workspace`);
-  let existingWorkspace;
-  try {
-    const raw = await fs7.readFile(workspacePath, "utf8");
-    existingWorkspace = JSON.parse(raw);
-  } catch {
-    existingWorkspace = void 0;
-  }
-  const generated = buildCodeWorkspaceJson(opts);
-  const merged = mergeCodeWorkspace(existingWorkspace, generated);
-  await fs7.writeFile(workspacePath, JSON.stringify(merged, null, 2) + "\n");
-}
-
-// src/modify/yml.ts
-import {
-  isMap as isMap2,
-  isScalar,
-  isSeq,
-  Pair as Pair2,
-  Scalar as Scalar2,
-  YAMLMap as YAMLMap2,
-  YAMLSeq
-} from "yaml";
-
-// src/init/manifest.ts
-import { existsSync as existsSync5, readFileSync as readFileSync3 } from "fs";
-import path9 from "path";
-function resolveManifestPath(name, checkoutRoot) {
-  if (checkoutRoot) {
-    const checkoutPath = path9.join(
-      checkoutRoot,
-      "images",
-      "features",
-      name,
-      "devcontainer-feature.json"
-    );
-    if (existsSync5(checkoutPath)) return checkoutPath;
-  }
-  const bundlePath = path9.join(
-    bundledFeaturesDir(),
-    name,
-    "devcontainer-feature.json"
-  );
-  if (existsSync5(bundlePath)) return bundlePath;
-  return null;
-}
-function loadFeatureManifestSummary(ref, checkoutRoot = workbenchCheckoutRoot()) {
-  const match = matchMonocerosFeature(ref);
-  if (!match) return void 0;
-  const manifestPath = resolveManifestPath(match.name, checkoutRoot);
-  if (!manifestPath) return void 0;
-  try {
-    const text = readFileSync3(manifestPath, "utf8");
-    const parsed = JSON.parse(text);
-    const rawHints = parsed["x-monoceros"]?.optionHints;
-    const optionHints = Array.isArray(rawHints) ? rawHints.filter(
-      (x) => typeof x === "string" && x.length > 0
-    ) : [];
-    const rawNotes = parsed["x-monoceros"]?.usageNotes;
-    const usageNotes = Array.isArray(rawNotes) ? rawNotes.filter(
-      (x) => typeof x === "string" && x.length > 0
-    ) : [];
-    const optionDescriptions = {};
-    const optionTypes = {};
-    const optionNames = [];
-    if (parsed.options) {
-      for (const [key, opt] of Object.entries(parsed.options)) {
-        if (!opt || typeof opt !== "object") continue;
-        optionNames.push(key);
-        if (typeof opt.description === "string" && opt.description.length > 0) {
-          optionDescriptions[key] = opt.description;
-        }
-        if (opt.type === "boolean") {
-          optionTypes[key] = "boolean";
-        } else if (opt.type === "string") {
-          optionTypes[key] = "string";
-        }
-      }
-    }
-    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,
-      optionNames,
-      optionTypes,
-      usageNotes
-    };
-  } catch {
-    return void 0;
-  }
-}
-
-// src/init/feature-doc.ts
-function buildFeatureHeaderLines(summary, width) {
-  const paragraphs = buildHeaderParagraphs(summary);
-  const wrapped = [];
-  for (const para of paragraphs) {
-    for (const line of wrapToComment(para, width)) {
-      wrapped.push(line);
-    }
-  }
-  return wrapped;
-}
-function buildFeatureHeaderCommentBefore(summary, width) {
-  const lines = buildFeatureHeaderLines(summary, width);
-  return lines.map((l) => ` ${l}`).join("\n");
+  await fs7.chmod(dest, 493);
 }
-function buildHeaderParagraphs(summary) {
-  if (!summary) return [];
-  const 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);
+async function writeScaffold(opts, targetDir, scaffoldOpts = {}) {
+  const dockerMode = scaffoldOpts.dockerMode ?? "rootful";
+  const devcontainerDir = path8.join(targetDir, ".devcontainer");
+  const monocerosDir = path8.join(targetDir, ".monoceros");
+  const projectsDir = path8.join(targetDir, "projects");
+  const homeDir = path8.join(targetDir, "home");
+  const dataDir = path8.join(targetDir, "data");
+  await fs7.mkdir(devcontainerDir, { recursive: true });
+  await fs7.mkdir(monocerosDir, { recursive: true });
+  await fs7.mkdir(projectsDir, { recursive: true });
+  await fs7.mkdir(homeDir, { recursive: true });
+  if (needsCompose(opts)) {
+    await fs7.mkdir(dataDir, { recursive: true });
+    for (const svc of opts.services) {
+      const hasDataVolume = svc.volumes.some((v) => v.split(":")[0] === "data");
+      if (hasDataVolume) {
+        await fs7.mkdir(path8.join(dataDir, svc.name), { recursive: true });
+      }
+    }
   }
-  for (const note of summary.usageNotes) {
-    const trimmed = note.trim();
-    if (trimmed.length > 0) out.push(trimmed);
+  const containerGitignore = path8.join(targetDir, ".gitignore");
+  await fs7.writeFile(containerGitignore, "/home/\n/.monoceros/\n/data/\n");
+  const gitkeep = path8.join(projectsDir, ".gitkeep");
+  if (!existsSync5(gitkeep)) {
+    await fs7.writeFile(gitkeep, "");
   }
-  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(", ")}.`);
+  await fs7.writeFile(
+    path8.join(monocerosDir, ".gitignore"),
+    "git-credentials*\ngitconfig\n"
+  );
+  const devcontainerJson = buildDevcontainerJson(opts, dockerMode);
+  await fs7.writeFile(
+    path8.join(devcontainerDir, "devcontainer.json"),
+    JSON.stringify(devcontainerJson, null, 2) + "\n"
+  );
+  const featuresDir = path8.join(devcontainerDir, "features");
+  if (existsSync5(featuresDir)) {
+    await fs7.rm(featuresDir, { recursive: true, force: true });
   }
-  if (summary.documentationURL) {
-    out.push(`See ${summary.documentationURL} for further information.`);
+  const resolvedFeatures = resolveFeatures(opts);
+  for (const f of resolvedFeatures) {
+    if (!f.localSourceDir || !f.localName) continue;
+    const dest = path8.join(featuresDir, f.localName);
+    await fs7.mkdir(dest, { recursive: true });
+    await fs7.cp(f.localSourceDir, dest, { recursive: true });
   }
-  return out;
-}
-function shortenOptionDescription(desc) {
-  const firstSentence = desc.split(/(?<=[.!?])\s+/)[0]?.trim() ?? desc.trim();
-  return firstSentence.replace(/[.!?]+$/, "").trim();
-}
-function wrapToComment(text, width) {
-  const words = text.split(/\s+/).filter((w) => w.length > 0);
-  if (words.length === 0) return [""];
-  const usable = Math.max(width, 20);
-  const lines = [];
-  let current = "";
-  for (const w of words) {
-    if (current.length === 0) {
-      current = w;
-      continue;
+  for (const f of resolvedFeatures) {
+    for (const sub of f.persistentHomePaths) {
+      await fs7.mkdir(path8.join(homeDir, sub), { recursive: true });
     }
-    if (current.length + 1 + w.length <= usable) {
-      current += " " + w;
-    } else {
-      lines.push(current);
-      current = w;
+    for (const entry2 of f.persistentHomeFiles) {
+      const filePath = path8.join(homeDir, entry2.path);
+      await fs7.mkdir(path8.dirname(filePath), { recursive: true });
+      if (!existsSync5(filePath)) {
+        await fs7.writeFile(filePath, entry2.initialContent);
+      }
     }
   }
-  if (current.length > 0) lines.push(current);
-  return lines;
+  await writePostCreateScript(devcontainerDir, opts);
+  const composePath = path8.join(devcontainerDir, "compose.yaml");
+  if (needsCompose(opts)) {
+    await fs7.writeFile(composePath, buildComposeYaml(opts, dockerMode));
+  } else if (existsSync5(composePath)) {
+    await fs7.rm(composePath);
+  }
+  const workspacePath = path8.join(targetDir, `${opts.name}.code-workspace`);
+  let existingWorkspace;
+  try {
+    const raw = await fs7.readFile(workspacePath, "utf8");
+    existingWorkspace = JSON.parse(raw);
+  } catch {
+    existingWorkspace = void 0;
+  }
+  const generated = buildCodeWorkspaceJson(opts);
+  const merged = mergeCodeWorkspace(existingWorkspace, generated);
+  await fs7.writeFile(workspacePath, JSON.stringify(merged, null, 2) + "\n");
 }
-var FEATURE_HEADER_WIDTH = 76 - 2;
 
 // src/modify/yml.ts
+import {
+  isMap as isMap2,
+  isScalar,
+  isSeq,
+  Pair as Pair2,
+  parseDocument as parseDocument3,
+  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;
@@ -2861,11 +2714,24 @@ function addLanguageToDoc(doc, lang) {
   seq.add(lang);
   return true;
 }
-function addServiceToDoc(doc, service) {
+function findServiceItem(seq, name) {
+  for (const item of seq.items) {
+    if (isMap2(item) && item.get("name") === name) return item;
+  }
+  return void 0;
+}
+function addServiceEntryToDoc(doc, name, image, bodyLines, scaffoldComment) {
   const seq = ensureSeq(doc, "services");
-  if (seq.items.some((i) => scalarValue(i) === service)) return false;
-  seq.add(service);
-  return true;
+  const existing = findServiceItem(seq, name);
+  if (existing) {
+    const existingImage = existing.get("image");
+    if (existingImage === image) return { outcome: "exists" };
+    return { outcome: "conflict", existingImage: String(existingImage) };
+  }
+  const node = parseDocument3(bodyLines.join("\n")).contents;
+  if (scaffoldComment) node.comment = scaffoldComment;
+  seq.add(node);
+  return { outcome: "added" };
 }
 function addAptPackagesToDoc(doc, packages) {
   const seq = ensureSeq(doc, "aptPackages");
@@ -3085,6 +2951,12 @@ function addFeatureToDoc(doc, ref, options = {}, displayName) {
     entry2.commentBefore = headerBefore;
     entry2.spaceBefore = true;
   }
+  const hints = featureOptionHints(summary, ref, Object.keys(options));
+  if (hints.length > 0) {
+    const commentLines = [" options:"];
+    for (const h of hints) commentLines.push(`   ${h.key}: ${h.placeholder}`);
+    entry2.comment = commentLines.join("\n");
+  }
   seq.add(entry2);
   return true;
 }
@@ -3161,7 +3033,15 @@ function removeLanguageFromDoc(doc, lang) {
   return removeScalarFromSeq(doc, "languages", lang);
 }
 function removeServiceFromDoc(doc, service) {
-  return removeScalarFromSeq(doc, "services", service);
+  const node = doc.get("services", true);
+  if (!node || !isSeq(node)) return false;
+  const idx = node.items.findIndex(
+    (i) => isMap2(i) && i.get("name") === service
+  );
+  if (idx === -1) return false;
+  node.items.splice(idx, 1);
+  pruneEmptySeq(doc, "services");
+  return true;
 }
 function removeAptPackageFromDoc(doc, pkg) {
   return removeScalarFromSeq(doc, "aptPackages", pkg);
@@ -3201,8 +3081,8 @@ function removeRepoFromDoc(doc, urlOrPath) {
     if (!isMap2(item)) return false;
     const url = item.get("url");
     if (url === urlOrPath) return true;
-    const path18 = item.get("path");
-    const effectivePath = typeof path18 === "string" ? path18 : typeof url === "string" ? deriveRepoName(url) : void 0;
+    const path21 = item.get("path");
+    const effectivePath = typeof path21 === "string" ? path21 : typeof url === "string" ? deriveRepoName(url) : void 0;
     return effectivePath === urlOrPath;
   });
   if (idx < 0) return false;
@@ -3229,13 +3109,38 @@ function runAddLanguage(input) {
   }
   return mutate(input, (doc) => addLanguageToDoc(doc, input.language));
 }
-function runAddService(input) {
-  if (!SERVICE_CATALOG[input.service]) {
+async function runAddService(input) {
+  const arg = input.service;
+  const curated = isCuratedService(arg);
+  if (input.as !== void 0 && !/^[a-z0-9][a-z0-9_-]*$/.test(input.as)) {
     throw new Error(
-      `Unknown service: ${input.service}. Known: ${knownServices().join(", ")}.`
+      `Invalid --as name ${JSON.stringify(input.as)}. Use lowercase letters, digits, '_' or '-' (must start with a letter or digit).`
+    );
+  }
+  const name = input.as ?? (curated ? arg : deriveServiceName(arg));
+  const image = curated ? expandCuratedService(arg).image : arg;
+  const custom = curated ? null : renderCustomService(name, arg);
+  const bodyLines = curated ? renderServiceObjectBody({ ...expandCuratedService(arg), name }) : custom.bodyLines;
+  const scaffoldComment = curated ? void 0 : custom.comment;
+  const result = await mutate(input, (doc) => {
+    const r = addServiceEntryToDoc(
+      doc,
+      name,
+      image,
+      bodyLines,
+      scaffoldComment
     );
+    if (r.outcome === "conflict") {
+      throw new Error(
+        `A service named '${name}' already exists with a different image (${r.existingImage}). Add it under a different name with \`--as <name>\`, or remove the existing one first (\`monoceros remove-service ${input.name} ${name}\`).`
+      );
+    }
+    return r.outcome === "added";
+  });
+  if (result.status === "updated" && !curated) {
+    (input.logger ?? defaultLogger()).info(customServiceHint(name));
   }
-  return mutate(input, (doc) => addServiceToDoc(doc, input.service));
+  return result;
 }
 function runAddAptPackages(input) {
   if (input.packages.length === 0) {
@@ -3252,7 +3157,7 @@ async function runAddRepo(input) {
       "Missing repo URL. Usage: monoceros add-repo <containername> <url>."
     );
   }
-  const path18 = (input.path ?? deriveRepoName(url)).trim();
+  const path21 = (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) {
@@ -3281,7 +3186,7 @@ async function runAddRepo(input) {
   const providerToWrite = !canonical && explicitProvider ? explicitProvider : void 0;
   const entry2 = {
     url,
-    path: path18,
+    path: path21,
     ...hasName && hasEmail ? {
       gitUser: {
         name: input.gitName.trim(),
@@ -3397,7 +3302,7 @@ async function tryCloneInRunningContainer(input, entry2) {
   logger.info(
     `Cloned ${entry2.url} into /workspaces/${containerName2}/${targetRel} inside the running container.`
   );
-  void path10;
+  void path9;
 }
 function shquote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
@@ -3474,10 +3379,33 @@ async function runAddFeature(input) {
     ...resolved.defaultOptions,
     ...input.options ?? {}
   };
-  return mutate(
+  const result = await mutate(
     input,
     (doc) => addFeatureToDoc(doc, resolved.ref, merged, raw)
   );
+  if (result.status === "updated") {
+    const summary = loadFeatureManifestSummary(resolved.ref);
+    const vars = featureOptionHints(
+      summary,
+      resolved.ref,
+      Object.keys(merged)
+    ).map((h) => h.envVar);
+    if (vars.length > 0) {
+      const home = input.monocerosHome ?? monocerosHome();
+      await ensureEnvGitignored(containerConfigsDir(home));
+      const seeded = await ensureEnvVars(
+        containerEnvPath(input.name, home),
+        input.name,
+        vars
+      );
+      if (seeded.added.length > 0) {
+        (input.logger ?? defaultLogger()).info(
+          `Seeded ${seeded.added.join(", ")} into ${input.name}.env \u2014 fill in the values.`
+        );
+      }
+    }
+  }
+  return result;
 }
 async function resolveFeatureRefOrShortname(input) {
   if (REGEX.featureRef.test(input)) {
@@ -3616,13 +3544,13 @@ async function mutate(opts, apply) {
 }
 function defaultLogger() {
   return {
-    info: (m) => consola2.info(m),
-    success: (m) => consola2.success(m),
-    warn: (m) => consola2.warn(m)
+    info: (m) => consola.info(m),
+    success: (m) => consola.success(m),
+    warn: (m) => consola.warn(m)
   };
 }
 var defaultConfirm = async (message) => {
-  const result = await consola2.prompt(message, {
+  const result = await consola.prompt(message, {
     type: "confirm",
     initial: false
   });
@@ -3662,9 +3590,6 @@ async function syncPortsToProxy(input) {
         ...input.proxyDocker ? { docker: input.proxyDocker } : {},
         logger: { info: (m) => logger.info(m), warn: (m) => logger.warn(m) }
       });
-      await kickProxyReload({
-        ...input.proxyDocker ? { docker: input.proxyDocker } : {}
-      });
       const urls = proxyUrlsFor(input.name, allPorts, hostPort);
       const lines = urls.map((u) => {
         const tag = u.isDefault ? " (default)" : "";
@@ -3674,9 +3599,6 @@ async function syncPortsToProxy(input) {
 ${lines.join("\n")}`);
     } else {
       await removeDynamicConfig(input.name, { monocerosHome: home });
-      await kickProxyReload({
-        ...input.proxyDocker ? { docker: input.proxyDocker } : {}
-      });
       await maybeStopProxy({
         monocerosHome: home,
         ...input.proxyDocker ? { docker: input.proxyDocker } : {},
@@ -3713,7 +3635,7 @@ var addAptPackagesCommand = defineCommand({
   async run({ args }) {
     const packages = [...getInnerArgs()];
     if (packages.length === 0) {
-      consola3.error(
+      consola2.error(
         "No package names given. Usage: `monoceros add-apt-packages <containername> [--yes] -- <pkg> [<pkg> \u2026]`."
       );
       process.exit(1);
@@ -3726,7 +3648,7 @@ var addAptPackagesCommand = defineCommand({
       });
       process.exit(result.status === "aborted" ? 1 : 0);
     } catch (err) {
-      consola3.error(err instanceof Error ? err.message : String(err));
+      consola2.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   }
@@ -3734,7 +3656,7 @@ var addAptPackagesCommand = defineCommand({
 
 // src/commands/add-feature.ts
 import { defineCommand as defineCommand2 } from "citty";
-import { consola as consola4 } from "consola";
+import { consola as consola3 } from "consola";
 var addFeatureCommand = defineCommand2({
   meta: {
     name: "add-feature",
@@ -3764,7 +3686,7 @@ var addFeatureCommand = defineCommand2({
     try {
       options = parseOptionsAfterDashes(getInnerArgs());
     } catch (err) {
-      consola4.error(err instanceof Error ? err.message : String(err));
+      consola3.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
     try {
@@ -3776,7 +3698,7 @@ var addFeatureCommand = defineCommand2({
       });
       process.exit(result.status === "aborted" ? 1 : 0);
     } catch (err) {
-      consola4.error(err instanceof Error ? err.message : String(err));
+      consola3.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   }
@@ -3808,7 +3730,7 @@ function coerce(value) {
 
 // src/commands/add-from-url.ts
 import { defineCommand as defineCommand3 } from "citty";
-import { consola as consola5 } from "consola";
+import { consola as consola4 } from "consola";
 var addFromUrlCommand = defineCommand3({
   meta: {
     name: "add-from-url",
@@ -3845,7 +3767,7 @@ var addFromUrlCommand = defineCommand3({
       });
       process.exit(result.status === "aborted" ? 1 : 0);
     } catch (err) {
-      consola5.error(err instanceof Error ? err.message : String(err));
+      consola4.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   }
@@ -3880,7 +3802,7 @@ function printSecurityWarning(url) {
 
 // src/commands/add-repo.ts
 import { defineCommand as defineCommand4 } from "citty";
-import { consola as consola6 } from "consola";
+import { consola as consola5 } from "consola";
 var addRepoCommand = defineCommand4({
   meta: {
     name: "add-repo",
@@ -3934,7 +3856,7 @@ var addRepoCommand = defineCommand4({
       });
       process.exit(result.status === "aborted" ? 1 : 0);
     } catch (err) {
-      consola6.error(err instanceof Error ? err.message : String(err));
+      consola5.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   }
@@ -3942,7 +3864,7 @@ var addRepoCommand = defineCommand4({
 
 // src/commands/add-language.ts
 import { defineCommand as defineCommand5 } from "citty";
-import { consola as consola7 } from "consola";
+import { consola as consola6 } from "consola";
 var addLanguageCommand = defineCommand5({
   meta: {
     name: "add-language",
@@ -3955,11 +3877,111 @@ var addLanguageCommand = defineCommand5({
       description: "Container name (yml in $MONOCEROS_HOME/container-configs/).",
       required: true
     },
-    language: {
+    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;
+}
+
+// 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 backing service to the container config. A curated name (postgres, mysql, redis) expands to a full editable block; any other image (e.g. rustfs/rustfs:latest) drops in name + image plus a commented scaffold. 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: "Language identifier from the feature whitelist (e.g. python, java, rust).",
+      description: "Curated name (postgres, mysql, redis) or any image ref (e.g. rustfs/rustfs:latest).",
       required: true
     },
+    as: {
+      type: "string",
+      description: "Override the service name (the compose service / DNS name / data dir). Lets you add the same image more than once \u2014 e.g. two postgres servers as postgres-app and postgres-analytics."
+    },
     yes: {
       type: "boolean",
       description: "Skip the interactive confirmation and apply the diff.",
@@ -3969,213 +3991,464 @@ var addLanguageCommand = defineCommand5({
   },
   async run({ args }) {
     try {
-      const result = await runAddLanguage({
+      const result = await runAddService({
         name: args.name,
-        language: args.language,
+        service: args.service,
+        ...args.as ? { as: args.as } : {},
         yes: args.yes
       });
       process.exit(result.status === "aborted" ? 1 : 0);
     } catch (err) {
-      consola7.error(err instanceof Error ? err.message : String(err));
+      consola8.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 consola8 } 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
+// src/commands/apply.ts
+import { defineCommand as defineCommand8 } from "citty";
+
+// src/apply/index.ts
+import { existsSync as existsSync8, promises as fs12 } from "fs";
+import { consola as consola11 } from "consola";
+
+// src/config/state.ts
+import { promises as fs9 } from "fs";
+import path10 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 path10.join(targetDir, ".monoceros", "state.json");
+}
+async function readStateFile(targetDir) {
+  try {
+    const content = await fs9.readFile(stateFilePath(targetDir), "utf8");
+    return JSON.parse(content);
+  } catch {
+    return void 0;
+  }
+}
+async function writeStateFile(targetDir, state) {
+  const monocerosDir = path10.join(targetDir, ".monoceros");
+  await fs9.mkdir(monocerosDir, { recursive: true });
+  await fs9.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] ?? {};
+    const containerOpts = Object.fromEntries(
+      Object.entries(entry2.options ?? {}).filter(([, v]) => v !== "")
+    );
+    featureRecord[entry2.ref] = { ...defaults, ...containerOpts };
+  }
+  const result = {
+    name: config.name,
+    languages: [...config.languages],
+    // Normalize every services[] entry (curated string or explicit
+    // object) to the canonical ResolvedService shape. `${VAR}` values
+    // survive untouched here — apply interpolates them against
+    // <name>.env afterwards.
+    services: config.services.map(resolveService)
+  };
+  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),
+      // 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);
+    }
+    result.ports = ports;
+  }
+  if (config.routing?.vscodeAutoForward !== void 0) {
+    result.vscodeAutoForward = config.routing.vscodeAutoForward;
+  }
+  return result;
+}
+
+// src/devcontainer/compose.ts
+import { spawn as spawn5 } from "child_process";
+import { existsSync as existsSync6 } from "fs";
+import path12 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));
     },
-    yes: {
-      type: "boolean",
-      description: "Skip the interactive confirmation and apply the diff.",
-      alias: ["y"],
-      default: false
+    flush(cb) {
+      if (buffer.length > 0) {
+        const tail = maskSecrets(buffer);
+        buffer = "";
+        cb(null, tail);
+        return;
+      }
+      cb(null);
+    }
+  });
+}
+
+// src/devcontainer/cli.ts
+import { spawn as spawn4 } from "child_process";
+import { readFileSync as readFileSync4 } from "fs";
+import { createRequire } from "module";
+import path11 from "path";
+
+// src/devcontainer/runtime-pull-hint.ts
+import { Transform as Transform2 } from "stream";
+var RUNTIME_PULL_MARKER = "No manifest found for ghcr.io/getmonoceros/monoceros-runtime";
+var RUNTIME_PULL_HINT = 'Downloading the Monoceros runtime image now -- expected on first apply, takes ~1-2 min (Docker pulls the multi-arch base with no progress output). The "No manifest found" line above is harmless. Please wait...';
+function createRuntimePullHintStream(state) {
+  let buffer = "";
+  const appendHintIfMarker = (block) => {
+    if (state.hinted || !block.includes(RUNTIME_PULL_MARKER)) return block;
+    state.hinted = true;
+    return `${block}${dim(`(i) ${RUNTIME_PULL_HINT}`)}
+`;
+  };
+  return new Transform2({
+    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, appendHintIfMarker(flushable));
     },
-    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
+    flush(cb) {
+      if (buffer.length === 0) {
+        cb(null);
+        return;
+      }
+      const tail = buffer;
+      buffer = "";
+      cb(null, appendHintIfMarker(tail));
     }
-  },
-  async run({ args }) {
-    const tokens = [...getInnerArgs()];
-    if (tokens.length === 0) {
-      consola8.error(
-        "No ports given. Usage: `monoceros add-port <containername> [--yes] [--default] -- <port> [<port> \u2026]`."
-      );
-      process.exit(1);
+  });
+}
+
+// src/devcontainer/cli.ts
+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(readFileSync4(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 = path11.resolve(path11.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"
+      });
+      child2.on("error", reject);
+      child2.on("exit", (code) => resolve(code ?? 0));
+      return;
     }
-    try {
-      const result = await runAddPort({
-        name: args.name,
-        ports: tokens.map(coerceToken),
-        yes: args.yes,
-        asDefault: args.default
+    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);
       });
-      process.exit(result.status === "aborted" ? 1 : 0);
-    } catch (err) {
-      consola8.error(err instanceof Error ? err.message : String(err));
-      process.exit(1);
+      return;
+    }
+    const pullHint = { hinted: false };
+    child.stdout?.pipe(createSecretMaskStream()).pipe(createRuntimePullHintStream(pullHint)).pipe(process.stdout);
+    child.stderr?.pipe(createSecretMaskStream()).pipe(createRuntimePullHintStream(pullHint)).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 spawnDocker = (args) => {
+  return new Promise((resolve, reject) => {
+    const child = spawn5("docker", args, {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString("utf8");
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString("utf8");
+    });
+    child.on("error", reject);
+    child.on(
+      "exit",
+      (code) => resolve({ exitCode: code ?? 0, stdout, stderr })
+    );
+  });
+};
+async function findContainerIds(filters, exec = spawnDocker) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const filter of filters) {
+    const result = await exec(["ps", "-aq", "--filter", filter]);
+    if (result.exitCode !== 0) continue;
+    for (const line of result.stdout.split(/\r?\n/)) {
+      const id = line.trim();
+      if (id) ids.add(id);
     }
   }
-});
-function coerceToken(raw) {
-  const n = Number(raw);
-  return Number.isFinite(n) ? n : raw;
+  return [...ids];
 }
-
-// src/commands/add-service.ts
-import { defineCommand as defineCommand7 } from "citty";
-import { consola as consola9 } 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 function cleanupDockerObjects(opts) {
+  const exec = opts.exec ?? spawnDocker;
+  const tag = opts.logTag ?? "cleanup";
+  opts.logger.info(`[${tag}] tearing down docker project ${opts.projectName}\u2026`);
+  const ids = await findContainerIds(opts.filters, exec);
+  let rmExit = 0;
+  if (ids.length > 0) {
+    opts.logger.info(`[${tag}] removing containers: ${ids.join(" ")}`);
+    const rmResult = await exec(["rm", "-f", ...ids]);
+    rmExit = rmResult.exitCode;
+    if (rmExit !== 0 && rmResult.stderr.trim()) {
+      opts.logger.info(`[${tag}] ${rmResult.stderr.trim()}`);
     }
-  },
-  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) {
-      consola9.error(err instanceof Error ? err.message : String(err));
-      process.exit(1);
+  } else {
+    opts.logger.info(`[${tag}] no containers found`);
+  }
+  if (opts.network) {
+    const netResult = await exec(["network", "rm", opts.network]);
+    if (netResult.exitCode === 0) {
+      opts.logger.info(`[${tag}] network ${opts.network} removed`);
     }
   }
-});
-
-// src/commands/apply.ts
-import { defineCommand as defineCommand8 } from "citty";
-
-// src/apply/index.ts
-import { existsSync as existsSync6, promises as fs11 } from "fs";
-import { consola as consola11 } from "consola";
-
-// src/config/state.ts
-import { promises as fs9 } from "fs";
-import path11 from "path";
-function buildStateFile(opts) {
-  return {
-    schemaVersion: CONFIG_SCHEMA_VERSION,
-    origin: opts.origin,
-    monocerosCliVersion: opts.cliVersion,
-    materializedAt: (opts.now ?? /* @__PURE__ */ new Date()).toISOString()
-  };
+  opts.logger.info(`[${tag}] docker cleanup done`);
+  return { exitCode: rmExit, removedIds: ids };
 }
-function stateFilePath(targetDir) {
-  return path11.join(targetDir, ".monoceros", "state.json");
+function composeProjectName(root) {
+  return `${path12.basename(root)}_devcontainer`;
 }
-async function readStateFile(targetDir) {
-  try {
-    const content = await fs9.readFile(stateFilePath(targetDir), "utf8");
-    return JSON.parse(content);
-  } catch {
-    return void 0;
+function resolveCompose(root) {
+  if (!existsSync6(path12.join(root, ".devcontainer"))) {
+    throw new Error(
+      `No .devcontainer/ at ${root}. Run \`monoceros apply <name>\` first.`
+    );
+  }
+  const composeFile = path12.join(root, ".devcontainer", "compose.yaml");
+  if (!existsSync6(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 writeStateFile(targetDir, state) {
-  const monocerosDir = path11.join(targetDir, ".monoceros");
-  await fs9.mkdir(monocerosDir, { recursive: true });
-  await fs9.writeFile(
-    stateFilePath(targetDir),
-    JSON.stringify(state, null, 2) + "\n"
+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
   );
 }
-
-// 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 !== "")
+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`
     );
-    featureRecord[entry2.ref] = { ...defaults, ...containerOpts };
-  }
-  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),
-      // 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);
+    const exec = opts.dockerExec ?? spawnDocker;
+    const filters = [
+      `label=com.docker.compose.project=${projectName}`,
+      `name=^${projectName}-`
+    ];
+    const { exitCode: rmExit } = await cleanupDockerObjects({
+      projectName,
+      filters,
+      network: `${projectName}_default`,
+      logger,
+      exec
+    });
+    if (rmExit !== 0) return rmExit;
+    const remaining = await findContainerIds(filters, exec);
+    if (remaining.length > 0) {
+      const warn = logger.warn ?? logger.info;
+      warn(
+        `ERROR: containers under project ${projectName} reappeared after removal.
+This typically means VS Code's Remote Containers extension is connected
+to this devcontainer and auto-recreated it. Close the dev container
+session in VS Code (Cmd+Shift+P \u2192 'Dev Containers: Close Remote Connection')
+and retry \`monoceros apply\`.`
+      );
+      return 1;
     }
-    result.ports = ports;
-  }
-  if (config.routing?.vscodeAutoForward !== void 0) {
-    result.vscodeAutoForward = config.routing.vscodeAutoForward;
+    return runStart({
+      root,
+      ...opts.devcontainerSpawn ? { spawn: opts.devcontainerSpawn } : {},
+      logger
+    });
   }
-  return result;
+  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
+  );
+}
+function runStop(opts) {
+  return runComposeAction(
+    (service) => ["stop", ...service ? [service] : []],
+    opts
+  );
+}
+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
@@ -4271,13 +4544,19 @@ function formatUnreachableReposError(failures) {
     lines.push(headerForKind(kind));
     for (const e of entries) {
       lines.push(`  \u2022 ${e.url}`);
+      if (e.detail) {
+        for (const detailLine of e.detail.split("\n")) {
+          const trimmed = detailLine.trim();
+          if (trimmed) lines.push(`      git: ${trimmed}`);
+        }
+      }
     }
     for (const advice of adviceForKind(kind)) {
       lines.push(`    - ${advice}`);
     }
     lines.push("");
   }
-  lines.push(`Then re-run ${cyan("monoceros apply")}.`);
+  lines.push(`Then re-run ${cyan2("monoceros apply")}.`);
   return lines.join("\n");
 }
 function headerForKind(kind) {
@@ -4317,11 +4596,85 @@ function adviceForKind(kind) {
   }
 }
 
-// src/devcontainer/docker-mode.ts
+// src/devcontainer/repo-clone.ts
 import { spawn as spawn7 } from "child_process";
+import { existsSync as existsSync7, promises as fs10 } from "fs";
+import path13 from "path";
+var realGitClone = (url, dest) => {
+  return new Promise((resolve, reject) => {
+    const child = spawn7("git", ["clone", "--", url, dest], {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (c) => {
+      stdout += c.toString();
+    });
+    child.stderr.on("data", (c) => {
+      stderr += c.toString();
+    });
+    child.on("error", reject);
+    child.on(
+      "exit",
+      (code) => resolve({ stdout, stderr, exitCode: code ?? 0 })
+    );
+  });
+};
+async function cloneReposHostSide(containerRoot, repos, options = {}) {
+  const spawnFn = options.spawn ?? realGitClone;
+  const results = [];
+  for (const repo of repos) {
+    const dest = path13.join(containerRoot, "projects", repo.path);
+    if (existsSync7(dest)) {
+      results.push({ path: repo.path, url: repo.url, status: "skipped" });
+      continue;
+    }
+    await fs10.mkdir(path13.dirname(dest), { recursive: true });
+    let r;
+    try {
+      r = await spawnFn(repo.url, dest);
+    } catch (err) {
+      results.push({
+        path: repo.path,
+        url: repo.url,
+        status: "failed",
+        detail: err instanceof Error ? err.message : String(err)
+      });
+      continue;
+    }
+    results.push(
+      r.exitCode === 0 ? { path: repo.path, url: repo.url, status: "cloned" } : {
+        path: repo.path,
+        url: repo.url,
+        status: "failed",
+        detail: r.stderr.trim()
+      }
+    );
+  }
+  return results;
+}
+function formatCloneFailuresError(failures) {
+  const lines = failures.length === 1 ? [`Failed to clone declared repo: ${failures[0].url}`, ""] : [`Failed to clone ${failures.length} declared repos:`, ""];
+  for (const f of failures) {
+    lines.push(`  \u2022 ${f.url} \u2192 projects/${f.path}`);
+    if (f.detail) lines.push(`    ${f.detail}`);
+  }
+  lines.push("");
+  lines.push(
+    "Reachability was confirmed earlier, so this is usually a local issue"
+  );
+  lines.push(
+    "(disk space, a leftover non-empty target dir). Fix it and re-run " + cyan2("monoceros apply") + "."
+  );
+  return lines.join("\n");
+}
+
+// src/devcontainer/docker-mode.ts
+import { spawn as spawn8 } from "child_process";
 var realDockerInfo = () => {
   return new Promise((resolve, reject) => {
-    const child = spawn7(
+    const child = spawn8(
       "docker",
       ["info", "--format", "{{json .SecurityOptions}}"],
       {
@@ -4360,14 +4713,14 @@ function formatRootlessNotSupportedError() {
     ``,
     `To fix, switch back to standard rootful Docker:`,
     ``,
-    cyan(
+    cyan2(
       `  systemctl --user stop docker.service docker.socket 2>/dev/null || true`
     ),
-    cyan(`  dockerd-rootless-setuptool.sh uninstall`),
-    cyan(`  rootlesskit rm -rf ~/.local/share/docker`),
-    cyan(`  unset DOCKER_HOST DOCKER_CONTEXT`),
-    cyan(`  sudo systemctl enable --now docker`),
-    cyan(`  sudo usermod -aG docker $USER`),
+    cyan2(`  dockerd-rootless-setuptool.sh uninstall`),
+    cyan2(`  rootlesskit rm -rf ~/.local/share/docker`),
+    cyan2(`  unset DOCKER_HOST DOCKER_CONTEXT`),
+    cyan2(`  sudo systemctl enable --now docker`),
+    cyan2(`  sudo usermod -aG docker $USER`),
     ``,
     `If you added DOCKER_HOST or DOCKER_CONTEXT to ~/.bashrc /`,
     `~/.profile (the rootless setup may have suggested it), remove`,
@@ -4380,13 +4733,13 @@ function formatRootlessNotSupportedError() {
 }
 
 // src/devcontainer/identity.ts
-import { spawn as spawn8 } from "child_process";
-import { promises as fs10 } from "fs";
-import path12 from "path";
+import { spawn as spawn9 } from "child_process";
+import { promises as fs11 } from "fs";
+import path14 from "path";
 import { consola as consola10 } from "consola";
 var realGitConfigGet = (key) => {
   return new Promise((resolve, reject) => {
-    const child = spawn8("git", ["config", "--global", "--get", key], {
+    const child = spawn9("git", ["config", "--global", "--get", key], {
       stdio: ["ignore", "pipe", "inherit"]
     });
     let stdout = "";
@@ -4496,8 +4849,8 @@ async function resolveIdentityWithPrompt(options = {}) {
   };
 }
 async function collectGitIdentity(devContainerRoot, options = {}) {
-  const gitconfigDir = path12.join(devContainerRoot, ".monoceros");
-  const gitconfigPath = path12.join(gitconfigDir, "gitconfig");
+  const gitconfigDir = path14.join(devContainerRoot, ".monoceros");
+  const gitconfigPath = path14.join(gitconfigDir, "gitconfig");
   const logger = options.logger ?? { info: () => {
   }, warn: () => {
   } };
@@ -4510,8 +4863,8 @@ async function collectGitIdentity(devContainerRoot, options = {}) {
   const lines = ["[user]"];
   if (resolved.name !== void 0) lines.push(`	name = ${resolved.name}`);
   if (resolved.email !== void 0) lines.push(`	email = ${resolved.email}`);
-  await fs10.mkdir(gitconfigDir, { recursive: true });
-  await fs10.writeFile(gitconfigPath, lines.join("\n") + "\n");
+  await fs11.mkdir(gitconfigDir, { recursive: true });
+  await fs11.writeFile(gitconfigPath, lines.join("\n") + "\n");
   return {
     ...resolved.name !== void 0 ? { name: resolved.name } : {},
     ...resolved.email !== void 0 ? { email: resolved.email } : {},
@@ -4554,7 +4907,7 @@ async function readKeyFromHost(spawnFn, key, logger) {
 }
 async function readExistingGitconfig(filePath) {
   try {
-    const content = await fs10.readFile(filePath, "utf8");
+    const content = await fs11.readFile(filePath, "utf8");
     const result = {};
     const nameMatch = /^\s*name\s*=\s*(.+?)\s*$/m.exec(content);
     const emailMatch = /^\s*email\s*=\s*(.+?)\s*$/m.exec(content);
@@ -4587,7 +4940,7 @@ ${sectionLine(label)}
     );
   }
   const ymlPath = containerConfigPath(opts.name, home);
-  if (!existsSync6(ymlPath)) {
+  if (!existsSync8(ymlPath)) {
     throw new Error(
       `No such config: ${ymlPath}. Run \`monoceros init <template> ${opts.name}\` first.`
     );
@@ -4604,6 +4957,20 @@ ${sectionLine(label)}
       globalConfig?.defaults?.features ?? {}
     )
   );
+  const envPath = containerEnvPath(opts.name, home);
+  await ensureEnvGitignored(containerConfigsDir(home));
+  const envVars = readEnvFile(envPath);
+  const interpServices = interpolateServices(createOpts.services, envVars);
+  const interpFeatures = interpolateFeatures(
+    createOpts.features ?? {},
+    envVars
+  );
+  const missingVars = [...interpServices.missing, ...interpFeatures.missing];
+  if (missingVars.length > 0) {
+    throw new Error(formatMissingVarsError(missingVars, prettyPath(envPath)));
+  }
+  createOpts.services = interpServices.services;
+  if (createOpts.features) createOpts.features = interpFeatures.features;
   validateOptions(createOpts);
   logger.success(`yml validated ${dim(`(${prettyPath(ymlPath)})`)}`);
   const hasRepos = (createOpts.repos ?? []).length > 0;
@@ -4658,7 +5025,7 @@ ${sectionLine(label)}
   if (dockerMode === "rootless") {
     throw new Error(formatRootlessNotSupportedError());
   }
-  await fs11.mkdir(targetDir, { recursive: true });
+  await fs12.mkdir(targetDir, { recursive: true });
   await writeScaffold(createOpts, targetDir, { dockerMode });
   await writeStateFile(
     targetDir,
@@ -4669,10 +5036,27 @@ ${sectionLine(label)}
     })
   );
   logger.success(`materialized into ${prettyPath(targetDir)}`);
+  const reposToClone = createOpts.repos ?? [];
+  if (reposToClone.length > 0) {
+    const cloneResults = await cloneReposHostSide(targetDir, reposToClone, {
+      ...opts.cloneSpawn ? { spawn: opts.cloneSpawn } : {}
+    });
+    for (const r of cloneResults) {
+      if (r.status === "cloned") {
+        logger.success(`cloned ${cyan2(r.path)} ${dim(`(${r.url})`)}`);
+      } else if (r.status === "skipped") {
+        logger.info(`projects/${r.path} already present \u2014 skipped clone`);
+      }
+    }
+    const cloneFailures = cloneResults.filter((r) => r.status === "failed");
+    if (cloneFailures.length > 0) {
+      throw new Error(formatCloneFailuresError(cloneFailures));
+    }
+  }
   section("Container");
   const featureRefs = parsed.config.features.map((f) => f.ref);
   if (featureRefs.length > 0) {
-    logger.info(`Features: ${featureRefs.map((r) => cyan(r)).join(", ")}`);
+    logger.info(`Features: ${featureRefs.map((r) => cyan2(r)).join(", ")}`);
   }
   logger.info(
     dim(
@@ -4695,14 +5079,8 @@ ${sectionLine(label)}
         hostPort: proxyHostPort(globalConfig),
         logger
       });
-      await kickProxyReload({
-        ...opts.proxyDocker ? { docker: opts.proxyDocker } : {}
-      });
     } else {
       await removeDynamicConfig(opts.name, { monocerosHome: home });
-      await kickProxyReload({
-        ...opts.proxyDocker ? { docker: opts.proxyDocker } : {}
-      });
     }
   } catch (err) {
     logger.warn?.(
@@ -4717,13 +5095,13 @@ ${sectionLine(label)}
   });
   if (exitCode === 0) {
     section("Next steps");
-    logger.info(`  ${cyan(`monoceros shell ${opts.name}`)}`);
+    logger.info(`  ${cyan2(`monoceros shell ${opts.name}`)}`);
   }
   return { targetDir, configPath: ymlPath, containerExitCode: exitCode };
 }
 async function assertSafeTargetDir(targetDir, expectedOrigin) {
-  if (!existsSync6(targetDir)) return;
-  const entries = await fs11.readdir(targetDir);
+  if (!existsSync8(targetDir)) return;
+  const entries = await fs12.readdir(targetDir);
   if (entries.length === 0) return;
   const state = await readStateFile(targetDir);
   if (state) {
@@ -4793,7 +5171,7 @@ async function persistPromptedIdentity(prompted, ymlPath, home, logger) {
   }
   if (wantContainer) {
     try {
-      const text = await fs11.readFile(ymlPath, "utf8");
+      const text = await fs12.readFile(ymlPath, "utf8");
       const parsed = parseConfig(text, ymlPath);
       const changed = setContainerGitUserInDoc(parsed.doc, {
         name: prompted.name,
@@ -4801,7 +5179,7 @@ async function persistPromptedIdentity(prompted, ymlPath, home, logger) {
       });
       if (changed) {
         const out = stringifyConfig(parsed.doc);
-        await fs11.writeFile(ymlPath, out, "utf8");
+        await fs12.writeFile(ymlPath, out, "utf8");
         logger.info(
           `Saved identity in this container \u2014 wrote git.user into ${prettyPath(ymlPath)}.`
         );
@@ -4815,7 +5193,7 @@ async function persistPromptedIdentity(prompted, ymlPath, home, logger) {
 }
 
 // src/version.ts
-var CLI_VERSION = true ? "1.11.11" : "dev";
+var CLI_VERSION = true ? "1.13.0" : "dev";
 
 // src/commands/_dispatch.ts
 import { consola as consola12 } from "consola";
@@ -4975,8 +5353,8 @@ var completionCommand = defineCommand9({
 import { defineCommand as defineCommand10 } from "citty";
 
 // src/completion/resolve.ts
-import { existsSync as existsSync7, promises as fs12 } from "fs";
-import path13 from "path";
+import { existsSync as existsSync9, promises as fs13 } from "fs";
+import path15 from "path";
 async function resolveCompletions(line, point, opts = {}) {
   const { prev, current } = parseCompletionLine(line, point);
   const ctx = { prev, current, opts };
@@ -5124,15 +5502,11 @@ function filterPrefix(values, fragment) {
 }
 async function listContainerNames(ctx) {
   const home = ctx.opts.monocerosHome ?? monocerosHome();
-  const dir = path13.join(home, "container-configs");
-  if (!existsSync7(dir)) return [];
-  const entries = await fs12.readdir(dir);
+  const dir = path15.join(home, "container-configs");
+  if (!existsSync9(dir)) return [];
+  const entries = await fs13.readdir(dir);
   return entries.filter((e) => e.endsWith(".yml")).map((e) => e.slice(0, -".yml".length)).sort();
 }
-async function listAllCatalogComponents() {
-  const catalog = await loadComponentCatalog();
-  return [...catalog.keys()].sort();
-}
 async function listFeatureComponents() {
   const catalog = await loadComponentCatalog();
   return [...catalog.values()].filter((c) => c.file.category === "feature").map((c) => c.name).sort();
@@ -5234,8 +5608,14 @@ var COMMAND_SPECS = {
     // flag suggestions.
     positionalCount: 1,
     flags: {
-      "--with": { type: "value", values: () => listAllCatalogComponents() },
-      "--with-repo": { type: "value" },
+      "--with-languages": { type: "value", values: () => listLanguageNames() },
+      "--with-features": {
+        type: "value",
+        values: () => listFeatureComponents()
+      },
+      "--with-services": { type: "value", values: () => listServiceNames() },
+      "--with-apt-packages": { type: "value" },
+      "--with-repos": { type: "value" },
       "--with-ports": { type: "value" }
     }
   },
@@ -5379,22 +5759,22 @@ import { defineCommand as defineCommand11 } from "citty";
 import { consola as consola14 } from "consola";
 
 // src/init/index.ts
-import { existsSync as existsSync8, promises as fs13 } from "fs";
+import { existsSync as existsSync10, promises as fs14 } from "fs";
+import path16 from "path";
 import { consola as consola13 } from "consola";
 
 // src/init/generator.ts
 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);
+function generateComposedYml(name, composed, lookupManifest, repoUrls = [], ports = []) {
   const lines = [];
   pushHeader(lines, SCHEMA_HEADER_ACTIVE, name);
   lines.push("");
   lines.push("schemaVersion: 1");
   lines.push(`name: ${name}`);
   lines.push("");
-  if (merged.languages.length > 0) {
+  if (composed.languages.length > 0) {
     pushSectionHeader(
       lines,
       LANGUAGES_HEADER,
@@ -5402,10 +5782,21 @@ function generateComposedYml(name, components, lookupManifest, repoUrls = [], po
       false
     );
     lines.push("languages:");
-    for (const lang of merged.languages) lines.push(`  - ${lang}`);
+    for (const lang of composed.languages) lines.push(`  - ${lang}`);
     lines.push("");
   }
-  if (merged.services.length > 0) {
+  if (composed.aptPackages.length > 0) {
+    pushSectionHeader(
+      lines,
+      APT_PACKAGES_HEADER,
+      /* commented */
+      false
+    );
+    lines.push("aptPackages:");
+    for (const pkg of composed.aptPackages) lines.push(`  - ${pkg}`);
+    lines.push("");
+  }
+  if (composed.services.length > 0) {
     pushSectionHeader(
       lines,
       SERVICES_HEADER,
@@ -5413,10 +5804,10 @@ function generateComposedYml(name, components, lookupManifest, repoUrls = [], po
       false
     );
     lines.push("services:");
-    for (const svc of merged.services) lines.push(`  - ${svc}`);
+    for (const svc of composed.services) pushServiceEntry(lines, svc);
     lines.push("");
   }
-  if (merged.features.length > 0) {
+  if (composed.features.length > 0) {
     pushSectionHeader(
       lines,
       FEATURES_HEADER_ACTIVE,
@@ -5424,7 +5815,7 @@ function generateComposedYml(name, components, lookupManifest, repoUrls = [], po
       false
     );
     lines.push("features:");
-    for (const f of merged.features) {
+    for (const f of composed.features) {
       lines.push("");
       renderFeatureBlock(
         lines,
@@ -5505,7 +5896,9 @@ function generateDocumentedYml(name, catalog, lookupManifest, repoUrls = [], por
     lines.push("# services:");
     for (const c of byCategory.service) {
       for (const svc of c.file.contributes.services ?? []) {
-        lines.push(`#   - ${svc}`);
+        const body = renderServiceObjectBody(expandCuratedService(svc));
+        lines.push(`#   - ${body[0]}`);
+        for (const line of body.slice(1)) lines.push(`#     ${line}`);
       }
     }
     lines.push("");
@@ -5612,6 +6005,22 @@ function generateDocumentedYml(name, catalog, lookupManifest, repoUrls = [], por
 }
 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 APT_PACKAGES_HEADER = "Debian/Ubuntu apt packages installed in the dev-container at build time. No curated list \u2014 any apt package name works; an invalid name surfaces as an apt error during build.";
+function pushServiceEntry(out, svc) {
+  if (svc.kind === "custom") {
+    const { bodyLines, comment } = renderCustomService(
+      svc.name,
+      svc.image ?? ""
+    );
+    out.push(`  - ${bodyLines[0]}`);
+    for (const line of bodyLines.slice(1)) out.push(`    ${line}`);
+    for (const cl of comment.split("\n")) out.push(`    #${cl}`);
+    return;
+  }
+  const body = renderServiceObjectBody(expandCuratedService(svc.name));
+  out.push(`  - ${body[0]}`);
+  for (const line of body.slice(1)) out.push(`    ${line}`);
+}
 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`.";
@@ -5626,15 +6035,15 @@ function renderFeatureBlock(out, feature, summary, commented) {
   out.push(`${yamlPrefix}  - ref: ${feature.ref}`);
   const options = feature.options ?? {};
   const activeKeys = Object.entries(options);
-  const hintKeys = (summary?.optionHints ?? []).filter((h) => !(h in options));
-  if (activeKeys.length === 0 && hintKeys.length === 0) return;
+  const hints = featureOptionHints(summary, feature.ref, Object.keys(options));
+  if (activeKeys.length === 0 && hints.length === 0) return;
   if (commented) {
     out.push(`${yamlPrefix}    options:`);
     for (const [key, value] of activeKeys) {
       out.push(`${yamlPrefix}      ${key}: ${renderScalarValue(value)}`);
     }
-    for (const key of hintKeys) {
-      out.push(`${yamlPrefix}      ${key}:`);
+    for (const hint of hints) {
+      out.push(`${yamlPrefix}      ${hint.key}: ${hint.placeholder}`);
     }
     return;
   }
@@ -5644,10 +6053,10 @@ function renderFeatureBlock(out, feature, summary, commented) {
       out.push(`      ${key}: ${renderScalarValue(value)}`);
     }
   }
-  if (hintKeys.length > 0) {
+  if (hints.length > 0) {
     out.push(`    # options:`);
-    for (const key of hintKeys) {
-      out.push(`    #   ${key}:`);
+    for (const hint of hints) {
+      out.push(`    #   ${hint.key}: ${hint.placeholder}`);
     }
   }
 }
@@ -5701,7 +6110,7 @@ async function runInit(opts) {
     );
   }
   const dest = containerConfigPath(opts.name, home);
-  if (existsSync8(dest)) {
+  if (existsSync10(dest)) {
     throw new Error(
       `Config already exists: ${dest}. Delete it manually before re-running \`monoceros init\` \u2014 this protects any hand-edits.`
     );
@@ -5771,15 +6180,28 @@ async function runInit(opts) {
     });
   }
   let text;
-  const requested = opts.with ?? [];
-  if (requested.length === 0) {
+  const composed = resolveComposedInit(catalog, {
+    languages: opts.languages ?? [],
+    features: opts.features ?? [],
+    services: opts.services ?? [],
+    aptPackages: opts.aptPackages ?? []
+  });
+  const anyComposed = composed.languages.length > 0 || composed.features.length > 0 || composed.services.length > 0 || composed.aptPackages.length > 0;
+  if (!anyComposed) {
     text = generateDocumentedYml(opts.name, catalog, lookup, repos, ports);
   } else {
-    const components = resolveComponents(catalog, requested);
-    text = generateComposedYml(opts.name, components, lookup, repos, ports);
-  }
-  await fs13.mkdir(containerConfigsDir(home), { recursive: true });
-  await fs13.writeFile(dest, text, "utf8");
+    text = generateComposedYml(opts.name, composed, lookup, repos, ports);
+  }
+  await fs14.mkdir(containerConfigsDir(home), { recursive: true });
+  await ensureEnvGitignored(containerConfigsDir(home));
+  await fs14.writeFile(dest, text, "utf8");
+  const envPath = containerEnvPath(opts.name, home);
+  const featureVars = composed.features.flatMap(
+    (f) => featureOptionHints(lookup(f.ref), f.ref, Object.keys(f.options ?? {})).map(
+      (h) => h.envVar
+    )
+  );
+  await ensureEnvVars(envPath, opts.name, featureVars);
   if (promptedIdentity?.prompted) {
     const { name, email, scope } = promptedIdentity.prompted;
     if (scope === "g" || scope === "b") {
@@ -5809,11 +6231,11 @@ async function runInit(opts) {
     }
     if (scope === "c" || scope === "b") {
       try {
-        const written = await fs13.readFile(dest, "utf8");
+        const written = await fs14.readFile(dest, "utf8");
         const parsed = parseConfig(written, dest);
         const changed = setContainerGitUserInDoc(parsed.doc, { name, email });
         if (changed) {
-          await fs13.writeFile(dest, stringifyConfig(parsed.doc), "utf8");
+          await fs14.writeFile(dest, stringifyConfig(parsed.doc), "utf8");
           logger.info(
             `Saved identity in ${prettyPath(dest)} (container-level git.user).`
           );
@@ -5825,29 +6247,136 @@ async function runInit(opts) {
       }
     }
   }
-  const documented = requested.length === 0;
-  const displayPath = prettyPath(dest);
+  const documented = !anyComposed;
+  const ymlRel = path16.relative(home, dest);
+  const envRel = path16.relative(home, envPath);
   if (documented) {
-    logger.success(
-      `Wrote documented default to ${displayPath}. Un-comment what you need, then \`monoceros apply ${opts.name}\`.`
+    logger.success(`Wrote documented default to ${ymlRel} and ${envRel}.`);
+    logger.info(
+      `Un-comment what you need, then \`monoceros apply ${opts.name}\`.`
     );
   } else {
-    logger.success(
-      `Composed ${requested.length} component(s) into ${displayPath}: ${requested.join(", ")}`
-    );
+    logger.success(`Composed into ${ymlRel} and ${envRel}.`);
     logger.info(
-      `Edit the file if you need to tweak, then \`monoceros apply ${opts.name}\`.`
+      `Edit the files if you need to tweak, then \`monoceros apply ${opts.name}\`.`
     );
   }
   return { configPath: dest, documented };
 }
+function resolveComposedInit(catalog, raw) {
+  return {
+    languages: resolveInitLanguages(raw.languages),
+    aptPackages: resolveInitAptPackages(raw.aptPackages),
+    services: resolveInitServices(raw.services),
+    features: resolveInitFeatures(catalog, raw.features)
+  };
+}
+function resolveInitLanguages(entries) {
+  const known = new Set(knownLanguages());
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const unknown = [];
+  for (const raw of entries) {
+    const e = raw.trim();
+    if (!e || seen.has(e)) continue;
+    const spec = parseLanguageSpec(e);
+    if (!spec || !known.has(spec.name)) {
+      unknown.push(e);
+      continue;
+    }
+    seen.add(e);
+    out.push(e);
+  }
+  if (unknown.length > 0) {
+    throw new Error(
+      `Unknown language${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}. Known: ${knownLanguages().join(", ")}.`
+    );
+  }
+  return out;
+}
+function resolveInitAptPackages(entries) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const bad = [];
+  for (const raw of entries) {
+    const e = raw.trim();
+    if (!e || seen.has(e)) continue;
+    if (!REGEX.aptPackage.test(e)) {
+      bad.push(e);
+      continue;
+    }
+    seen.add(e);
+    out.push(e);
+  }
+  if (bad.length > 0) {
+    throw new Error(
+      `Invalid apt package name${bad.length > 1 ? "s" : ""}: ${bad.join(", ")}. Expected lowercase alphanumeric plus '.+-'.`
+    );
+  }
+  return out;
+}
+function resolveInitServices(entries) {
+  const out = [];
+  const byName = /* @__PURE__ */ new Map();
+  for (const raw of entries) {
+    const e = raw.trim();
+    if (!e) continue;
+    const svc = isCuratedService(e) ? { kind: "curated", name: e } : { kind: "custom", name: deriveServiceName(e), image: e };
+    const existing = byName.get(svc.name);
+    if (existing) {
+      if (existing.kind === svc.kind && existing.image === svc.image) continue;
+      throw new Error(
+        `Two --with-services entries resolve to the service name '${svc.name}'. Add one after init with \`monoceros add-service ${"<name>"} <image> --as=<other>\`.`
+      );
+    }
+    byName.set(svc.name, svc);
+    out.push(svc);
+  }
+  return out;
+}
+function resolveInitFeatures(catalog, entries) {
+  const byRef = /* @__PURE__ */ new Map();
+  const unknown = [];
+  for (const raw of entries) {
+    const e = raw.trim();
+    if (!e) continue;
+    if (REGEX.featureRef.test(e)) {
+      if (!byRef.has(e)) byRef.set(e, { ref: e, options: {} });
+      continue;
+    }
+    const c = catalog.get(e);
+    if (!c || c.file.category !== "feature") {
+      unknown.push(e);
+      continue;
+    }
+    for (const f of c.file.contributes.features ?? []) {
+      const existing = byRef.get(f.ref);
+      if (!existing) {
+        byRef.set(f.ref, { ref: f.ref, options: { ...f.options ?? {} } });
+      } else {
+        existing.options = mergeFeatureOptions(
+          existing.options,
+          f.options ?? {}
+        );
+      }
+    }
+  }
+  if (unknown.length > 0) {
+    const featureNames = [...catalog.values()].filter((c) => c.file.category === "feature").map((c) => c.name).sort();
+    throw new Error(
+      `Unknown feature${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}.
+Use a catalog short name (${featureNames.join(", ")}) or a full OCI ref (ghcr.io/\u2026/<name>:<tag>).`
+    );
+  }
+  return [...byRef.values()];
+}
 
 // src/commands/init.ts
 var initCommand = defineCommand11({
   meta: {
     name: "init",
     group: "lifecycle",
-    description: "Create a fresh container-config yml at .local/container-configs/<name>.yml. Without --with, the file is a documented default with every component commented out. With --with=<names>, the named components are composed into an active, immediately-applyable yml. Then run `monoceros apply <name>`."
+    description: "Create a fresh container-config yml at <MONOCEROS_HOME>/container-configs/<name>.yml. Without any --with-* flag, the file is a documented default with every component commented out. With --with-languages / --with-features / --with-services / --with-apt-packages, the named pieces are composed into an active, immediately-applyable yml. Then run `monoceros apply <name>`."
   },
   args: {
     name: {
@@ -5855,14 +6384,29 @@ var initCommand = defineCommand11({
       description: "Config name. The yml lands at <MONOCEROS_HOME>/container-configs/<name>.yml and becomes the source-of-truth for `monoceros apply <name>`.",
       required: true
     },
-    with: {
+    "with-languages": {
+      type: "string",
+      description: "Language runtimes to install, comma-separated or repeated, e.g. --with-languages=java,node. Optional :version (java:17). Curated catalog only \u2014 see `monoceros list-components`.",
+      required: false
+    },
+    "with-features": {
+      type: "string",
+      description: "Features (AI tools, language CLIs, \u2026), comma-separated or repeated. Catalog short name (claude, atlassian/twg) or a full OCI ref (ghcr.io/foo/bar:1).",
+      required: false
+    },
+    "with-services": {
+      type: "string",
+      description: "Backing services, comma-separated or repeated. Curated name (postgres, mysql, redis) \u2192 full editable block; any other image (rustfs/rustfs:latest) \u2192 name + image + commented scaffold.",
+      required: false
+    },
+    "with-apt-packages": {
       type: "string",
-      description: "Comma-separated list of component names to compose, e.g. 'node,postgres,github,claude'. Sub-components use a slash, e.g. 'atlassian/twg'. When omitted, init writes a documented default with every catalog component commented out.",
+      description: "Debian/Ubuntu apt packages to install, comma-separated or repeated, e.g. --with-apt-packages=openssl,make. No curated list.",
       required: false
     },
-    "with-repo": {
+    "with-repos": {
       type: "string",
-      description: "Git URL of a repo to clone into projects/ on first apply. Repeatable: pass --with-repo=URL1 --with-repo=URL2 for multiple repos. Folder name derived from URL (foo.git \u2192 projects/foo/); use `monoceros add-repo --path=...` post-init for subfolder paths.",
+      description: "Git URLs to clone into projects/ on first apply, comma-separated or repeated. Folder name derived from URL (foo.git \u2192 projects/foo/); use `monoceros add-repo --path=...` post-init for subfolder paths. Canonical hosts only (github.com / gitlab.com / bitbucket.org).",
       required: false
     },
     "with-ports": {
@@ -5873,14 +6417,20 @@ var initCommand = defineCommand11({
   },
   async run({ args, rawArgs }) {
     try {
-      const withList = collectWithList(args.with, rawArgs);
-      const withRepoList = collectWithRepoList(rawArgs);
-      const withPortsList = collectWithPortsList(args["with-ports"], rawArgs);
+      const languages = collectListFlag("--with-languages", rawArgs);
+      const features = collectListFlag("--with-features", rawArgs);
+      const services = collectListFlag("--with-services", rawArgs);
+      const aptPackages = collectListFlag("--with-apt-packages", rawArgs);
+      const repos = collectListFlag("--with-repos", rawArgs);
+      const ports = collectWithPortsList(args["with-ports"], rawArgs);
       await runInit({
         name: args.name,
-        ...withList ? { with: withList } : {},
-        ...withRepoList.length > 0 ? { withRepo: withRepoList } : {},
-        ...withPortsList && withPortsList.length > 0 ? { withPorts: withPortsList } : {}
+        ...languages.length > 0 ? { languages } : {},
+        ...features.length > 0 ? { features } : {},
+        ...services.length > 0 ? { services } : {},
+        ...aptPackages.length > 0 ? { aptPackages } : {},
+        ...repos.length > 0 ? { withRepo: repos } : {},
+        ...ports && ports.length > 0 ? { withPorts: ports } : {}
       });
     } catch (err) {
       consola14.error(err instanceof Error ? err.message : String(err));
@@ -5888,6 +6438,30 @@ var initCommand = defineCommand11({
     }
   }
 });
+function collectListFlag(flag, rawArgs) {
+  const eq = `${flag}=`;
+  const pieces = [];
+  for (let i = 0; i < rawArgs.length; i += 1) {
+    const t = rawArgs[i];
+    let scanStart = -1;
+    if (t === flag) {
+      scanStart = i + 1;
+    } else if (t.startsWith(eq)) {
+      pieces.push(t.slice(eq.length));
+      scanStart = i + 1;
+    }
+    if (scanStart < 0) continue;
+    let j = scanStart;
+    while (j < rawArgs.length) {
+      const u = rawArgs[j];
+      if (u.startsWith("-")) break;
+      pieces.push(u);
+      j += 1;
+    }
+    i = j - 1;
+  }
+  return pieces.flatMap((s) => s.split(",")).map((s) => s.trim()).filter((s) => s.length > 0);
+}
 function collectWithPortsList(_withPortsArg, rawArgs) {
   const pieces = [];
   for (let i = 0; i < rawArgs.length; i += 1) {
@@ -5923,43 +6497,6 @@ function collectWithPortsList(_withPortsArg, rawArgs) {
   }
   return out;
 }
-function collectWithRepoList(rawArgs) {
-  const urls = [];
-  for (let i = 0; i < rawArgs.length; i += 1) {
-    const t = rawArgs[i];
-    if (t === "--with-repo") {
-      const next = rawArgs[i + 1];
-      if (typeof next === "string" && !next.startsWith("-")) {
-        urls.push(next);
-        i += 1;
-      }
-    } else if (t.startsWith("--with-repo=")) {
-      urls.push(t.slice("--with-repo=".length));
-    }
-  }
-  return urls;
-}
-function collectWithList(withArg, rawArgs) {
-  if (typeof withArg !== "string" || withArg.trim().length === 0) {
-    return void 0;
-  }
-  let combined = withArg.trim();
-  const startIdx = rawArgs.findIndex(
-    (t) => t === "--with" || t.startsWith("--with=")
-  );
-  if (startIdx >= 0) {
-    let scanFrom = startIdx + 1;
-    if (rawArgs[startIdx] === "--with") scanFrom += 1;
-    for (let i = scanFrom; i < rawArgs.length; i += 1) {
-      const t = rawArgs[i];
-      if (t.startsWith("--") || t === "-h" || t === "--help") break;
-      const sep = combined.endsWith(",") ? "" : ",";
-      combined += sep + t;
-    }
-  }
-  const pieces = combined.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
-  return pieces.length > 0 ? pieces : void 0;
-}
 
 // src/commands/list-components.ts
 import { defineCommand as defineCommand12 } from "citty";
@@ -6247,8 +6784,8 @@ import { consola as consola20 } from "consola";
 import { createInterface } from "readline/promises";
 
 // src/remove/index.ts
-import { existsSync as existsSync9, promises as fs14 } from "fs";
-import path14 from "path";
+import { existsSync as existsSync11, promises as fs15 } from "fs";
+import path17 from "path";
 import { consola as consola19 } from "consola";
 async function runRemove(opts) {
   const home = opts.monocerosHome ?? monocerosHome();
@@ -6263,9 +6800,11 @@ async function runRemove(opts) {
     );
   }
   const ymlPath = containerConfigPath(opts.name, home);
+  const envPath = containerEnvPath(opts.name, home);
   const containerPath = containerDir(opts.name, home);
-  const hasYml = existsSync9(ymlPath);
-  const hasContainer = existsSync9(containerPath);
+  const hasYml = existsSync11(ymlPath);
+  const hasEnv = existsSync11(envPath);
+  const hasContainer = existsSync11(containerPath);
   if (!hasYml && !hasContainer) {
     throw new Error(
       `Nothing to remove for '${opts.name}': neither ${ymlPath} nor ${containerPath} exists.`
@@ -6277,7 +6816,7 @@ async function runRemove(opts) {
     projectName,
     filters: [
       `label=com.docker.compose.project=${projectName}`,
-      `label=devcontainer.local_folder=${dockerLocalFolderLabel(containerPath)}`,
+      `label=devcontainer.local_folder=${containerPath}`,
       `name=^${projectName}-`,
       `name=^vsc-${opts.name}-`
     ],
@@ -6289,24 +6828,30 @@ async function runRemove(opts) {
   let backupPath = null;
   if (!opts.noBackup && (hasYml || hasContainer)) {
     const ts = (opts.now ?? /* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-    backupPath = path14.join(home, "container-backups", `${opts.name}-${ts}`);
-    await fs14.mkdir(backupPath, { recursive: true });
+    backupPath = path17.join(home, "container-backups", `${opts.name}-${ts}`);
+    await fs15.mkdir(backupPath, { recursive: true });
     if (hasYml) {
-      await fs14.copyFile(ymlPath, path14.join(backupPath, `${opts.name}.yml`));
+      await fs15.copyFile(ymlPath, path17.join(backupPath, `${opts.name}.yml`));
+    }
+    if (hasEnv) {
+      await fs15.copyFile(envPath, path17.join(backupPath, `${opts.name}.env`));
     }
     if (hasContainer) {
-      await fs14.cp(containerPath, path14.join(backupPath, "container"), {
+      await fs15.cp(containerPath, path17.join(backupPath, "container"), {
         recursive: true
       });
     }
     logger.info(`Backup written to ${prettyPath(backupPath)}.`);
   }
   if (hasYml) {
-    await fs14.rm(ymlPath, { force: true });
+    await fs15.rm(ymlPath, { force: true });
+  }
+  if (hasEnv) {
+    await fs15.rm(envPath, { force: true });
   }
   if (hasContainer) {
     try {
-      await fs14.rm(containerPath, { recursive: true, force: true });
+      await fs15.rm(containerPath, { recursive: true, force: true });
     } catch (err) {
       const code = err.code;
       if (code !== "EACCES" && code !== "EPERM") {
@@ -6332,7 +6877,7 @@ async function runRemove(opts) {
           `docker-based cleanup of ${containerPath} exited ${exit}. Inspect with \`sudo ls -la ${containerPath}\` and clean manually.`
         );
       }
-      await fs14.rm(containerPath, { recursive: true, force: true });
+      await fs15.rm(containerPath, { recursive: true, force: true });
     }
   }
   logger.success(
@@ -6345,9 +6890,6 @@ async function runRemove(opts) {
   }
   try {
     await removeDynamicConfig(opts.name, { monocerosHome: home });
-    await kickProxyReload({
-      ...opts.proxyDocker ? { docker: opts.proxyDocker } : {}
-    });
   } catch (err) {
     logger.warn?.(
       `Could not remove Traefik dynamic config for ${opts.name}: ${err instanceof Error ? err.message : String(err)}. Ignored.`
@@ -6438,8 +6980,8 @@ import { defineCommand as defineCommand18 } from "citty";
 import { consola as consola22 } from "consola";
 
 // src/restore/index.ts
-import { existsSync as existsSync10, promises as fs15 } from "fs";
-import path15 from "path";
+import { existsSync as existsSync12, promises as fs16 } from "fs";
+import path18 from "path";
 import { consola as consola21 } from "consola";
 async function runRestore(opts) {
   const home = opts.monocerosHome ?? monocerosHome();
@@ -6447,15 +6989,15 @@ async function runRestore(opts) {
     info: (msg) => consola21.info(msg),
     success: (msg) => consola21.success(msg)
   };
-  const backup = path15.resolve(opts.backupPath);
-  if (!existsSync10(backup)) {
+  const backup = path18.resolve(opts.backupPath);
+  if (!existsSync12(backup)) {
     throw new Error(`Backup not found: ${backup}.`);
   }
-  const stat = await fs15.stat(backup);
+  const stat = await fs16.stat(backup);
   if (!stat.isDirectory()) {
     throw new Error(`Backup path is not a directory: ${backup}.`);
   }
-  const entries = await fs15.readdir(backup);
+  const entries = await fs16.readdir(backup);
   const ymlFiles = entries.filter((f) => f.endsWith(".yml"));
   if (ymlFiles.length === 0) {
     throw new Error(
@@ -6469,24 +7011,29 @@ async function runRestore(opts) {
   }
   const ymlFile = ymlFiles[0];
   const name = ymlFile.replace(/\.yml$/, "");
-  const containerInBackup = path15.join(backup, "container");
-  const hasContainer = existsSync10(containerInBackup);
+  const containerInBackup = path18.join(backup, "container");
+  const hasContainer = existsSync12(containerInBackup);
+  const envInBackup = path18.join(backup, `${name}.env`);
+  const hasEnv = existsSync12(envInBackup);
   const destYml = containerConfigPath(name, home);
   const destContainer = containerDir(name, home);
-  if (existsSync10(destYml)) {
+  if (existsSync12(destYml)) {
     throw new Error(
       `Refusing to restore: ${destYml} already exists. Remove the current container first (\`monoceros remove ${name}\`) or rename the existing config.`
     );
   }
-  if (hasContainer && existsSync10(destContainer)) {
+  if (hasContainer && existsSync12(destContainer)) {
     throw new Error(
       `Refusing to restore: ${destContainer} already exists. Remove the current container first (\`monoceros remove ${name}\`).`
     );
   }
-  await fs15.mkdir(containerConfigsDir(home), { recursive: true });
-  await fs15.copyFile(path15.join(backup, ymlFile), destYml);
+  await fs16.mkdir(containerConfigsDir(home), { recursive: true });
+  await fs16.copyFile(path18.join(backup, ymlFile), destYml);
+  if (hasEnv) {
+    await fs16.copyFile(envInBackup, containerEnvPath(name, home));
+  }
   if (hasContainer) {
-    await fs15.cp(containerInBackup, destContainer, { recursive: true });
+    await fs16.cp(containerInBackup, destContainer, { recursive: true });
   }
   logger.success(`Restored '${name}' from ${prettyPath(backup)}.`);
   logger.info(
@@ -6744,8 +7291,8 @@ import { defineCommand as defineCommand24 } from "citty";
 import { consola as consola28 } from "consola";
 
 // src/devcontainer/shell.ts
-import { existsSync as existsSync11 } from "fs";
-import path16 from "path";
+import { existsSync as existsSync13 } from "fs";
+import path19 from "path";
 async function runShell(opts) {
   assertContainerExists(opts.root);
   const spawnFn = opts.spawn ?? spawnDevcontainer;
@@ -6768,7 +7315,7 @@ async function runShell(opts) {
   );
 }
 function assertContainerExists(root) {
-  if (!existsSync11(path16.join(root, ".devcontainer"))) {
+  if (!existsSync13(path19.join(root, ".devcontainer"))) {
     throw new Error(
       `No .devcontainer/ at ${root}. Run \`monoceros apply <name>\` first.`
     );
@@ -6980,15 +7527,15 @@ import { defineCommand as defineCommand29 } from "citty";
 import { consola as consola33 } from "consola";
 
 // src/tunnel/run.ts
-import { spawn as spawn9 } from "child_process";
+import { spawn as spawn10 } from "child_process";
 import { consola as consola32 } from "consola";
 
 // src/tunnel/resolve.ts
-import { existsSync as existsSync12 } from "fs";
-import path17 from "path";
+import { existsSync as existsSync14 } from "fs";
+import path20 from "path";
 async function resolveTunnelTarget(opts) {
   const ymlPath = containerConfigPath(opts.name, opts.monocerosHome);
-  if (!existsSync12(ymlPath)) {
+  if (!existsSync14(ymlPath)) {
     throw new Error(
       `No yml profile for '${opts.name}' at ${ymlPath}. Run \`monoceros init ${opts.name}\` first.`
     );
@@ -6996,13 +7543,13 @@ async function resolveTunnelTarget(opts) {
   const parsed = await readConfig(ymlPath);
   const config = parsed.config;
   const containerRoot = containerDir(opts.name, opts.monocerosHome);
-  if (!existsSync12(containerRoot)) {
+  if (!existsSync14(containerRoot)) {
     throw new Error(
       `Container '${opts.name}' is not materialised at ${containerRoot}. Run \`monoceros apply ${opts.name}\` first.`
     );
   }
-  const composePath = path17.join(containerRoot, ".devcontainer", "compose.yaml");
-  const isCompose = existsSync12(composePath);
+  const composePath = path20.join(containerRoot, ".devcontainer", "compose.yaml");
+  const isCompose = existsSync14(composePath);
   const parsedTarget = parseTargetArg(opts.target, config);
   const docker = opts.docker ?? defaultDockerExec;
   if (isCompose) {
@@ -7021,23 +7568,41 @@ async function resolveTunnelTarget(opts) {
   });
 }
 function parseTargetArg(raw, config) {
+  const colon = raw.indexOf(":");
+  if (colon > 0) {
+    const name = raw.slice(0, colon);
+    const port = Number(raw.slice(colon + 1));
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      throw new Error(
+        `Invalid target '${raw}'. Use <service>:<port> with a numeric port (1\u201365535), a bare port number, or a configured service name.`
+      );
+    }
+    findConfiguredService(config, name);
+    return { kind: "service", service: name, port };
+  }
   const asNumber = Number(raw);
   if (Number.isInteger(asNumber) && asNumber > 0 && asNumber < 65536) {
     return { kind: "port", port: asNumber };
   }
-  const entry2 = SERVICE_CATALOG[raw];
-  if (!entry2) {
-    const candidates = knownServices().join(", ");
+  const match = findConfiguredService(config, raw);
+  if (match.port === void 0) {
     throw new Error(
-      `Unknown service '${raw}'. Known services: ${candidates}. Or pass a port number (e.g. \`monoceros tunnel <name> 8080\`).`
+      `Service '${raw}' declares no port, so tunnel can't know what to forward. Add \`port: <n>\` to the service in the yml and re-apply, or pass one explicitly: \`monoceros tunnel <name> ${raw}:<port>\`.`
     );
   }
-  if (!config.services.includes(raw)) {
+  return { kind: "service", service: raw, port: match.port };
+}
+function findConfiguredService(config, name) {
+  const services = config.services.map(resolveService);
+  const match = services.find((s) => s.name === name);
+  if (!match) {
+    const names = services.map((s) => s.name);
+    const list = names.length > 0 ? names.join(", ") : "(none configured)";
     throw new Error(
-      `Service '${raw}' is not declared in this container's yml. Add it with \`monoceros add-service ${config.services.length === 0 ? "<name>" : "\u2026"} ${raw}\` and re-apply.`
+      `Service '${name}' is not configured in this container's yml. Configured services: ${list}. Or pass a port number (e.g. \`monoceros tunnel <name> 8080\`).`
     );
   }
-  return { kind: "service", service: raw, port: entry2.defaultPort };
+  return match;
 }
 function resolveCompose2(args) {
   const network = `${composeProjectName(args.containerRoot)}_default`;
@@ -7046,7 +7611,7 @@ function resolveCompose2(args) {
       network,
       targetHost: args.parsedTarget.service,
       internalPort: args.parsedTarget.port,
-      display: `${args.name}/${args.parsedTarget.service}`
+      display: `${args.name}/${args.parsedTarget.service}:${args.parsedTarget.port}`
     };
   }
   return {
@@ -7087,10 +7652,7 @@ async function lookupContainerNetwork(args) {
     "ps",
     "-q",
     "--filter",
-    // Windows-normalize: devcontainer-cli lowercases the drive letter
-    // when stamping the label, docker filter is byte-exact. No-op
-    // off Windows.
-    `label=devcontainer.local_folder=${dockerLocalFolderLabel(args.containerRoot)}`
+    `label=devcontainer.local_folder=${args.containerRoot}`
   ]);
   if (psResult.exitCode !== 0) {
     throw new Error(
@@ -7208,7 +7770,7 @@ function formatLocalPortHeldError(port, address, result) {
 // src/tunnel/run.ts
 var SOCAT_IMAGE = "alpine/socat:1.8.0.3";
 var defaultDockerSpawn = (args) => {
-  const child = spawn9("docker", args, {
+  const child = spawn10("docker", args, {
     stdio: "inherit"
   });
   const exited = new Promise((resolve, reject) => {
@@ -7331,7 +7893,7 @@ var tunnelCommand = defineCommand29({
     },
     target: {
       type: "positional",
-      description: "Service name from the container yml (e.g. `postgres`) or an in-container port number (e.g. `8080`).",
+      description: "Service name from the container yml (e.g. `postgres`), `service:port` for an explicit in-container port (e.g. `rustfs:9001`), or a bare in-container port number \u2192 workspace (e.g. `8080`).",
       required: true
     },
     "local-port": {
@@ -7412,7 +7974,6 @@ var main = defineCommand30({
 
 // src/bin.ts
 bootstrapDockerGroup();
-bootstrapWslBackend();
 consumeInnerArgsFromProcessArgv();
 async function entry() {
   if (await maybeRenderHelp(process.argv.slice(2), main)) {