@getmonoceros/workbench 1.12.0 → 1.13.1

package/dist/bin.js

@@ -251,25 +251,25 @@ function detectHelpRequest(argv, main2) {
   const separatorIdx = argv.indexOf("--");
   if (helpIdx === -1) return null;
   if (separatorIdx !== -1 && separatorIdx < helpIdx) return null;
-  const 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);
@@ -311,7 +311,7 @@ import { consola as consola2 } from "consola";
 import { promises as fs8 } from "fs";
 import { consola } from "consola";
 import { createPatch } from "diff";
-import path8 from "path";
+import path9 from "path";
 
 // src/config/io.ts
 import { promises as fs } from "fs";
@@ -404,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,
@@ -430,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({}),
@@ -549,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");
 }
@@ -569,10 +634,330 @@ function prettyPath(p) {
   return p;
 }
 
+// src/config/env-file.ts
+import { existsSync as existsSync2, readFileSync, promises as fsp } from "fs";
+import path2 from "path";
+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 out;
+}
+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}
+`);
+}
+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;
+    };
+    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 (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 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 { features: out, missing };
+}
+function buildEnvStub(name) {
+  return `# Secrets and values for \${VAR} references in ${name}.yml.
+`;
+}
+async function ensureEnvVars(envPath, name, vars) {
+  const entries = Array.isArray(vars) ? vars.map((v) => [v, ""]) : Object.entries(vars);
+  const exists = existsSync2(envPath);
+  let content = exists ? readFileSync(envPath, "utf8") : buildEnvStub(name);
+  const present = new Set(Object.keys(parseEnvFile(content)));
+  const seen = /* @__PURE__ */ new Set();
+  const toAdd = entries.filter(([k]) => {
+    if (present.has(k) || seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+  const added = toAdd.map(([k]) => k);
+  if (!exists || added.length > 0) {
+    if (content.length > 0 && !content.endsWith("\n")) content += "\n";
+    for (const [k, v] of toAdd) content += `${k}=${v}
+`;
+    await fsp.mkdir(path2.dirname(envPath), { recursive: true });
+    await fsp.writeFile(envPath, content);
+  }
+  return { created: !exists, added };
+}
+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");
+}
+
+// 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");
+}
+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);
+  }
+  for (const note of summary.usageNotes) {
+    const trimmed = note.trim();
+    if (trimmed.length > 0) out.push(trimmed);
+  }
+  if (summary.optionHints.length > 0) {
+    const parts = summary.optionHints.map((key) => {
+      const desc = summary.optionDescriptions[key];
+      const short = desc ? shortenOptionDescription(desc) : void 0;
+      return short ? `${key} (${short})` : key;
+    });
+    out.push(`Options: ${parts.join(", ")}.`);
+  }
+  if (summary.documentationURL) {
+    out.push(`See ${summary.documentationURL} for further information.`);
+  }
+  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;
+    }
+    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/init/manifest.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+import path3 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] };
+}
+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/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;
+  }
+  const bundlePath = path3.join(
+    bundledFeaturesDir(),
+    name,
+    "devcontainer-feature.json"
+  );
+  if (existsSync3(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 = 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;
+        }
+        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/devcontainer/credentials.ts
 import { spawn } from "child_process";
 import { promises as fs2 } from "fs";
-import path2 from "path";
+import path4 from "path";
 
 // src/util/format.ts
 var ESC = "\x1B[";
@@ -788,8 +1173,8 @@ function formatCredentialLine(host, username, password) {
   return `https://${encUser}:${encPass}@${host}`;
 }
 async function collectGitCredentials(devContainerRoot, hosts, options = {}) {
-  const credsDir = path2.join(devContainerRoot, ".monoceros");
-  const credentialsPath = path2.join(credsDir, "git-credentials");
+  const 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: () => {
@@ -1186,8 +1571,8 @@ ${existing}` : leakedComment;
 }
 
 // src/init/components.ts
-import { existsSync as existsSync2, promises as fs4 } from "fs";
-import path3 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"]);
@@ -1234,7 +1619,7 @@ var ComponentFileSchema = z3.object({
   }
 });
 async function loadComponentCatalog(rootDir = componentsDir()) {
-  if (!existsSync2(rootDir)) {
+  if (!existsSync4(rootDir)) {
     return /* @__PURE__ */ new Map();
   }
   const out = /* @__PURE__ */ new Map();
@@ -1244,14 +1629,14 @@ async function loadComponentCatalog(rootDir = componentsDir()) {
 async function walk(baseDir, currentDir, out) {
   const entries = await fs4.readdir(currentDir, { withFileTypes: true });
   for (const entry2 of entries) {
-    const full = path3.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 = path3.relative(baseDir, full);
-    const name = relative.replace(/\.yml$/, "").split(path3.sep).join("/");
+    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 {
@@ -1273,42 +1658,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)) {
@@ -1321,39 +1670,11 @@ 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;
-    }
-    if (version !== void 0 && c.file.category !== "language") {
-      throw new Error(
-        `Component '${name}' is a ${c.file.category}, not a language \u2014 a ':${version}' suffix has no meaning here.`
-      );
-    }
-    out.push({ component: c, ...version !== void 0 ? { version } : {} });
-  }
-  if (unknown.length > 0) {
-    const available = [...catalog.keys()].sort();
-    throw new Error(
-      `Unknown component${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}.
-Available: ${available.join(", ")}.`
-    );
-  }
-  return out;
-}
 
 // src/proxy/index.ts
 import { spawn as spawn3 } from "child_process";
 import { promises as fs5 } from "fs";
-import path4 from "path";
+import path6 from "path";
 var PROXY_CONTAINER_NAME = "monoceros-proxy";
 var PROXY_NETWORK_NAME = "monoceros-proxy";
 var TRAEFIK_IMAGE = "traefik:v3.3";
@@ -1379,7 +1700,7 @@ var defaultDockerExec = (args) => {
 };
 var realDocker = defaultDockerExec;
 function proxyDynamicDir(home) {
-  return path4.join(home ?? monocerosHome(), "traefik", "dynamic");
+  return path6.join(home ?? monocerosHome(), "traefik", "dynamic");
 }
 async function ensureProxy(opts = {}) {
   const docker = opts.docker ?? realDocker;
@@ -1471,7 +1792,7 @@ async function maybeStopProxy(opts = {}) {
 
 // src/proxy/dynamic.ts
 import { promises as fs6 } from "fs";
-import path5 from "path";
+import path7 from "path";
 async function writeDynamicConfig(name, ports, opts = {}) {
   if (ports.length === 0) {
     throw new Error(
@@ -1480,12 +1801,12 @@ async function writeDynamicConfig(name, ports, opts = {}) {
   }
   const dir = proxyDynamicDir(opts.monocerosHome);
   await fs6.mkdir(dir, { recursive: true });
-  const file = path5.join(dir, `${name}.yml`);
+  const file = path7.join(dir, `${name}.yml`);
   await fs6.writeFile(file, renderDynamicConfig(name, ports), "utf8");
   return file;
 }
 async function removeDynamicConfig(name, opts = {}) {
-  const file = path5.join(proxyDynamicDir(opts.monocerosHome), `${name}.yml`);
+  const file = path7.join(proxyDynamicDir(opts.monocerosHome), `${name}.yml`);
   await fs6.rm(file, { force: true });
 }
 function renderDynamicConfig(name, ports) {
@@ -1658,6 +1979,19 @@ var SERVICE_CATALOG = {
       POSTGRES_PASSWORD: "monoceros",
       POSTGRES_DB: "monoceros"
     },
+    healthcheck: {
+      test: [
+        "CMD",
+        "pg_isready",
+        "-U",
+        "${POSTGRES_USER}",
+        "-d",
+        "${POSTGRES_DB}"
+      ],
+      interval: "10s",
+      timeout: "5s",
+      retries: 5
+    },
     // Postgres 18+ stores data under /var/lib/postgresql/<major>/, so
     // the recommended mount is the parent directory; pre-18 used
     // /var/lib/postgresql/data directly. See
@@ -1672,12 +2006,33 @@ var SERVICE_CATALOG = {
       MYSQL_ROOT_PASSWORD: "monoceros",
       MYSQL_DATABASE: "monoceros"
     },
+    healthcheck: {
+      test: [
+        "CMD",
+        "mysqladmin",
+        "ping",
+        "-h",
+        "127.0.0.1",
+        "-u",
+        "root",
+        "-p${MYSQL_ROOT_PASSWORD}"
+      ],
+      interval: "10s",
+      timeout: "5s",
+      retries: 5
+    },
     dataMount: "/var/lib/mysql",
     defaultPort: 3306
   },
   redis: {
     id: "redis",
     image: "redis:8",
+    healthcheck: {
+      test: ["CMD", "redis-cli", "ping"],
+      interval: "10s",
+      timeout: "5s",
+      retries: 5
+    },
     dataMount: "/data",
     defaultPort: 6379
   }
@@ -1688,34 +2043,107 @@ 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: Object.fromEntries(
+        Object.keys(def.env).map((k) => [k, `\${${k}}`])
+      )
+    } : {},
+    ...def.dataMount ? { volumes: [`data:${def.dataMount}`] } : {},
+    ...def.healthcheck ? { healthcheck: def.healthcheck } : {},
+    restart: "unless-stopped"
+  };
+}
+function curatedServiceEnvDefaults(name) {
+  const def = SERVICE_CATALOG[name];
+  return def?.env ? { ...def.env } : {};
+}
+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 existsSync3, readFileSync, promises as fs7 } from "fs";
-import path6 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.\-_~/:?#[\]@!&'()*+,;=%]+$/;
@@ -1745,12 +2173,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(
-        `Unknown service: ${svc}. Known: ${knownServices().join(", ")}.`
+        `Service ${JSON.stringify(svc.name)} has no image. Every service needs an 'image:'.`
       );
     }
+    if (svc.name === "workspace") {
+      throw new Error(
+        `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)) {
@@ -1800,10 +2240,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))
@@ -1862,8 +2306,8 @@ function resolveFeatures(opts) {
       if (match) {
         const name = match.name;
         const checkout = workbenchCheckoutRoot();
-        const localSourceDir = checkout ? path6.join(checkout, "images", "features", name) : null;
-        if (localSourceDir && existsSync3(localSourceDir)) {
+        const localSourceDir = checkout ? path8.join(checkout, "images", "features", name) : null;
+        if (localSourceDir && existsSync5(localSourceDir)) {
           const { paths, files } = readPersistentHomeEntries(localSourceDir);
           resolved.push({
             devcontainerKey: `./features/${name}`,
@@ -1887,9 +2331,9 @@ function resolveFeatures(opts) {
   return resolved;
 }
 function readPersistentHomeEntries(localSourceDir) {
-  const manifestPath = path6.join(localSourceDir, "devcontainer-feature.json");
+  const manifestPath = path8.join(localSourceDir, "devcontainer-feature.json");
   try {
-    const text = readFileSync(manifestPath, "utf8");
+    const text = readFileSync3(manifestPath, "utf8");
     const parsed = JSON.parse(text);
     return {
       paths: filterSubpaths(parsed["x-monoceros"]?.persistentHomePaths),
@@ -1964,7 +2408,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,
@@ -1997,6 +2441,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;
@@ -2025,20 +2481,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) {
@@ -2172,245 +2650,99 @@ function buildPostCreateScript(opts) {
   return lines.join("\n") + "\n";
 }
 async function writePostCreateScript(devcontainerDir, opts) {
-  const dest = path6.join(devcontainerDir, "post-create.sh");
+  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 = path6.join(targetDir, ".devcontainer");
-  const monocerosDir = path6.join(targetDir, ".monoceros");
-  const projectsDir = path6.join(targetDir, "projects");
-  const homeDir = path6.join(targetDir, "home");
-  const dataDir = path6.join(targetDir, "data");
+  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(path6.join(dataDir, def.id), { 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 });
       }
     }
   }
-  const containerGitignore = path6.join(targetDir, ".gitignore");
+  const containerGitignore = path8.join(targetDir, ".gitignore");
   await fs7.writeFile(containerGitignore, "/home/\n/.monoceros/\n/data/\n");
-  const gitkeep = path6.join(projectsDir, ".gitkeep");
-  if (!existsSync3(gitkeep)) {
+  const gitkeep = path8.join(projectsDir, ".gitkeep");
+  if (!existsSync5(gitkeep)) {
     await fs7.writeFile(gitkeep, "");
   }
   await fs7.writeFile(
-    path6.join(monocerosDir, ".gitignore"),
+    path8.join(monocerosDir, ".gitignore"),
     "git-credentials*\ngitconfig\n"
   );
   const devcontainerJson = buildDevcontainerJson(opts, dockerMode);
   await fs7.writeFile(
-    path6.join(devcontainerDir, "devcontainer.json"),
+    path8.join(devcontainerDir, "devcontainer.json"),
     JSON.stringify(devcontainerJson, null, 2) + "\n"
   );
-  const featuresDir = path6.join(devcontainerDir, "features");
-  if (existsSync3(featuresDir)) {
+  const featuresDir = path8.join(devcontainerDir, "features");
+  if (existsSync5(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 = path6.join(featuresDir, f.localName);
+    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(path6.join(homeDir, sub), { recursive: true });
-    }
-    for (const entry2 of f.persistentHomeFiles) {
-      const filePath = path6.join(homeDir, entry2.path);
-      await fs7.mkdir(path6.dirname(filePath), { recursive: true });
-      if (!existsSync3(filePath)) {
-        await fs7.writeFile(filePath, entry2.initialContent);
-      }
-    }
-  }
-  await writePostCreateScript(devcontainerDir, opts);
-  const composePath = path6.join(devcontainerDir, "compose.yaml");
-  if (needsCompose(opts)) {
-    await fs7.writeFile(composePath, buildComposeYaml(opts, dockerMode));
-  } else if (existsSync3(composePath)) {
-    await fs7.rm(composePath);
-  }
-  const workspacePath = path6.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 existsSync4, readFileSync as readFileSync2 } from "fs";
-import path7 from "path";
-function resolveManifestPath(name, checkoutRoot) {
-  if (checkoutRoot) {
-    const checkoutPath = path7.join(
-      checkoutRoot,
-      "images",
-      "features",
-      name,
-      "devcontainer-feature.json"
-    );
-    if (existsSync4(checkoutPath)) return checkoutPath;
-  }
-  const bundlePath = path7.join(
-    bundledFeaturesDir(),
-    name,
-    "devcontainer-feature.json"
-  );
-  if (existsSync4(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 = 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;
-        }
-        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");
-}
-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);
-  }
-  for (const note of summary.usageNotes) {
-    const trimmed = note.trim();
-    if (trimmed.length > 0) out.push(trimmed);
-  }
-  if (summary.optionHints.length > 0) {
-    const parts = summary.optionHints.map((key) => {
-      const desc = summary.optionDescriptions[key];
-      const short = desc ? shortenOptionDescription(desc) : void 0;
-      return short ? `${key} (${short})` : key;
-    });
-    out.push(`Options: ${parts.join(", ")}.`);
-  }
-  if (summary.documentationURL) {
-    out.push(`See ${summary.documentationURL} for further information.`);
-  }
-  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;
-    }
-    if (current.length + 1 + w.length <= usable) {
-      current += " " + w;
-    } else {
-      lines.push(current);
-      current = w;
+    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 (!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;
@@ -2433,11 +2765,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");
@@ -2657,6 +3002,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;
 }
@@ -2733,7 +3084,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);
@@ -2773,8 +3132,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;
@@ -2801,13 +3160,56 @@ 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") {
+    if (curated) {
+      const defaults = curatedServiceEnvDefaults(arg);
+      if (Object.keys(defaults).length > 0) {
+        const home = input.monocerosHome ?? monocerosHome();
+        await ensureEnvGitignored(containerConfigsDir(home));
+        const seeded = await ensureEnvVars(
+          containerEnvPath(input.name, home),
+          input.name,
+          defaults
+        );
+        if (seeded.added.length > 0) {
+          (input.logger ?? defaultLogger()).info(
+            `Seeded ${seeded.added.join(", ")} into ${input.name}.env (dev-defaults \u2014 change them there if needed).`
+          );
+        }
+      }
+    } else {
+      (input.logger ?? defaultLogger()).info(customServiceHint(name));
+    }
   }
-  return mutate(input, (doc) => addServiceToDoc(doc, input.service));
+  return result;
 }
 function runAddAptPackages(input) {
   if (input.packages.length === 0) {
@@ -2824,7 +3226,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) {
@@ -2853,7 +3255,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(),
@@ -2969,7 +3371,7 @@ async function tryCloneInRunningContainer(input, entry2) {
   logger.info(
     `Cloned ${entry2.url} into /workspaces/${containerName2}/${targetRel} inside the running container.`
   );
-  void path8;
+  void path9;
 }
 function shquote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
@@ -3046,10 +3448,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)) {
@@ -3609,7 +4034,7 @@ 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."
+    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: {
@@ -3619,9 +4044,13 @@ var addServiceCommand = defineCommand7({
     },
     service: {
       type: "positional",
-      description: "Service identifier (postgres, mysql, redis).",
+      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.",
@@ -3634,6 +4063,7 @@ var addServiceCommand = defineCommand7({
       const result = await runAddService({
         name: args.name,
         service: args.service,
+        ...args.as ? { as: args.as } : {},
         yes: args.yes
       });
       process.exit(result.status === "aborted" ? 1 : 0);
@@ -3648,12 +4078,12 @@ var addServiceCommand = defineCommand7({
 import { defineCommand as defineCommand8 } from "citty";
 
 // src/apply/index.ts
-import { existsSync as existsSync6, promises as fs11 } from "fs";
+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 path9 from "path";
+import path10 from "path";
 function buildStateFile(opts) {
   return {
     schemaVersion: CONFIG_SCHEMA_VERSION,
@@ -3663,7 +4093,7 @@ function buildStateFile(opts) {
   };
 }
 function stateFilePath(targetDir) {
-  return path9.join(targetDir, ".monoceros", "state.json");
+  return path10.join(targetDir, ".monoceros", "state.json");
 }
 async function readStateFile(targetDir) {
   try {
@@ -3674,7 +4104,7 @@ async function readStateFile(targetDir) {
   }
 }
 async function writeStateFile(targetDir, state) {
-  const monocerosDir = path9.join(targetDir, ".monoceros");
+  const monocerosDir = path10.join(targetDir, ".monoceros");
   await fs9.mkdir(monocerosDir, { recursive: true });
   await fs9.writeFile(
     stateFilePath(targetDir),
@@ -3695,7 +4125,11 @@ function solutionConfigToCreateOptions(config, featureDefaults = {}) {
   const result = {
     name: config.name,
     languages: [...config.languages],
-    services: [...config.services]
+    // 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;
@@ -3746,8 +4180,8 @@ function solutionConfigToCreateOptions(config, featureDefaults = {}) {
 
 // src/devcontainer/compose.ts
 import { spawn as spawn5 } from "child_process";
-import { existsSync as existsSync5 } from "fs";
-import path11 from "path";
+import { existsSync as existsSync6 } from "fs";
+import path12 from "path";
 import { consola as consola9 } from "consola";
 
 // src/util/mask-secrets.ts
@@ -3808,9 +4242,9 @@ function createSecretMaskStream() {
 
 // src/devcontainer/cli.ts
 import { spawn as spawn4 } from "child_process";
-import { readFileSync as readFileSync3 } from "fs";
+import { readFileSync as readFileSync4 } from "fs";
 import { createRequire } from "module";
-import path10 from "path";
+import path11 from "path";
 
 // src/devcontainer/runtime-pull-hint.ts
 import { Transform as Transform2 } from "stream";
@@ -3856,12 +4290,12 @@ var cachedBinaryPath = null;
 function devcontainerCliPath() {
   if (cachedBinaryPath) return cachedBinaryPath;
   const pkgJsonPath = require_.resolve("@devcontainers/cli/package.json");
-  const pkg = JSON.parse(readFileSync3(pkgJsonPath, "utf8"));
+  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 = path10.resolve(path10.dirname(pkgJsonPath), binEntry);
+  cachedBinaryPath = path11.resolve(path11.dirname(pkgJsonPath), binEntry);
   return cachedBinaryPath;
 }
 var spawnDevcontainer = (args, cwd, options = {}) => {
@@ -3979,16 +4413,16 @@ async function cleanupDockerObjects(opts) {
   return { exitCode: rmExit, removedIds: ids };
 }
 function composeProjectName(root) {
-  return `${path11.basename(root)}_devcontainer`;
+  return `${path12.basename(root)}_devcontainer`;
 }
 function resolveCompose(root) {
-  if (!existsSync5(path11.join(root, ".devcontainer"))) {
+  if (!existsSync6(path12.join(root, ".devcontainer"))) {
     throw new Error(
       `No .devcontainer/ at ${root}. Run \`monoceros apply <name>\` first.`
     );
   }
-  const composeFile = path11.join(root, ".devcontainer", "compose.yaml");
-  if (!existsSync5(composeFile)) {
+  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.`
     );
@@ -4179,6 +4613,12 @@ 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}`);
@@ -4225,11 +4665,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}}"],
       {
@@ -4288,13 +4802,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 = "";
@@ -4404,8 +4918,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: () => {
   } };
@@ -4418,8 +4932,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 } : {},
@@ -4462,7 +4976,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);
@@ -4495,7 +5009,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.`
     );
@@ -4512,6 +5026,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;
@@ -4566,7 +5094,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,
@@ -4577,6 +5105,23 @@ ${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) {
@@ -4624,8 +5169,8 @@ ${sectionLine(label)}
   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) {
@@ -4695,7 +5240,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,
@@ -4703,7 +5248,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)}.`
         );
@@ -4717,7 +5262,7 @@ async function persistPromptedIdentity(prompted, ymlPath, home, logger) {
 }
 
 // src/version.ts
-var CLI_VERSION = true ? "1.12.0" : "dev";
+var CLI_VERSION = true ? "1.13.1" : "dev";
 
 // src/commands/_dispatch.ts
 import { consola as consola12 } from "consola";
@@ -4877,8 +5422,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 };
@@ -5026,15 +5571,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();
@@ -5136,8 +5677,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" }
     }
   },
@@ -5281,22 +5828,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,
@@ -5304,10 +5851,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 (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 (merged.services.length > 0) {
+  if (composed.services.length > 0) {
     pushSectionHeader(
       lines,
       SERVICES_HEADER,
@@ -5315,10 +5873,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,
@@ -5326,7 +5884,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,
@@ -5407,7 +5965,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("");
@@ -5514,6 +6074,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`.";
@@ -5528,15 +6104,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;
   }
@@ -5546,10 +6122,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}`);
     }
   }
 }
@@ -5603,7 +6179,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.`
     );
@@ -5673,15 +6249,38 @@ 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);
+    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 seedVars = {};
+  for (const f of composed.features) {
+    for (const h of featureOptionHints(
+      lookup(f.ref),
+      f.ref,
+      Object.keys(f.options ?? {})
+    )) {
+      if (!(h.envVar in seedVars)) seedVars[h.envVar] = "";
+    }
+  }
+  for (const svc of composed.services) {
+    if (svc.kind === "curated") {
+      Object.assign(seedVars, curatedServiceEnvDefaults(svc.name));
+    }
   }
-  await fs13.mkdir(containerConfigsDir(home), { recursive: true });
-  await fs13.writeFile(dest, text, "utf8");
+  await ensureEnvVars(envPath, opts.name, seedVars);
   if (promptedIdentity?.prompted) {
     const { name, email, scope } = promptedIdentity.prompted;
     if (scope === "g" || scope === "b") {
@@ -5711,11 +6310,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).`
           );
@@ -5727,29 +6326,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: {
@@ -5757,14 +6463,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": {
@@ -5775,14 +6496,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));
@@ -5790,6 +6517,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) {
@@ -5825,43 +6576,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";
@@ -6149,8 +6863,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();
@@ -6165,9 +6879,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.`
@@ -6191,24 +6907,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") {
@@ -6234,7 +6956,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(
@@ -6337,8 +7059,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();
@@ -6346,15 +7068,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(
@@ -6368,24 +7090,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(
@@ -6643,8 +7370,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;
@@ -6667,7 +7394,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.`
     );
@@ -6879,15 +7606,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.`
     );
@@ -6895,13 +7622,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) {
@@ -6920,23 +7647,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`;
@@ -6945,7 +7690,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 {
@@ -7104,7 +7849,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) => {
@@ -7227,7 +7972,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": {