saasaloy 0.5.1 → 0.6.0

package/dist/index.js

@@ -14,17 +14,17 @@ import {
   confirm,
   intro,
   isCancel,
-  log,
+  log as log2,
   note,
   outro,
   select
 } from "@clack/prompts";
-import { posix as posix4 } from "path";
+import { posix as posix3 } from "path";
 import pc2 from "picocolors";
 
 // src/lib/applier.ts
-import { mkdir as mkdir3, readFile as readFile5, writeFile as writeFile3 } from "fs/promises";
-import { dirname as dirname3, posix as posix2 } from "path";
+import { mkdir as mkdir4, readFile as readFile6, writeFile as writeFile4 } from "fs/promises";
+import { dirname as dirname4, posix as posix2 } from "path";
 
 // src/lib/exit.ts
 var EXIT_OK = 0;
@@ -152,6 +152,10 @@ function formatOwnedCollisions(collisions, requested = "these modules") {
   );
 }
 
+// src/lib/env-example.ts
+import { mkdir as mkdir2, readFile as readFile2, writeFile } from "fs/promises";
+import { dirname as dirname2 } from "path";
+
 // src/lib/fs-utils.ts
 import { createHash } from "crypto";
 import {
@@ -274,20 +278,145 @@ async function classifyLink(linkAbs, targetAbs) {
     return "conflict";
   }
   const dest = await readlink(linkAbs);
-  const resolved2 = resolve(dirname(linkAbs), dest);
-  return resolved2 === resolve(targetAbs) ? "correct" : "conflict";
+  const resolved = resolve(dirname(linkAbs), dest);
+  return resolved === resolve(targetAbs) ? "correct" : "conflict";
 }
 async function createDirLink(linkAbs, targetAbs) {
   await mkdir(dirname(linkAbs), { recursive: true });
   await (process.platform === "win32" ? symlink(resolve(targetAbs), linkAbs, "junction") : symlink(relative(dirname(linkAbs), targetAbs), linkAbs, "dir"));
 }
 
+// src/lib/env-example.ts
+var ENV_EXAMPLE = "packages/env/.env.example";
+var PUBLIC_PREFIX = "PUBLIC_";
+var SERVICE_NAMES = ["api", "web", "admin", "deploy"];
+var CLIENT_SERVICES = ["web", "admin"];
+function isPublicVar(name) {
+  return name.startsWith(PUBLIC_PREFIX);
+}
+var HEADER = [
+  "# The one key list for this repository. Every `.env` that `pnpm env:setup` writes is",
+  "# written from this file. There is no second example file, and no `.dev.vars.example`.",
+  "#",
+  "# Generated by `saasaloy add` from the installed modules' `envVars`. A value you type",
+  "# here survives that, and nothing is ever removed \u2014 `saasaloy remove` owns deletions.",
+  "#",
+  "# `.env` is gitignored; this file is tracked. Keep real secrets out of it.",
+  "#",
+  "# A `# @services <names>` line sets which services take every key below it, until the",
+  "# next such line. A key with no section above it fails `pnpm env:setup`."
+];
+function servicesFor(name, envServices) {
+  const declared = envServices?.[name] ?? envServices?.default;
+  if (declared && declared.length > 0) {
+    return SERVICE_NAMES.filter((service) => declared.includes(service));
+  }
+  return isPublicVar(name) ? [...CLIENT_SERVICES] : ["api"];
+}
+var SECTION = /^\s*#\s*@services\b(.*)$/;
+function parseEnvExample(text4) {
+  const entries = {};
+  let comment = [];
+  let services;
+  for (const line of text4.split("\n")) {
+    const trimmed = line.trim();
+    const section = SECTION.exec(trimmed);
+    if (section) {
+      const named = new Set((section[1] ?? "").split(/[\s,]+/).filter(Boolean));
+      services = SERVICE_NAMES.filter((name) => named.has(name));
+      comment = [];
+      continue;
+    }
+    if (trimmed.startsWith("#")) {
+      comment.push(trimmed);
+      continue;
+    }
+    if (trimmed === "") {
+      comment = [];
+      continue;
+    }
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) {
+      comment = [];
+      continue;
+    }
+    entries[trimmed.slice(0, eq).trim()] = {
+      value: trimmed.slice(eq + 1),
+      comment,
+      services: services && services.length > 0 ? services : void 0
+    };
+    comment = [];
+  }
+  return entries;
+}
+function sectionKey(services) {
+  return SERVICE_NAMES.filter((name) => services.includes(name)).join(" ");
+}
+var BLANK_ON_PURPOSE = "# Blank on purpose: this key may stay empty.";
+function renderEnvExample(args) {
+  const { envVars, devVars, existing } = args;
+  const optional = new Set(args.optional);
+  const names = [
+    .../* @__PURE__ */ new Set([...Object.keys(envVars), ...Object.keys(existing)])
+  ].toSorted();
+  const bySection = /* @__PURE__ */ new Map();
+  for (const name of names) {
+    const declared = args.services[name];
+    const kept = existing[name]?.services;
+    const section = sectionKey(
+      declared || kept ? [...kept ?? [], ...declared ?? []] : servicesFor(name)
+    );
+    bySection.set(section, [...bySection.get(section) ?? [], name]);
+  }
+  const blocks = [];
+  for (const section of [...bySection.keys()].toSorted()) {
+    blocks.push(`# @services ${section}`);
+    for (const name of bySection.get(section) ?? []) {
+      const entry = existing[name];
+      const value = entry?.value ?? devVars[name] ?? "";
+      const description = envVars[name];
+      const kept = entry?.comment ?? [];
+      const lines = description ? description.split("\n").map((line) => `# ${line}`) : kept.length > 0 ? [...kept] : ["# Declared outside saasaloy \u2014 no module describes this one."];
+      if (optional.has(name)) {
+        lines.unshift(BLANK_ON_PURPOSE);
+      }
+      lines.push(`${name}=${value}`);
+      blocks.push(lines.join("\n"));
+    }
+  }
+  return `${[HEADER.join("\n"), ...blocks].join("\n\n")}
+`;
+}
+async function writeEnvExample(args) {
+  const { root, envVars, devVars, services, optional } = args;
+  const abs = resolveWithinRoot(root, ENV_EXAMPLE);
+  await assertNoSymlinkPath(root, abs);
+  const before = await pathExists(abs) ? await readFile2(abs, "utf-8") : "";
+  const existing = parseEnvExample(before);
+  if (Object.keys(envVars).length === 0 && Object.keys(existing).length === 0) {
+    return void 0;
+  }
+  const content = renderEnvExample({
+    devVars,
+    envVars,
+    existing,
+    optional,
+    services
+  });
+  if (before === content) {
+    return void 0;
+  }
+  await mkdir2(dirname2(abs), { recursive: true });
+  await writeFile(abs, content, "utf-8");
+  return ENV_EXAMPLE;
+}
+
 // src/lib/manifest.ts
-import { mkdir as mkdir2, readFile as readFile3, writeFile } from "fs/promises";
-import { dirname as dirname2, join as join3 } from "path";
+import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname3, join as join3 } from "path";
 
 // src/lib/schema.ts
-import { readFile as readFile2 } from "fs/promises";
+import { readFile as readFile3 } from "fs/promises";
 import { join as join2 } from "path";
 import { fileURLToPath } from "url";
 import AjvDefault from "ajv/dist/2020.js";
@@ -320,7 +449,7 @@ async function getValidator(name) {
     return cached;
   }
   const schema = JSON.parse(
-    await readFile2(join2(await schemaDir(), SCHEMA_FILES[name]), "utf-8")
+    await readFile3(join2(await schemaDir(), SCHEMA_FILES[name]), "utf-8")
   );
   const validator = ajv.compile(schema);
   validators.set(name, validator);
@@ -405,7 +534,7 @@ async function loadManifest(root) {
   }
   let raw;
   try {
-    raw = JSON.parse(await readFile3(file, "utf-8"));
+    raw = JSON.parse(await readFile4(file, "utf-8"));
   } catch (error) {
     throw new RefusalError(
       `${MANIFEST_FILE} is invalid:
@@ -430,8 +559,8 @@ async function loadManifest(root) {
 }
 async function saveManifest(root, manifest) {
   const file = join3(root, MANIFEST_FILE);
-  await mkdir2(dirname2(file), { recursive: true });
-  await writeFile(file, `${JSON.stringify(manifest, null, 2)}
+  await mkdir3(dirname3(file), { recursive: true });
+  await writeFile2(file, `${JSON.stringify(manifest, null, 2)}
 `, "utf-8");
 }
 
@@ -1828,7 +1957,7 @@ function refusalReason(table, source, patch) {
 }
 
 // src/lib/saasaloy-config.ts
-import { readFile as readFile4, writeFile as writeFile2 } from "fs/promises";
+import { readFile as readFile5, writeFile as writeFile3 } from "fs/promises";
 import { join as join4 } from "path";
 var CONFIG_FILE = "saasaloy.json";
 async function loadConfig(root) {
@@ -1838,7 +1967,7 @@ async function loadConfig(root) {
       `No ${CONFIG_FILE} found in ${root}. Run \`saasaloy init\` first, or cd into a Saasaloy project.`
     );
   }
-  const parsed = JSON.parse(await readFile4(file, "utf-8"));
+  const parsed = JSON.parse(await readFile5(file, "utf-8"));
   const result = await validateSaasaloyConfig(parsed);
   if (!result.valid) {
     throw new RefusalError(
@@ -1861,7 +1990,7 @@ function migrateBase(config) {
 }
 async function saveConfig(root, config) {
   const file = join4(root, CONFIG_FILE);
-  await writeFile2(file, `${JSON.stringify(config, null, 2)}
+  await writeFile3(file, `${JSON.stringify(config, null, 2)}
 `, "utf-8");
 }
 function resolveTarget(aliases, target) {
@@ -1881,6 +2010,9 @@ function resolveTarget(aliases, target) {
     );
   }
   const trimmed = base.endsWith("/") ? base.slice(0, -1) : base;
+  if (trimmed === "." || trimmed === "") {
+    return rest;
+  }
   return `${trimmed}/${rest}`;
 }
 
@@ -2004,7 +2136,7 @@ async function classify(targetAbs, target, newHash, manifest, module) {
     const stale = manifest.managed[target];
     return stale && stale.module !== module ? { action: "create", staleOwner: stale.module } : { action: "create" };
   }
-  const oldContent = await readFile5(targetAbs, "utf-8");
+  const oldContent = await readFile6(targetAbs, "utf-8");
   const oldHash = hashContent(oldContent);
   const managed = manifest.managed[target];
   const ownedBy = managed && managed.module !== module ? { ownedBy: managed.module } : {};
@@ -2021,7 +2153,7 @@ async function classify(targetAbs, target, newHash, manifest, module) {
   return { action: "conflict", oldContent };
 }
 async function planModuleFile(module, ref, root, manifest) {
-  const content = await readFile5(ref.abs, "utf-8");
+  const content = await readFile6(ref.abs, "utf-8");
   const newHash = hashContent(content);
   const targetAbs = resolveWithinRoot(root, ref.target);
   const { action, oldContent, ownedBy, staleOwner } = await classify(
@@ -2067,6 +2199,9 @@ async function buildPlan(args) {
   const devDependencies = [];
   const envVars = {};
   const devVars = {};
+  const envServices = {};
+  const envServicesGuessed = /* @__PURE__ */ new Set();
+  const envOptional = /* @__PURE__ */ new Set();
   const removeWarnings = {};
   const aliases = {};
   for (const name of install) {
@@ -2164,8 +2299,20 @@ async function buildPlan(args) {
     for (const [key, value] of Object.entries(item.devVars ?? {})) {
       devVars[key] = value;
     }
+    for (const key of item.envOptional ?? []) {
+      envOptional.add(key);
+    }
     for (const [key, value] of Object.entries(item.envVars ?? {})) {
       envVars[key] = value;
+      if (!item.envServices) {
+        envServicesGuessed.add(name);
+      }
+      envServices[key] = [
+        .../* @__PURE__ */ new Set([
+          ...envServices[key] ?? [],
+          ...servicesFor(key, item.envServices)
+        ])
+      ];
     }
     if (item.removeWarnings && item.removeWarnings.length > 0) {
       removeWarnings[name] = [...item.removeWarnings];
@@ -2212,6 +2359,9 @@ async function buildPlan(args) {
     dependencies,
     devDependencies,
     devVars,
+    envOptional: [...envOptional].toSorted(),
+    envServices,
+    envServicesGuessed: [...envServicesGuessed].toSorted(),
     envVars,
     aliases,
     aliasConflicts,
@@ -2244,8 +2394,8 @@ async function executePlan(plan, root, config, manifest) {
     }
     if (WRITABLE.has(file.action)) {
       await assertNoSymlinkPath(root, file.targetAbs);
-      await mkdir3(dirname3(file.targetAbs), { recursive: true });
-      await writeFile3(file.targetAbs, file.content, "utf-8");
+      await mkdir4(dirname4(file.targetAbs), { recursive: true });
+      await writeFile4(file.targetAbs, file.content, "utf-8");
       written.push(file);
     } else {
       refreshed.push(file);
@@ -2263,10 +2413,10 @@ async function executePlan(plan, root, config, manifest) {
       continue;
     }
     await assertNoSymlinkPath(root, p.fileAbs);
-    const source = await readFile5(p.fileAbs, "utf-8");
+    const source = await readFile6(p.fileAbs, "utf-8");
     const { content, changed, reason } = applyPatch(source, p.patch, p.file);
     if (changed) {
-      await writeFile3(p.fileAbs, content, "utf-8");
+      await writeFile4(p.fileAbs, content, "utf-8");
       patched.push(p);
       recordPatch(manifest, {
         file: p.file,
@@ -2652,6 +2802,39 @@ function formatCliMismatches(mismatches, requested, cliVersion) {
     `Nothing was written.`
   ].join("\n");
 }
+function describeInvalidDescriptor(args) {
+  const { name, raw, errors, cliVersion } = args;
+  const range = rawRequiresRange(raw);
+  if (range !== void 0 && isValidRange(range)) {
+    if (cliVersion === UNKNOWN_VERSION) {
+      return `Module "${name}" needs saasaloy ${range}, and this CLI's own version could not be read. Upgrade with \`${UPGRADE_COMMAND}\`.`;
+    }
+    if (!satisfies(cliVersion, range)) {
+      return `Module "${name}" needs saasaloy ${range}, and ${cliVersion} is installed. Upgrade with \`${UPGRADE_COMMAND}\`.`;
+    }
+  }
+  const lines = [
+    `Module "${name}" has an invalid descriptor:`,
+    ...errors.map((e) => `  ${e}`)
+  ];
+  if (errors.some((e) => e.includes("unexpected property"))) {
+    lines.push(
+      `It may use a field newer than saasaloy ${cliVersion}. Upgrade with \`${UPGRADE_COMMAND}\` and retry.`
+    );
+  }
+  return lines.join("\n");
+}
+function rawRequiresRange(raw) {
+  if (typeof raw !== "object" || raw === null) {
+    return void 0;
+  }
+  const { requires } = raw;
+  if (typeof requires !== "object" || requires === null) {
+    return void 0;
+  }
+  const { saasaloy } = requires;
+  return typeof saasaloy === "string" ? saasaloy : void 0;
+}
 
 // src/lib/conflicts.ts
 function pairKey(a, b) {
@@ -2740,81 +2923,88 @@ function planWritesUi(plan) {
   );
 }
 
-// src/lib/dev-vars.ts
-import { mkdir as mkdir4, readFile as readFile6, writeFile as writeFile4 } from "fs/promises";
-import { dirname as dirname4, posix as posix3 } from "path";
-var DEV_VARS_EXAMPLE = ".dev.vars.example";
-var API_ALIAS = "@api";
-function apiWorkspace(aliases) {
-  const src = aliases[API_ALIAS];
-  if (!src) {
-    return void 0;
+// src/lib/format.ts
+import { spawn } from "child_process";
+import { join as join5 } from "path";
+import { log } from "@clack/prompts";
+function prettierBin(root) {
+  const name = process.platform === "win32" ? "prettier.cmd" : "prettier";
+  return join5(root, "node_modules", ".bin", name);
+}
+async function formatFiles(root, files, run2 = runChild) {
+  const unique = [...new Set(files)];
+  if (unique.length === 0) {
+    return { kind: "nothing" };
+  }
+  const bin = prettierBin(root);
+  if (!await pathExists(bin)) {
+    return { files: unique, kind: "no-prettier" };
+  }
+  const result = await run2(
+    bin,
+    ["--write", "--ignore-unknown", "--log-level", "warn", "--", ...unique],
+    root
+  );
+  if (!result.ok) {
+    return {
+      files: unique,
+      kind: "failed",
+      message: result.message ?? "prettier failed"
+    };
   }
-  const workspace = posix3.dirname(src.replace(/\/+$/, ""));
-  return workspace === "." || workspace === "/" ? void 0 : workspace;
-}
-var HEADER = [
-  "# Environment variables this project's modules declare.",
-  "# Generated by `saasaloy add`, one entry per declared variable, comments and all.",
-  "#",
-  "# Copy this file to `.dev.vars` and fill in the blanks: `.dev.vars` is what",
-  "# `wrangler dev` reads, and it is gitignored. This example is not \u2014 keep it",
-  "# checked in, and keep real secrets out of it."
-];
-function devVarsExamplePath(aliases) {
-  const workspace = apiWorkspace(aliases);
-  return workspace ? posix3.join(workspace, DEV_VARS_EXAMPLE) : void 0;
+  return { files: unique, kind: "formatted" };
 }
-function parseDevVars(text4) {
-  const values = {};
-  for (const line of text4.split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith("#")) {
-      continue;
-    }
-    const eq = trimmed.indexOf("=");
-    if (eq <= 0) {
-      continue;
-    }
-    values[trimmed.slice(0, eq).trim()] = trimmed.slice(eq + 1);
+function formatReport(outcome) {
+  if (outcome.kind === "nothing") {
+    return null;
   }
-  return values;
-}
-function renderDevVarsExample(args) {
-  const { envVars, devVars, existing } = args;
-  const names = [
-    .../* @__PURE__ */ new Set([...Object.keys(envVars), ...Object.keys(existing)])
-  ].toSorted();
-  const blocks = names.map((name) => {
-    const value = existing[name] ?? devVars[name] ?? "";
-    const description = envVars[name];
-    const lines = description ? description.split("\n").map((line) => `# ${line}`) : ["# Declared outside saasaloy \u2014 no module describes this one."];
-    lines.push(`${name}=${value}`);
-    return lines.join("\n");
-  });
-  return `${[HEADER.join("\n"), ...blocks].join("\n\n")}
-`;
-}
-async function writeDevVarsExample(args) {
-  const { root, aliases, envVars, devVars } = args;
-  const target = devVarsExamplePath(aliases);
-  if (!target) {
-    return void 0;
+  const count = `${String(outcome.files.length)} patched file${outcome.files.length === 1 ? "" : "s"}`;
+  if (outcome.kind === "formatted") {
+    return { level: "step", message: `format  ${count} with Prettier` };
   }
-  const abs = resolveWithinRoot(root, target);
-  await assertNoSymlinkPath(root, abs);
-  const before = await pathExists(abs) ? await readFile6(abs, "utf-8") : void 0;
-  const existing = before === void 0 ? {} : parseDevVars(before);
-  if (Object.keys(envVars).length === 0 && Object.keys(existing).length === 0) {
-    return void 0;
+  if (outcome.kind === "no-prettier") {
+    return {
+      level: "info",
+      message: `Prettier isn't installed yet, so ${count} kept the patch layout. Run \`pnpm install\`, then \`pnpm format\`.`
+    };
   }
-  const content = renderDevVarsExample({ devVars, envVars, existing });
-  if (before === content) {
-    return void 0;
+  return {
+    level: "warn",
+    message: `Couldn't format ${count} \u2014 ${outcome.message}. Run \`pnpm format\`.`
+  };
+}
+async function formatPatchedFiles(root, files, options) {
+  const report = formatReport(await formatFiles(root, files));
+  if (report !== null) {
+    log[report.level](report.message, options);
   }
-  await mkdir4(dirname4(abs), { recursive: true });
-  await writeFile4(abs, content, "utf-8");
-  return target;
+}
+function runChild(command, args, cwd) {
+  return new Promise((resolvePromise) => {
+    const child = spawn(command, args, {
+      cwd,
+      shell: process.platform === "win32",
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let output = "";
+    child.stdout?.on("data", (chunk) => {
+      output += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk) => {
+      output += chunk.toString();
+    });
+    child.on("error", (error) => {
+      resolvePromise({ message: error.message, ok: false });
+    });
+    child.on("close", (code) => {
+      resolvePromise(
+        code === 0 ? { ok: true } : {
+          message: output.trim() || `prettier exited with code ${String(code)}`,
+          ok: false
+        }
+      );
+    });
+  });
 }
 
 // src/lib/diff.ts
@@ -2865,7 +3055,7 @@ function lineDiff(oldText, newText) {
 
 // src/lib/lock.ts
 import { readFile as readFile7, writeFile as writeFile5 } from "fs/promises";
-import { join as join5 } from "path";
+import { join as join6 } from "path";
 var LOCK_FILE = "saasaloy-lock.json";
 var LOCKFILE_VERSION = 1;
 var LOCK_SCHEMA_URL = "https://saasaloy.dev/schemas/saasaloy-lock.schema.json";
@@ -2877,7 +3067,7 @@ function emptyLock() {
   };
 }
 async function loadLock(root) {
-  const file = join5(root, LOCK_FILE);
+  const file = join6(root, LOCK_FILE);
   if (!await pathExists(file)) {
     return emptyLock();
   }
@@ -2907,7 +3097,7 @@ async function loadLock(root) {
   };
 }
 async function saveLock(root, lock) {
-  const file = join5(root, LOCK_FILE);
+  const file = join6(root, LOCK_FILE);
   await writeFile5(file, `${JSON.stringify(lock, null, 2)}
 `, "utf-8");
 }
@@ -2944,7 +3134,7 @@ async function persistLedger(input) {
 
 // src/lib/pkg-json.ts
 import { readFile as readFile8, writeFile as writeFile6 } from "fs/promises";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 function parseDep(spec) {
   const at = spec.lastIndexOf("@");
   if (at > 0) {
@@ -2987,7 +3177,7 @@ function planDeps(pkg, deps, devDeps = []) {
   return { added, conflicts, devAdded, skipped };
 }
 async function readRootPackageJson(root) {
-  const file = join6(root, "package.json");
+  const file = join7(root, "package.json");
   if (!await pathExists(file)) {
     return null;
   }
@@ -3014,20 +3204,20 @@ async function writeDeps(root, pkg, added, devAdded = []) {
   if (devAdded.length > 0) {
     pkg.devDependencies = mergeSorted(pkg.devDependencies, devAdded);
   }
-  const file = join6(root, "package.json");
+  const file = join7(root, "package.json");
   await writeFile6(file, `${JSON.stringify(pkg, null, 2)}
 `, "utf-8");
 }
 
 // src/lib/project.ts
-import { dirname as dirname5, join as join7, parse } from "path";
+import { dirname as dirname5, join as join8, parse } from "path";
 var MARKERS = ["saasaloy.json"];
 async function findProjectRoot(start = process.cwd()) {
   let dir = start;
   const { root } = parse(dir);
   for (; ; ) {
     for (const marker of MARKERS) {
-      if (await pathExists(join7(dir, marker))) {
+      if (await pathExists(join8(dir, marker))) {
         return dir;
       }
     }
@@ -3039,10 +3229,26 @@ async function findProjectRoot(start = process.cwd()) {
 }
 
 // src/lib/registry.ts
-import { mkdtemp, readFile as readFile9, rm } from "fs/promises";
+import { mkdtemp, readFile as readFile10, rm } from "fs/promises";
 import { tmpdir } from "os";
-import { isAbsolute as isAbsolute2, join as join8, resolve as resolve2 } from "path";
+import { isAbsolute as isAbsolute2, join as join9, resolve as resolve2 } from "path";
 import { downloadTemplate } from "giget";
+
+// src/version.ts
+import { readFile as readFile9 } from "fs/promises";
+import { fileURLToPath as fileURLToPath2 } from "url";
+var UNKNOWN_VERSION2 = "unknown";
+async function readVersion() {
+  try {
+    const file = fileURLToPath2(new URL("../package.json", import.meta.url));
+    const parsed = JSON.parse(await readFile9(file, "utf-8"));
+    return typeof parsed.version === "string" ? parsed.version : UNKNOWN_VERSION2;
+  } catch {
+    return UNKNOWN_VERSION2;
+  }
+}
+
+// src/lib/registry.ts
 var REGISTRY_ENV = "SAASALOY_REGISTRY_DIR";
 var DEFAULT_OWNER = "mimukit";
 var DEFAULT_REPO = "saasaloy";
@@ -3093,7 +3299,7 @@ function createRegistrySource(coord) {
   );
 }
 async function loadModuleFolder(dir, name, requiredBy) {
-  const file = join8(dir, "registry-item.json");
+  const file = join9(dir, "registry-item.json");
   if (!await pathExists(file)) {
     const because = requiredBy ? ` (required by ${requiredBy})` : "";
     throw new RefusalError(
@@ -3102,7 +3308,7 @@ async function loadModuleFolder(dir, name, requiredBy) {
   }
   let parsed;
   try {
-    parsed = JSON.parse(await readFile9(file, "utf-8"));
+    parsed = JSON.parse(await readFile10(file, "utf-8"));
   } catch (error) {
     throw new RefusalError(
       `Module "${name}" has an unreadable descriptor: ${file} is not valid JSON.`,
@@ -3112,8 +3318,12 @@ async function loadModuleFolder(dir, name, requiredBy) {
   const result = await validateRegistryItem(parsed);
   if (!result.valid) {
     throw new RefusalError(
-      `Module "${name}" has an invalid descriptor:
-  ${result.errors.join("\n  ")}`
+      describeInvalidDescriptor({
+        cliVersion: await readVersion(),
+        errors: result.errors,
+        name,
+        raw: parsed
+      })
     );
   }
   const item = parsed;
@@ -3134,13 +3344,13 @@ var LocalRegistrySource = class {
   }
   async readModule(name, requiredBy) {
     await this.assertExists();
-    return loadModuleFolder(join8(this.dir, name), name, requiredBy);
+    return loadModuleFolder(join9(this.dir, name), name, requiredBy);
   }
   async listModules() {
     await this.assertExists();
     const names = [];
     for (const name of await readDirNames(this.dir)) {
-      if (await pathExists(join8(this.dir, name, "registry-item.json"))) {
+      if (await pathExists(join9(this.dir, name, "registry-item.json"))) {
         names.push(name);
       }
     }
@@ -3209,9 +3419,9 @@ var RemoteRegistrySource = class {
   }
   async readModule(name, requiredBy) {
     const { sha } = await this.resolve();
-    const parent = await mkdtemp(join8(tmpdir(), "saasaloy-reg-"));
+    const parent = await mkdtemp(join9(tmpdir(), "saasaloy-reg-"));
     this.tempDirs.push(parent);
-    const dir = join8(parent, name);
+    const dir = join9(parent, name);
     try {
       await withDeadline(
         downloadTemplate(
@@ -3513,20 +3723,6 @@ function wantsHelp(argv) {
   return argv.includes("--help") || argv.includes("-h");
 }
 
-// src/version.ts
-import { readFile as readFile10 } from "fs/promises";
-import { fileURLToPath as fileURLToPath2 } from "url";
-var UNKNOWN_VERSION2 = "unknown";
-async function readVersion() {
-  try {
-    const file = fileURLToPath2(new URL("../package.json", import.meta.url));
-    const parsed = JSON.parse(await readFile10(file, "utf-8"));
-    return typeof parsed.version === "string" ? parsed.version : UNKNOWN_VERSION2;
-  } catch {
-    return UNKNOWN_VERSION2;
-  }
-}
-
 // src/commands/descriptions.ts
 var DESCRIPTIONS = {
   init: "scaffold a new Saasaloy project (base: Astro landing + ui + config)",
@@ -3675,12 +3871,12 @@ ${pc2.dim("New workspace(s) \u2014 run `pnpm install` to link them.")}`
     );
   }
   for (const conflict of plan.aliasConflicts) {
-    log.warn(
+    log2.warn(
       `Alias redefinition: ${conflict} ${pc2.dim("(scaffold overrides the existing alias)")}.`
     );
   }
   for (const stale of plan.staleOwners) {
-    log.warn(describeStaleOwner({ ...stale, target: pc2.cyan(stale.target) }));
+    log2.warn(describeStaleOwner({ ...stale, target: pc2.cyan(stale.target) }));
   }
   const newLinks = plan.links.filter((l) => l.action !== "conflict");
   if (newLinks.length > 0) {
@@ -3698,7 +3894,7 @@ ${pc2.dim("Symlinked for Claude Code \u2014 the skill files live in `.agents/ski
   }
   for (const link of plan.links) {
     if (link.action === "conflict") {
-      log.warn(
+      log2.warn(
         `Skill link ${pc2.cyan(link.path)} already exists and isn't ours \u2014 left untouched ${pc2.dim("(remove it to let `add` link the skill)")}.`
       );
     }
@@ -3712,7 +3908,7 @@ ${pc2.dim("Symlinked for Claude Code \u2014 the skill files live in `.agents/ski
   }
   for (const p of plan.patches) {
     if (p.action === "missing") {
-      log.warn(
+      log2.warn(
         `Config patch target ${pc2.cyan(p.file)} is missing \u2014 ${p.patch.kind} not applied ${pc2.dim(`(is ${p.module}'s prerequisite installed?)`)}.`
       );
     }
@@ -3727,7 +3923,7 @@ function wireUpSteps(result, aliases) {
     return [];
   }
   const skillByModule = new Map(
-    result.links.map((link) => [link.module, posix4.basename(link.path)])
+    result.links.map((link) => [link.module, posix3.basename(link.path)])
   );
   const byModule = /* @__PURE__ */ new Map();
   for (const block of blocks) {
@@ -3743,13 +3939,13 @@ function wireUpSteps(result, aliases) {
     const verb = moduleTargets.length === 1 ? "is" : "are";
     const skill = skillByModule.get(module);
     if (skill === void 0) {
-      log.warn(
+      log2.warn(
         `${pc2.cyan(module)} wrote ${targets} but ships no skill \u2014 its wire-up steps are missing. Import the block yourself ${pc2.dim("(a module that ships a block should ship a skill with a Wire-up section)")}.`
       );
       continue;
     }
     lines.push(
-      `Manual wire-up needed \u2014 ${targets} ${verb} on disk but on no page yet. In Claude Code, run ${pc2.cyan(`/${skill}`)} and follow its Wire-up section.`
+      `Manual wire-up needed \u2014 ${targets} ${verb} on disk but on no page yet. In your AI coding tool, run ${pc2.cyan(`/${skill}`)} and follow its Wire-up section.`
     );
   }
   return lines;
@@ -3762,7 +3958,8 @@ function envSteps(names, devVarsPath) {
   const where = devVarsPath ? ` ${pc2.dim(`${devVarsPath} keeps the checked-in description of each.`)}` : "";
   return [
     `Set ${keys.map((key) => pc2.cyan(key)).join(", ")}.`,
-    `Run ${pc2.cyan("saasaloy env")} \u2014 it prompts for each unset one and writes it to the ${pc2.cyan(".dev.vars")} or ${pc2.cyan(".env")} that reads it.${where}`
+    `Run ${pc2.cyan("saasaloy env")} \u2014 it prompts for each unset one and writes it to ${pc2.cyan("packages/env/.env")}.${where}`,
+    `Then run ${pc2.cyan("pnpm env:setup")} to write each service's own ${pc2.cyan(".env")} from it.`
   ];
 }
 function formatIncomplete(incomplete, requested) {
@@ -3785,11 +3982,11 @@ async function persistState(input) {
     );
   } catch (error) {
     failures.push(error);
-    log.warn(`Couldn't pin ${LOCK_FILE} \u2014 ${formatFailure(error)}.`);
+    log2.warn(`Couldn't pin ${LOCK_FILE} \u2014 ${formatFailure(error)}.`);
   }
   for (const failure of await persistLedger(input)) {
     failures.push(failure.error);
-    log.warn(
+    log2.warn(
       `Couldn't write ${failure.file} \u2014 ${formatFailure(failure.error)}.`
     );
   }
@@ -3820,10 +4017,10 @@ async function applyAndPersist(input) {
 }
 function printNextSteps(plan, result, devVarsPath, aliases) {
   const lines = [...wireUpSteps(result, aliases)];
-  const skills = result.links.map((link) => posix4.basename(link.path)).toSorted();
+  const skills = result.links.map((link) => posix3.basename(link.path)).toSorted();
   if (skills.length > 0) {
     lines.push(
-      `Read the module's own procedure \u2014 in Claude Code, run ${skills.map((name) => pc2.cyan(`/${name}`)).join(" or ")}.`
+      `Read the module's own procedure \u2014 in your AI coding tool, run ${skills.map((name) => pc2.cyan(`/${name}`)).join(" or ")}.`
     );
   }
   lines.push(...envSteps(Object.keys(plan.envVars), devVarsPath));
@@ -3876,7 +4073,7 @@ async function runAdd(argv) {
     coord = pinToLock(coord, lock);
     source = createRegistrySource(coord);
     if (process.env[REGISTRY_ENV] && (coord.owner || coord.repo)) {
-      log.warn(
+      log2.warn(
         `Ignoring source "${coord.owner}/${coord.repo}" \u2014 ${REGISTRY_ENV} override is set.`
       );
     }
@@ -3958,7 +4155,7 @@ async function runAdd(argv) {
     const manifest = await loadManifest(root);
     const conflicts = detectConflicts({ graph, config, lock });
     if (conflicts.missingLockEntries.length > 0) {
-      log.warn(
+      log2.warn(
         `No lock entry for ${conflicts.missingLockEntries.map((m) => pc2.cyan(m)).join(", ")} \u2014 any conflict they declare can't be checked ${pc2.dim("(re-add them to record it)")}.`
       );
     }
@@ -3991,7 +4188,7 @@ async function runAdd(argv) {
     });
     summarizePlan(plan, requested, prereqs);
     if (planWritesUi(plan)) {
-      log.info(
+      log2.info(
         `This module writes ${pc2.cyan("packages/ui/")}. Run ${pc2.cyan("/saasaloy-design update")} after it applies.`
       );
     }
@@ -4057,41 +4254,45 @@ async function runAdd(argv) {
         await writeDeps(root, pkg, added, devAdded);
         depsAdded = [...added, ...devAdded].map((d) => d.name);
         for (const conflict of depConflicts) {
-          log.warn(`Dependency version conflict \u2014 ${conflict}.`);
+          log2.warn(`Dependency version conflict \u2014 ${conflict}.`);
         }
       } else {
-        log.warn(
+        log2.warn(
           `No package.json at the project root \u2014 add ${allDeps.join(", ")} yourself.`
         );
       }
     }
     for (const file of result.written) {
-      log.step(`${ACTION_LABEL[file.action]}  ${file.target}`);
+      log2.step(`${ACTION_LABEL[file.action]}  ${file.target}`);
     }
     for (const file of result.refreshed) {
-      log.step(`${ACTION_LABEL[file.action]}  ${file.target}`);
+      log2.step(`${ACTION_LABEL[file.action]}  ${file.target}`);
     }
     for (const link of result.links) {
       const label = link.action === "create" ? pc2.green("link") : pc2.dim("link");
-      log.step(`${label}  ${link.path} ${pc2.dim(`\u2192 ${link.target}`)}`);
+      log2.step(`${label}  ${link.path} ${pc2.dim(`\u2192 ${link.target}`)}`);
     }
     for (const link of result.linkConflicts) {
-      log.warn(
+      log2.warn(
         `Skill link ${pc2.cyan(link.path)} left untouched \u2014 a non-saasaloy path already occupies it.`
       );
     }
     for (const p of result.patched) {
-      log.step(
+      log2.step(
         `${pc2.green("patch")}  ${p.file} ${pc2.dim(`\u2014 ${p.patch.kind}`)}`
       );
     }
+    await formatPatchedFiles(
+      root,
+      result.patched.map((p) => p.file)
+    );
     for (const p of result.patchConflicts) {
-      log.warn(
+      log2.warn(
         `Config patch target ${pc2.cyan(p.file)} missing \u2014 ${p.patch.kind} skipped.`
       );
     }
     for (const r of result.patchRefusals) {
-      log.warn(
+      log2.warn(
         `Config patch on ${pc2.cyan(r.patch.file)} skipped \u2014 ${r.reason}. Wire it by hand.`
       );
     }
@@ -4110,7 +4311,7 @@ ${pc2.dim("Changed while the plan was open \u2014 left alone rather than overwri
       (name) => !result.completed.includes(name)
     );
     if (incomplete.length > 0) {
-      log.warn(formatIncomplete(incomplete, requested));
+      log2.warn(formatIncomplete(incomplete, requested));
     }
     if (result.heldBack.length > 0) {
       const merges = result.heldBack.map((f) => `  ${ACTION_LABEL[f.action]}  ${f.target}`).join("\n");
@@ -4133,16 +4334,22 @@ ${pc2.dim("Run `pnpm install` to fetch them.")}`
         "Dependencies added"
       );
     }
+    if (plan.envServicesGuessed.length > 0) {
+      log2.warn(
+        `${plan.envServicesGuessed.join(", ")} declare env vars without \`envServices\`, so the PUBLIC_ prefix decided which service reads each one. Check ${ENV_EXAMPLE}.`
+      );
+    }
     let devVarsPath;
     try {
-      devVarsPath = await writeDevVarsExample({
-        aliases: config.aliases,
+      devVarsPath = await writeEnvExample({
         devVars: plan.devVars,
         envVars: plan.envVars,
+        optional: plan.envOptional,
+        services: plan.envServices,
         root
       });
     } catch (error) {
-      log.warn(`Couldn't write ${DEV_VARS_EXAMPLE} \u2014 ${formatFailure(error)}.`);
+      log2.warn(`Couldn't write ${ENV_EXAMPLE} \u2014 ${formatFailure(error)}.`);
     }
     printNextSteps(plan, result, devVarsPath, config.aliases);
     outro(
@@ -4155,7 +4362,7 @@ ${pc2.dim("Run `pnpm install` to fetch them.")}`
     return EXIT_OK;
   } catch (error) {
     if (partial) {
-      log.warn(formatRecovery(partial));
+      log2.warn(formatRecovery(partial));
     }
     cancel(formatFailure(error));
     return exitCodeFor(error);
@@ -4165,25 +4372,25 @@ ${pc2.dim("Run `pnpm install` to fetch them.")}`
 }
 
 // src/commands/doctor.ts
-import { cancel as cancel2, intro as intro2, log as log2, note as note2, outro as outro2 } from "@clack/prompts";
-import { join as join12, relative as relative2 } from "path";
+import { cancel as cancel2, intro as intro2, log as log3, note as note2, outro as outro2 } from "@clack/prompts";
+import { join as join13, relative as relative2 } from "path";
 import pc3 from "picocolors";
 
 // src/lib/base.ts
 import { createHash as createHash2 } from "crypto";
 import { mkdtemp as mkdtemp2, readdir as readdir3, readFile as readFile12, rm as rm2 } from "fs/promises";
 import { tmpdir as tmpdir2 } from "os";
-import { join as join10, posix as posix6 } from "path";
+import { join as join11, posix as posix5 } from "path";
 
 // src/lib/scaffold.ts
 import { mkdir as mkdir5, readdir as readdir2, readFile as readFile11, writeFile as writeFile7 } from "fs/promises";
-import { join as join9, posix as posix5 } from "path";
+import { join as join10, posix as posix4 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 
 // package.json
 var package_default = {
   name: "saasaloy",
-  version: "0.5.1",
+  version: "0.6.0",
   description: "Composable SaaS accelerator kit.",
   keywords: [
     "saas",
@@ -4222,6 +4429,7 @@ var package_default = {
   },
   scripts: {
     build: "tsup",
+    clean: "rimraf dist coverage",
     prepack: "pnpm -w run readme:cli && pnpm run build",
     dev: "tsup --watch",
     start: "node ./dist/index.js",
@@ -4237,6 +4445,7 @@ var package_default = {
     "@types/node": "26.4.1",
     "@vitest/coverage-v8": "5.0.0",
     "release-it": "21.0.2",
+    rimraf: "6.1.3",
     tsup: "8.5.1",
     vitest: "5.0.0"
   },
@@ -4257,7 +4466,7 @@ var TEMPLATE_DIR_CANDIDATES = ["../templates/base", "../../templates/base"];
 async function baseTemplateDir() {
   for (const candidate of TEMPLATE_DIR_CANDIDATES) {
     const dir = fileURLToPath3(new URL(candidate, import.meta.url));
-    if (await pathExists(join9(dir, "package.json"))) {
+    if (await pathExists(join10(dir, "package.json"))) {
       return dir;
     }
   }
@@ -4280,11 +4489,11 @@ async function copyTree(srcDir, destDir, vars, options, fromPrefix, targetPrefix
     if (isRoot && entry.name === BASE_DECLARATION) {
       continue;
     }
-    const srcPath = join9(srcDir, entry.name);
+    const srcPath = join10(srcDir, entry.name);
     const outName = renderedName(entry.name);
-    const destPath = join9(destDir, options.keepNames ? entry.name : outName);
-    const from = posix5.join(fromPrefix, entry.name);
-    const target = posix5.join(targetPrefix, outName);
+    const destPath = join10(destDir, options.keepNames ? entry.name : outName);
+    const from = posix4.join(fromPrefix, entry.name);
+    const target = posix4.join(targetPrefix, outName);
     if (entry.isDirectory()) {
       written.push(
         ...await copyTree(
@@ -4334,9 +4543,9 @@ function ownedMatcher(declaration) {
   return (target) => patterns.some((re) => re.test(target));
 }
 async function readBaseDeclaration(templateDir) {
-  const raw = await readIfPresent(join10(templateDir, BASE_DECLARATION));
+  const raw = await readIfPresent(join11(templateDir, BASE_DECLARATION));
   if (raw === void 0) {
-    return { seedFiles: [], ownedFiles: [] };
+    return { seedFiles: [], retiredSeedFiles: [], ownedFiles: [] };
   }
   const parsed = JSON.parse(raw);
   const seedFiles = parsed.seedFiles;
@@ -4345,6 +4554,14 @@ async function readBaseDeclaration(templateDir) {
       `${BASE_DECLARATION} must declare "seedFiles" as a list of project-relative paths.`
     );
   }
+  const retiredSeedFiles = parsed.retiredSeedFiles ?? [];
+  if (!Array.isArray(retiredSeedFiles) || !retiredSeedFiles.every(
+    (entry) => typeof entry === "string" && entry !== ""
+  )) {
+    throw new Error(
+      `${BASE_DECLARATION} must declare "retiredSeedFiles" as a list of project-relative paths.`
+    );
+  }
   const ownedFiles = parsed.ownedFiles ?? [];
   if (!Array.isArray(ownedFiles) || !ownedFiles.every((entry) => typeof entry === "string" && entry !== "")) {
     throw new Error(
@@ -4352,7 +4569,8 @@ async function readBaseDeclaration(templateDir) {
     );
   }
   return {
-    seedFiles,
+    seedFiles: [...seedFiles, ...retiredSeedFiles],
+    retiredSeedFiles,
     ownedFiles
   };
 }
@@ -4363,9 +4581,9 @@ async function listTemplateFiles(templateDir) {
       if (isRoot && entry.name === BASE_DECLARATION) {
         continue;
       }
-      const from = posix6.join(fromPrefix, entry.name);
-      const target = posix6.join(targetPrefix, renderedName(entry.name));
-      const abs = join10(dir, entry.name);
+      const from = posix5.join(fromPrefix, entry.name);
+      const target = posix5.join(targetPrefix, renderedName(entry.name));
+      const abs = join11(dir, entry.name);
       if (entry.isDirectory()) {
         await walk(abs, from, target, false);
       } else if (entry.isFile()) {
@@ -4439,7 +4657,7 @@ async function missingBaseTargets(root, manifest, templateDir) {
   return missing.toSorted((a, b) => a < b ? -1 : 1);
 }
 async function renderTemplate(root, templateDir, projectName) {
-  const dir = await mkdtemp2(join10(tmpdir2(), "saasaloy-base-render-"));
+  const dir = await mkdtemp2(join11(tmpdir2(), "saasaloy-base-render-"));
   const files = await copyTemplate(
     templateDir,
     dir,
@@ -4555,7 +4773,7 @@ async function baseUpdateInput(args) {
 import { findNodeAtLocation as findNodeAtLocation4, getNodeValue as getNodeValue4, parseTree as parseTree4 } from "jsonc-parser";
 import { parseModule as parseModule7 } from "magicast";
 import { readFile as readFile13 } from "fs/promises";
-import { basename, dirname as dirname6, join as join11, posix as posix7, resolve as resolve3 } from "path";
+import { basename, dirname as dirname6, join as join12, posix as posix6, resolve as resolve3 } from "path";
 var SKILL_PREFIX = "saasaloy-";
 var PINNED_DEP = /^(@[^/@]+\/)?[^/@]+@\d+\.\d+\.\d+(-[\w.-]+)?(\+[\w.-]+)?$/;
 function finding(module, where, message) {
@@ -4570,7 +4788,7 @@ function asRecord(value) {
 async function registryModuleNames(dir) {
   const names = [];
   for (const name of await readDirNames(dir)) {
-    if (await pathExists(join11(dir, name, "registry-item.json"))) {
+    if (await pathExists(join12(dir, name, "registry-item.json"))) {
       names.push(name);
     }
   }
@@ -4579,12 +4797,12 @@ async function registryModuleNames(dir) {
 async function collectAliases(registryDir, names) {
   const templateDir = await baseTemplateDir();
   let base = {};
-  if (await pathExists(join11(templateDir, "saasaloy.json"))) {
+  if (await pathExists(join12(templateDir, "saasaloy.json"))) {
     base = (await loadConfig(templateDir)).aliases;
   }
   const fromScaffolds = {};
   for (const name of names) {
-    const item = asRecord(await readDescriptor(join11(registryDir, name)));
+    const item = asRecord(await readDescriptor(join12(registryDir, name)));
     for (const scaffold of asArray2(item.scaffolds)) {
       const aliases = asRecord(asRecord(scaffold).aliases);
       for (const [alias, prefix] of Object.entries(aliases)) {
@@ -4597,7 +4815,7 @@ async function collectAliases(registryDir, names) {
   return { base, fromScaffolds };
 }
 async function readDescriptor(dir) {
-  const file = join11(dir, "registry-item.json");
+  const file = join12(dir, "registry-item.json");
   if (!await pathExists(file)) {
     return void 0;
   }
@@ -4612,7 +4830,7 @@ async function checkModule(input) {
   const module = basename(dir);
   const findings = [];
   const report = () => ({ dir, findings, module });
-  const file = join11(dir, "registry-item.json");
+  const file = join12(dir, "registry-item.json");
   if (!await pathExists(file)) {
     findings.push(
       finding(module, "(root)", `no registry-item.json in ${module}/`)
@@ -4730,6 +4948,28 @@ async function checkModule(input) {
       );
     }
   }
+  for (const key of Object.keys(asRecord(item.envServices))) {
+    if (key !== "default" && !(key in asRecord(item.envVars))) {
+      findings.push(
+        finding(
+          module,
+          `/envServices/${key}`,
+          "has no matching entry in envVars, so it routes nothing"
+        )
+      );
+    }
+  }
+  for (const key of asArray2(item.envOptional)) {
+    if (typeof key === "string" && !(key in asRecord(item.envVars))) {
+      findings.push(
+        finding(
+          module,
+          `/envOptional/${key}`,
+          "has no matching entry in envVars, so nothing marks it blank on purpose"
+        )
+      );
+    }
+  }
   for (const key of Object.keys(asRecord(item.devVars))) {
     if (!(key in asRecord(item.envVars))) {
       findings.push(
@@ -4745,7 +4985,7 @@ async function checkModule(input) {
     if (typeof skill !== "string") {
       continue;
     }
-    const folder = posix7.basename(skill);
+    const folder = posix6.basename(skill);
     if (!folder.startsWith(SKILL_PREFIX)) {
       findings.push(
         finding(
@@ -4979,7 +5219,7 @@ async function readPolicyState(root, installed) {
     const source = await readIfPresent(
       resolveWithinRoot(
         root,
-        posix7.join(posix7.dirname(KV_INDEX_FILE), `${specifier}.ts`)
+        posix6.join(posix6.dirname(KV_INDEX_FILE), `${specifier}.ts`)
       )
     );
     if (source !== void 0) {
@@ -5006,7 +5246,7 @@ function relativeImportsIn(index) {
 }
 async function resolveDoctorTarget(path) {
   const dir = resolve3(path);
-  if (await pathExists(join11(dir, "registry-item.json"))) {
+  if (await pathExists(join12(dir, "registry-item.json"))) {
     return { names: [basename(dir)], registryDir: dirname6(dir) };
   }
   return { names: await registryModuleNames(dir), registryDir: dir };
@@ -5028,6 +5268,54 @@ function checkPartialInstalls(state) {
     )
   );
 }
+var LEGACY_ENV_FILES = [".dev.vars", ".dev.vars.example"];
+function checkEnv(args) {
+  const findings = args.legacy.toSorted().map(
+    (path) => finding(
+      "env",
+      `/${path}`,
+      `${path} still exists, and nothing reads it. wrangler loads .env only while no .dev.vars sits beside it, so every value pnpm env:setup writes is ignored. Run \`pnpm env:setup\` to carry its values into .env and delete it.`
+    )
+  );
+  if (args.legacy.length > 0 && !args.hasKeyList) {
+    findings.push(
+      finding(
+        "env",
+        `/${ENV_EXAMPLE}`,
+        `${ENV_EXAMPLE} is missing, so there is no key list to migrate those values into. Re-run \`saasaloy add\` for an installed module to regenerate it.`
+      )
+    );
+  }
+  return findings;
+}
+var INFRA_RUNBOOK = "https://github.com/mimukit/saasaloy/blob/main/docs/wiki/runbooks/move-off-the-infra-module.md";
+function checkRetiredInfra(hasInfra) {
+  return hasInfra ? [
+    finding(
+      "deploy",
+      "/infra",
+      `infra/ is the Pulumi deploy that pnpm deploy:production replaced, and nothing runs it any more. Never run pulumi destroy: it deletes the live Workers and their data. Follow ${INFRA_RUNBOOK} to move the resource ids into wrangler.jsonc, then delete infra/.`
+    )
+  ] : [];
+}
+function hasRetiredInfra(root) {
+  return pathExists(resolveWithinRoot(root, "infra"));
+}
+async function readEnvState(root) {
+  const legacy = [];
+  for (const workspace of ["apps/api", "apps/web", "apps/admin"]) {
+    for (const name of LEGACY_ENV_FILES) {
+      const path = posix6.join(workspace, name);
+      if (await pathExists(resolveWithinRoot(root, path))) {
+        legacy.push(path);
+      }
+    }
+  }
+  return {
+    legacy,
+    hasKeyList: await pathExists(resolveWithinRoot(root, ENV_EXAMPLE))
+  };
+}
 async function checkTarget(target) {
   const siblings = await registryModuleNames(target.registryDir);
   const aliases = await collectAliases(target.registryDir, siblings);
@@ -5036,7 +5324,7 @@ async function checkTarget(target) {
     reports.push(
       await checkModule({
         aliases,
-        dir: join11(target.registryDir, name),
+        dir: join12(target.registryDir, name),
         siblings
       })
     );
@@ -5150,10 +5438,13 @@ async function reportProject(path) {
   });
   note2(wrapForNote(renderBase(base)), "Base");
   const policyState = await readPolicyState(path, config.installed);
+  const envState = await readEnvState(path);
   const findings = [
     ...checkProject({ config, manifest }),
     ...checkPartialInstalls({ installed: config.installed, manifest }),
-    ...policyState ? checkPolicyBindings(policyState) : []
+    ...policyState ? checkPolicyBindings(policyState) : [],
+    ...checkEnv(envState),
+    ...checkRetiredInfra(await hasRetiredInfra(path))
   ];
   if (findings.length === 0) {
     const count = config.installed.length;
@@ -5198,7 +5489,7 @@ async function runDoctor(argv) {
       );
       return EXIT_REFUSED;
     }
-    if (await pathExists(join12(path, CONFIG_FILE))) {
+    if (await pathExists(join13(path, CONFIG_FILE))) {
       return await reportProject(path);
     }
     const target = await resolveDoctorTarget(path);
@@ -5228,7 +5519,7 @@ async function runDoctor(argv) {
         `${pc3.yellow(report.module)} ${pc3.dim(`(${report.findings.length})`)}`
       );
     }
-    log2.info(
+    log3.info(
       pc3.dim(
         `Checked ${reports.length} module${reports.length === 1 ? "" : "s"}; ${reports.length - bad.length} clean.`
       )
@@ -5250,118 +5541,29 @@ import {
   cancel as cancel3,
   intro as intro3,
   isCancel as isCancel2,
-  log as log3,
+  log as log4,
   note as note3,
   outro as outro3,
-  select as select2,
   text
 } from "@clack/prompts";
 import pc4 from "picocolors";
 
 // src/lib/env-vars.ts
-import { posix as posix8 } from "path";
-var ENV_FILE = ".env";
-var DEV_VARS_FILE = ".dev.vars";
-var PUBLIC_PREFIX = "PUBLIC_";
-var APPS_DIR = "apps/";
-var WRANGLER_CONFIGS = ["wrangler.jsonc", "wrangler.json", "wrangler.toml"];
-function isPublicVar(name) {
-  return name.startsWith(PUBLIC_PREFIX);
-}
-function targetFileName(name) {
-  return isPublicVar(name) ? ENV_FILE : DEV_VARS_FILE;
-}
-function resolved(workspace) {
-  return workspace ? { kind: "resolved", workspace } : void 0;
-}
-function routeVariable(args) {
-  const { candidates, wranglerWorkspaces } = args;
-  if (isPublicVar(args.name)) {
-    const apps = candidates.filter(
-      (w) => w.startsWith(APPS_DIR) && w !== args.apiWorkspace
-    );
-    if (apps.length === 1) {
-      return { kind: "resolved", workspace: apps[0] };
-    }
-    if (apps.length > 1) {
-      return { choices: apps.toSorted(), kind: "ambiguous" };
-    }
-    return resolved(args.baseWorkspace) ?? fromCandidatesAlone(candidates);
-  }
-  const wrangler = candidates.filter((w) => wranglerWorkspaces.includes(w));
-  if (wrangler.length === 1) {
-    return { kind: "resolved", workspace: wrangler[0] };
-  }
-  if (wrangler.length > 1) {
-    return (args.apiWorkspace && wrangler.includes(args.apiWorkspace) ? resolved(args.apiWorkspace) : void 0) ?? { choices: wrangler.toSorted(), kind: "ambiguous" };
-  }
-  return resolved(args.apiWorkspace) ?? fromCandidatesAlone(candidates);
-}
-function fromCandidatesAlone(candidates) {
-  if (candidates.length === 1) {
-    return { kind: "resolved", workspace: candidates[0] };
-  }
-  return candidates.length === 0 ? { kind: "unknown" } : { choices: candidates.toSorted(), kind: "ambiguous" };
-}
-async function discoverWorkspaces(root, aliases) {
-  const found = /* @__PURE__ */ new Set();
-  for (const value of Object.values(aliases)) {
-    const workspace = await walkUpToWorkspace(root, value);
-    if (workspace) {
-      found.add(workspace);
-    }
-  }
-  return [...found].toSorted();
-}
-async function walkUpToWorkspace(root, relPosixPath) {
-  let current = relPosixPath.replace(/\/+$/, "");
-  while (current && current !== "." && current !== "/") {
-    if (await pathExists(resolveWithinRoot(root, `${current}/package.json`))) {
-      return current;
-    }
-    const parent = posix8.dirname(current);
-    if (parent === current) {
-      return void 0;
-    }
-    current = parent;
-  }
-  return void 0;
-}
-async function findWranglerWorkspaces(root, workspaces) {
-  const found = [];
-  for (const workspace of workspaces) {
-    for (const config of WRANGLER_CONFIGS) {
-      if (await pathExists(resolveWithinRoot(root, `${workspace}/${config}`))) {
-        found.push(workspace);
-        break;
-      }
-    }
-  }
-  return found;
-}
-function workspacesByModule(manifest, workspaces) {
-  const byModule = /* @__PURE__ */ new Map();
-  for (const [path, entry] of Object.entries(manifest.managed)) {
-    const workspace = workspaceForPath(path, workspaces);
-    if (!workspace) {
+var LOCAL_VALUES = "packages/env/.env";
+function parseEnvValues(text4) {
+  const values = {};
+  for (const line of text4.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
       continue;
     }
-    const set = byModule.get(entry.module) ?? /* @__PURE__ */ new Set();
-    set.add(workspace);
-    byModule.set(entry.module, set);
-  }
-  return new Map(
-    [...byModule].map(([module, set]) => [module, [...set].toSorted()])
-  );
-}
-function workspaceForPath(path, workspaces) {
-  let best;
-  for (const workspace of workspaces) {
-    if (path.startsWith(`${workspace}/`) && (best === void 0 || workspace.length > best.length)) {
-      best = workspace;
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) {
+      continue;
     }
+    values[trimmed.slice(0, eq).trim()] = trimmed.slice(eq + 1);
   }
-  return best;
+  return values;
 }
 function isSet(values, name) {
   return (values[name] ?? "").trim() !== "";
@@ -5397,27 +5599,20 @@ function appendVars(existing, additions) {
   return appended.length === 0 ? head : `${head}${appended.join("\n")}
 `;
 }
-function productionSecretCommands(targets) {
-  const byWorkspace = /* @__PURE__ */ new Map();
-  for (const { name, workspace } of targets) {
-    if (isPublicVar(name)) {
-      continue;
-    }
-    byWorkspace.set(workspace, [...byWorkspace.get(workspace) ?? [], name]);
-  }
-  const lines = [];
-  for (const workspace of [...byWorkspace.keys()].toSorted()) {
-    lines.push(`# from ${workspace}`);
-    for (const name of (byWorkspace.get(workspace) ?? []).toSorted()) {
-      lines.push(`wrangler secret put ${name}`);
-    }
+function productionSecretCommands(names) {
+  const secrets = names.filter((name) => !isPublicVar(name)).toSorted();
+  if (secrets.length === 0) {
+    return [];
   }
-  return lines;
+  return [
+    "# from the Worker's workspace, e.g. apps/api",
+    ...secrets.map((name) => `wrangler secret put ${name}`)
+  ];
 }
 
 // src/lib/gitignore.ts
 import { readFile as readFile14 } from "fs/promises";
-import { dirname as dirname7, join as join13, relative as relative3, resolve as resolve4, sep as sep2 } from "path";
+import { dirname as dirname7, join as join14, relative as relative3, resolve as resolve4, sep as sep2 } from "path";
 var REGEX_SPECIAL = /[.+^${}()|[\]\\]/g;
 function globToRegex(glob) {
   let out = "";
@@ -5501,7 +5696,7 @@ function excludes(layers, candidate, isDir) {
 async function findRepoRoot(start) {
   let current = resolve4(start);
   for (; ; ) {
-    if (await pathExists(join13(current, ".git"))) {
+    if (await pathExists(join14(current, ".git"))) {
       return current;
     }
     const parent = dirname7(current);
@@ -5518,7 +5713,7 @@ async function isPathIgnored(root, relPosixPath) {
   }
   const fromRepo = relative3(
     repoRoot,
-    join13(resolve4(root), ...relPosixPath.split("/"))
+    join14(resolve4(root), ...relPosixPath.split("/"))
   );
   const segments = fromRepo.split(sep2).filter(Boolean);
   if (segments.length === 0 || segments.includes("..")) {
@@ -5527,7 +5722,7 @@ async function isPathIgnored(root, relPosixPath) {
   const layers = [];
   for (let depth = 0; depth < segments.length; depth += 1) {
     const parts = segments.slice(0, depth);
-    const file = join13(repoRoot, ...parts, ".gitignore");
+    const file = join14(repoRoot, ...parts, ".gitignore");
     if (await pathExists(file)) {
       layers.push({
         base: parts.join("/"),
@@ -5565,16 +5760,9 @@ function parseArgs3(argv) {
   return { check: argv.includes("--check"), unknown };
 }
 function renderPending(pending) {
-  return pending.map((entry) => {
-    const head = `${pc4.cyan(entry.declaration.name)} ${pc4.dim(`\u2014 declared by ${entry.declaration.module}`)}`;
-    if (entry.file) {
-      return `${head}
-  ${pc4.dim(`\u2192 ${entry.file}`)}`;
-    }
-    const why = entry.choices ? `several workspaces fit (${entry.choices.join(", ")}) \u2014 run \`saasaloy env\` to pick one` : "no target workspace found \u2014 this module wrote no files under a known alias";
-    return `${head}
-  ${pc4.yellow(`\u2192 ${why}`)}`;
-  });
+  return pending.map(
+    (entry) => `${pc4.cyan(entry.declaration.name)} ${pc4.dim(`\u2014 declared by ${entry.declaration.module}`)}`
+  );
 }
 async function loadDeclarations(config, lock, sources, onSkip) {
   const override = process.env[REGISTRY_ENV];
@@ -5643,31 +5831,15 @@ async function loadDeclarations(config, lock, sources, onSkip) {
     return true;
   });
 }
-function workspaceForAlias(aliases, alias, workspaces) {
-  const value = aliases[alias];
-  if (!value) {
-    return void 0;
-  }
-  return workspaceForPath(
-    value.endsWith("/") ? value : `${value}/`,
-    workspaces
-  );
-}
-async function writeAnswers(root, answers, contents) {
-  const written = [];
-  for (const [file, additions] of [...answers].toSorted(
-    ([a], [b]) => a.localeCompare(b)
-  )) {
-    if (additions.length === 0) {
-      continue;
-    }
-    const abs = resolveWithinRoot(root, file);
-    await assertNoSymlinkPath(root, abs);
-    await mkdir6(dirname8(abs), { recursive: true });
-    await writeFile8(abs, appendVars(contents.get(file), additions), "utf-8");
-    written.push([file, additions.length]);
+async function writeAnswers(root, additions, before) {
+  if (additions.length === 0) {
+    return 0;
   }
-  return written;
+  const abs = resolveWithinRoot(root, LOCAL_VALUES);
+  await assertNoSymlinkPath(root, abs);
+  await mkdir6(dirname8(abs), { recursive: true });
+  await writeFile8(abs, appendVars(before, additions), "utf-8");
+  return additions.length;
 }
 async function readTarget(root, file) {
   const abs = resolveWithinRoot(root, file);
@@ -5691,62 +5863,34 @@ async function runEnv(argv) {
   try {
     const root = await findProjectRoot();
     const config = await loadConfig(root);
-    const manifest = await loadManifest(root);
     const lock = await loadLock(root);
     const declarations = await loadDeclarations(
       config,
       lock,
       sources,
       (msg) => {
-        log3.warn(msg);
+        log4.warn(msg);
       }
     );
     if (declarations.length === 0) {
       outro3(pc4.dim("No module declares an environment variable."));
       return EXIT_OK;
     }
-    const workspaces = await discoverWorkspaces(root, config.aliases);
-    const wranglerWorkspaces = await findWranglerWorkspaces(root, workspaces);
-    const byModule = workspacesByModule(manifest, workspaces);
-    const api = apiWorkspace(config.aliases);
-    const base = workspaceForAlias(
-      config.aliases,
-      `@${config.base ?? "web"}`,
-      workspaces
-    );
-    const contents = /* @__PURE__ */ new Map();
-    const readOnce = async (file) => {
-      if (!contents.has(file)) {
-        contents.set(file, await readTarget(root, file));
-      }
-      return contents.get(file);
-    };
-    const pending = [];
-    const routed = [];
-    for (const declaration of declarations) {
-      const route = routeVariable({
-        candidates: byModule.get(declaration.module) ?? [],
-        name: declaration.name,
-        wranglerWorkspaces,
-        ...api ? { apiWorkspace: api } : {},
-        ...base ? { baseWorkspace: base } : {}
-      });
-      if (route.kind === "resolved") {
-        const file = `${route.workspace}/${targetFileName(declaration.name)}`;
-        routed.push({ name: declaration.name, workspace: route.workspace });
-        const values = parseDevVars(await readOnce(file) ?? "");
-        if (isSet(values, declaration.name)) {
-          continue;
-        }
-        pending.push({ declaration, file, workspace: route.workspace });
-        continue;
-      }
-      pending.push({
-        declaration,
-        ...route.kind === "ambiguous" ? { choices: route.choices } : {}
-      });
+    const listed = new Set(
+      Object.keys(parseEnvExample(await readTarget(root, ENV_EXAMPLE) ?? ""))
+    );
+    const undeclared = declarations.filter((declaration) => !listed.has(declaration.name)).map((declaration) => declaration.name);
+    if (undeclared.length > 0) {
+      log4.warn(
+        `${ENV_EXAMPLE} does not list ${undeclared.join(", ")}, so no service reads ${undeclared.length === 1 ? "it" : "them"}. Re-run \`saasaloy add\` for the declaring module to regenerate the key list.`
+      );
     }
-    const secretCommands = productionSecretCommands(routed);
+    const before = await readTarget(root, LOCAL_VALUES);
+    const values = parseEnvValues(before ?? "");
+    const pending = declarations.filter((declaration) => !isSet(values, declaration.name)).map((declaration) => ({ declaration }));
+    const secretCommands = productionSecretCommands(
+      declarations.map((declaration) => declaration.name)
+    );
     const printSecrets = () => {
       if (secretCommands.length > 0) {
         note3(
@@ -5764,16 +5908,11 @@ ${pc4.dim("Printed, never run \u2014 copy these when you deploy.")}`
       outro3(pc4.green("Every declared variable is set."));
       return EXIT_OK;
     }
-    const files = [
-      ...new Set(pending.flatMap((entry) => entry.file ? [entry.file] : []))
-    ].toSorted();
-    for (const file of files) {
-      if (!await isPathIgnored(root, file)) {
-        cancel3(
-          `${pc4.cyan(file)} isn't gitignored \u2014 refusing to write a secret into a tracked file. Add it to .gitignore (the base template already does) and run again.`
-        );
-        return EXIT_REFUSED;
-      }
+    if (!await isPathIgnored(root, LOCAL_VALUES)) {
+      cancel3(
+        `${pc4.cyan(LOCAL_VALUES)} isn't gitignored \u2014 refusing to write a secret into a tracked file. Add it to .gitignore (the base template already does) and run again.`
+      );
+      return EXIT_REFUSED;
     }
     if (opts.check || !isInteractive()) {
       note3(wrapForNote(renderPending(pending).join("\n")), "Missing");
@@ -5784,42 +5923,11 @@ ${pc4.dim("Printed, never run \u2014 copy these when you deploy.")}`
       );
       return EXIT_REFUSED;
     }
-    const answers = /* @__PURE__ */ new Map();
+    const answers = [];
     for (const entry of pending) {
-      let file = entry.file;
-      if (!file) {
-        if (!entry.choices) {
-          log3.warn(
-            `${pc4.cyan(entry.declaration.name)} \u2014 no target workspace found; set it by hand.`
-          );
-          continue;
-        }
-        const picked = await select2({
-          message: `Which workspace reads ${entry.declaration.name}?`,
-          options: entry.choices.map((workspace) => ({
-            label: workspace,
-            value: workspace
-          }))
-        });
-        if (isCancel2(picked)) {
-          cancel3("Cancelled \u2014 nothing written.");
-          return EXIT_REFUSED;
-        }
-        file = `${picked}/${targetFileName(entry.declaration.name)}`;
-        if (!await isPathIgnored(root, file)) {
-          cancel3(
-            `${pc4.cyan(file)} isn't gitignored \u2014 refusing to write a secret into a tracked file.`
-          );
-          return EXIT_REFUSED;
-        }
-        const values = parseDevVars(await readOnce(file) ?? "");
-        if (isSet(values, entry.declaration.name)) {
-          continue;
-        }
-      }
       const answer = await text({
         defaultValue: entry.declaration.devValue ?? "",
-        message: `${pc4.cyan(entry.declaration.name)} ${pc4.dim(`\u2192 ${file}`)}
+        message: `${pc4.cyan(entry.declaration.name)} ${pc4.dim(`\u2192 ${LOCAL_VALUES}`)}
 ${entry.declaration.description}`,
         ...entry.declaration.devValue === void 0 ? {} : { initialValue: entry.declaration.devValue }
       });
@@ -5827,18 +5935,15 @@ ${entry.declaration.description}`,
         cancel3("Cancelled \u2014 nothing written.");
         return EXIT_REFUSED;
       }
-      answers.set(file, [
-        ...answers.get(file) ?? [],
-        [entry.declaration.name, answer]
-      ]);
+      answers.push([entry.declaration.name, answer]);
     }
-    const written = await writeAnswers(root, answers, contents);
-    if (written.length > 0) {
+    const written = await writeAnswers(root, answers, before);
+    if (written > 0) {
       note3(
         wrapForNote(
-          written.map(
-            ([file, count]) => `${pc4.cyan(file)} ${pc4.dim(`\u2014 ${count} added`)}`
-          ).join("\n")
+          `${pc4.cyan(LOCAL_VALUES)} ${pc4.dim(`\u2014 ${written} added`)}
+
+${pc4.dim("Run `pnpm env:setup` to write each service's own .env from it.")}`
         ),
         "Written"
       );
@@ -5857,39 +5962,39 @@ ${entry.declaration.description}`,
 }
 
 // src/commands/init.ts
-import { spawn } from "child_process";
+import { spawn as spawn2 } from "child_process";
 import { readdir as readdir4, readFile as readFile16 } from "fs/promises";
-import { basename as basename2, join as join14, resolve as resolve6 } from "path";
+import { basename as basename2, join as join15, resolve as resolve6 } from "path";
 import {
   cancel as cancel4,
   intro as intro4,
   isCancel as isCancel3,
   note as note4,
   outro as outro4,
-  select as select3,
+  select as select2,
   spinner,
   text as text2
 } from "@clack/prompts";
 import pc6 from "picocolors";
 
 // src/lib/logger.ts
-import { log as log4 } from "@clack/prompts";
+import { log as log5 } from "@clack/prompts";
 import pc5 from "picocolors";
 var logger = {
   error(message) {
-    log4.error(message);
+    log5.error(message);
   },
   info(message) {
-    log4.info(message);
+    log5.info(message);
   },
   step(message) {
-    log4.step(pc5.dim(message));
+    log5.step(pc5.dim(message));
   },
   success(message) {
-    log4.success(message);
+    log5.success(message);
   },
   warn(message) {
-    log4.warn(message);
+    log5.warn(message);
   }
 };
 
@@ -5936,7 +6041,7 @@ function parseArgs4(argv) {
 }
 function run(command, args, cwd) {
   return new Promise((resolvePromise) => {
-    const child = spawn(command, args, {
+    const child = spawn2(command, args, {
       cwd,
       stdio: ["ignore", "pipe", "pipe"],
       shell: process.platform === "win32"
@@ -5971,7 +6076,10 @@ function runPnpmInstall(cwd) {
 async function initGitRepo(cwd) {
   const inside = await run("git", ["rev-parse", "--is-inside-work-tree"], cwd);
   if (inside.ok) {
-    return { created: false };
+    const ignored = await run("git", ["check-ignore", "--quiet", "."], cwd);
+    if (!ignored.ok) {
+      return { created: false };
+    }
   }
   const result = await run("git", ["init"], cwd);
   if (!result.ok) {
@@ -5992,7 +6100,7 @@ function bySkillOrder(a, b) {
 }
 async function linkAgentSkills(target) {
   const result = { linked: [], conflicts: [], failures: [] };
-  const skillsDir = join14(target, ".agents", "skills");
+  const skillsDir = join15(target, ".agents", "skills");
   let names;
   try {
     names = await readDirNames(skillsDir);
@@ -6001,8 +6109,8 @@ async function linkAgentSkills(target) {
     return result;
   }
   for (const name of names.toSorted(bySkillOrder)) {
-    const linkAbs = join14(target, ".claude", "skills", name);
-    const targetAbs = join14(skillsDir, name);
+    const linkAbs = join15(target, ".claude", "skills", name);
+    const targetAbs = join15(skillsDir, name);
     let state;
     try {
       state = await classifyLink(linkAbs, targetAbs);
@@ -6160,7 +6268,7 @@ ${pc6.dim("Symlinked for Claude Code \u2014 the skill files live in `.agents/ski
     );
   }
   let installed = false;
-  const wantsInstall = noInstall ? false : await select3({
+  const wantsInstall = noInstall ? false : await select2({
     message: "Install dependencies now?",
     options: [
       { value: true, label: `Yes, run ${pc6.cyan("pnpm install")}` },
@@ -6195,7 +6303,7 @@ ${pc6.dim("Symlinked for Claude Code \u2014 the skill files live in `.agents/ski
     // owner who never opens AGENTS.md would otherwise not know they exist.
     // Pad to the same column the commands above comment at (`pnpm dev` + 21 spaces).
     ...skills.linked.map(
-      (name) => `${`/${name}`.padEnd(29)}${pc6.dim("# in Claude Code")}`
+      (name) => `${`/${name}`.padEnd(29)}${pc6.dim("# in your AI coding tool")}`
     )
   ].filter((line) => line !== null).map((line) => pc6.cyan(line)).join("\n");
   note4(steps, "Next steps");
@@ -6205,7 +6313,7 @@ ${pc6.dim("Symlinked for Claude Code \u2014 the skill files live in `.agents/ski
 
 // src/commands/list.ts
 import { cancel as cancel5, intro as intro5, note as note5, outro as outro5 } from "@clack/prompts";
-import { join as join15 } from "path";
+import { join as join16 } from "path";
 import pc7 from "picocolors";
 var KNOWN_FLAGS5 = /* @__PURE__ */ new Set(["--installed", "--available", "--help", "-h"]);
 var USAGE5 = "saasaloy list [<owner/repo[@ref]>] [--installed] [--available]";
@@ -6238,7 +6346,7 @@ function parseArgs5(argv) {
 }
 async function localProject() {
   const root = await findProjectRoot();
-  if (!await pathExists(join15(root, CONFIG_FILE))) {
+  if (!await pathExists(join16(root, CONFIG_FILE))) {
     return { installed: /* @__PURE__ */ new Set() };
   }
   const config = await loadConfig(root);
@@ -6338,21 +6446,21 @@ async function runList(argv) {
 }
 
 // src/commands/new.ts
-import { join as join17, relative as relative4, resolve as resolve7 } from "path";
+import { join as join18, relative as relative4, resolve as resolve7 } from "path";
 import {
   cancel as cancel6,
   intro as intro6,
   isCancel as isCancel4,
   note as note6,
   outro as outro6,
-  select as select4,
+  select as select3,
   text as text3
 } from "@clack/prompts";
 import pc8 from "picocolors";
 
 // src/lib/new-module.ts
 import { mkdir as mkdir7, writeFile as writeFile9 } from "fs/promises";
-import { dirname as dirname9, join as join16 } from "path";
+import { dirname as dirname9, join as join17 } from "path";
 var MODULE_TYPES = [
   "saasaloy:capability",
   "saasaloy:feature"
@@ -6456,7 +6564,7 @@ function moduleFiles(spec) {
 async function writeModule(dir, spec) {
   const files = moduleFiles(spec);
   for (const file of files) {
-    const abs = join16(dir, ...file.path.split("/"));
+    const abs = join17(dir, ...file.path.split("/"));
     await mkdir7(dirname9(abs), { recursive: true });
     await writeFile9(abs, file.content, "utf-8");
   }
@@ -6544,7 +6652,7 @@ async function runNew(argv) {
   }
   try {
     const projectRoot = await findProjectRoot();
-    if (await pathExists(join17(projectRoot, CONFIG_FILE))) {
+    if (await pathExists(join18(projectRoot, CONFIG_FILE))) {
       cancel6(
         `${CONFIG_FILE} is present at ${pc8.cyan(projectRoot)} \u2014 this is a generated project, and \`new module\` authors a module for a registry. Run it in the registry repo instead. Nothing was written.`
       );
@@ -6572,7 +6680,7 @@ async function runNew(argv) {
       return EXIT_REFUSED;
     }
     const registryDir = resolve7(process.cwd(), REGISTRY_DIR);
-    const dir = join17(registryDir, name);
+    const dir = join18(registryDir, name);
     if (await pathExists(dir)) {
       cancel6(
         `${pc8.cyan(`${REGISTRY_DIR}/${name}`)} already exists \u2014 pick another name, or edit it by hand. Nothing was written.`
@@ -6589,7 +6697,7 @@ async function runNew(argv) {
       }
       type = opts.type;
     } else if (isInteractive()) {
-      const picked = await select4({
+      const picked = await select3({
         message: "Which tier is this?",
         options: MODULE_TYPES.map((value) => ({
           hint: TYPE_HINTS[value],
@@ -6662,16 +6770,16 @@ async function runNew(argv) {
 }
 
 // src/commands/outdated.ts
-import { cancel as cancel7, intro as intro7, log as log5, note as note7, outro as outro7 } from "@clack/prompts";
+import { cancel as cancel7, intro as intro7, log as log6, note as note7, outro as outro7 } from "@clack/prompts";
 import pc9 from "picocolors";
 
 // src/lib/updater.ts
 import { mkdir as mkdir8, readFile as readFile18, rm as rmPath2, writeFile as writeFile11 } from "fs/promises";
-import { dirname as dirname11, posix as posix9 } from "path";
+import { dirname as dirname11, posix as posix7 } from "path";
 
 // src/lib/remover.ts
 import { readdir as readdir5, readFile as readFile17, rm as rmPath, writeFile as writeFile10 } from "fs/promises";
-import { dirname as dirname10, join as join18, relative as relative5, sep as sep3 } from "path";
+import { dirname as dirname10, join as join19, relative as relative5, sep as sep3 } from "path";
 function classifyTrackedFile(content, manifestHash) {
   if (content === void 0) {
     return "missing";
@@ -6815,7 +6923,7 @@ async function pruneEmptyDirs(root, deletedAbsPaths) {
 async function dropDanglingAliases(root, config) {
   const dropped = [];
   for (const [alias, prefix] of Object.entries(config.aliases)) {
-    const prefixAbs = join18(root, ...prefix.split("/"));
+    const prefixAbs = join19(root, ...prefix.split("/"));
     if (!await pathExists(prefixAbs)) {
       delete config.aliases[alias];
       dropped.push(alias);
@@ -7352,9 +7460,9 @@ function classifyUpdate(base, theirs, mine, managedHash, adopted, projectOwned)
 async function planLinks(root, theirs) {
   const links = [];
   for (const skillRel of theirs.item.agent?.skills ?? []) {
-    const folderName = posix9.basename(skillRel);
-    const path = posix9.join(".claude/skills", folderName);
-    const target = posix9.join(".agents/skills", folderName);
+    const folderName = posix7.basename(skillRel);
+    const path = posix7.join(".claude/skills", folderName);
+    const target = posix7.join(".agents/skills", folderName);
     const pathAbs = resolveWithinRoot(root, path);
     const targetAbs = resolveWithinRoot(root, target);
     const state = await classifyLink(pathAbs, targetAbs);
@@ -7708,7 +7816,7 @@ async function runOutdated(argv) {
     const manifest = await loadManifest(root);
     const registryOverride = !!process.env[REGISTRY_ENV];
     if (registryOverride && config.installed.length > 0) {
-      log5.warn(
+      log6.warn(
         `${REGISTRY_ENV} is set, so every module reads as local \u2014 unset it to compare against the registry.`
       );
     }
@@ -7789,10 +7897,10 @@ import {
   confirm as confirm2,
   intro as intro8,
   isCancel as isCancel5,
-  log as log6,
+  log as log7,
   note as note8,
   outro as outro8,
-  select as select5
+  select as select4
 } from "@clack/prompts";
 import pc10 from "picocolors";
 var KNOWN_FLAGS8 = /* @__PURE__ */ new Set([
@@ -7891,12 +7999,12 @@ function summarizeRemovePlan(plan, name, yes) {
     note8(wrapForNote(linkLines.join("\n")), "Skill links");
   }
   if (plan.dependents.length > 0) {
-    log6.warn(
+    log7.warn(
       `${pc10.cyan(name)} is still depended on by ${plan.dependents.join(", ")} \u2014 proceeding anyway (--force).`
     );
   }
   for (const missingLock of plan.missingLockEntries) {
-    log6.warn(
+    log7.warn(
       `Installed module ${pc10.cyan(missingLock)} has no lock entry \u2014 dependent detection is incomplete for it.`
     );
   }
@@ -7912,7 +8020,7 @@ function summarizeRemovePlan(plan, name, yes) {
     if (p.action !== "drop") {
       continue;
     }
-    log6.warn(
+    log7.warn(
       `Config patch on ${pc10.cyan(p.entry.file)} ${pc10.dim(`(${p.entry.patch.kind})`)} is not reversed by \`remove\` \u2014 hand-revert it if needed.`
     );
   }
@@ -7953,7 +8061,7 @@ async function runRemove(argv) {
         );
         return EXIT_REFUSED;
       }
-      const picked = await select5({
+      const picked = await select4({
         message: "Pick a module to remove",
         options: config.installed.map((n) => ({ value: n, label: n }))
       });
@@ -7978,7 +8086,7 @@ async function runRemove(argv) {
     }
     summarizeRemovePlan(plan, name, opts.yes);
     for (const warning of plan.warnings) {
-      log6.warn(warning);
+      log7.warn(warning);
     }
     if (opts.diff) {
       for (const file of plan.files) {
@@ -8053,24 +8161,28 @@ async function runRemove(argv) {
       throw failedSave.error;
     }
     for (const file of result.deleted) {
-      log6.step(`${pc10.red("delete")}  ${file.target}`);
+      log7.step(`${pc10.red("delete")}  ${file.target}`);
     }
     for (const file of result.missingUntracked) {
-      log6.step(
+      log7.step(
         `${pc10.dim("untrack")}  ${file.target} ${pc10.dim("(already gone)")}`
       );
     }
     for (const link of result.linksRemoved) {
-      log6.step(`${pc10.red("unlink")}  ${link.path}`);
+      log7.step(`${pc10.red("unlink")}  ${link.path}`);
     }
     for (const link of result.linkConflicts) {
-      log6.warn(
+      log7.warn(
         `Skill link ${pc10.cyan(link.path)} left untouched \u2014 not ours to remove.`
       );
     }
     for (const p of result.patchesReversed) {
-      log6.step(`${pc10.red("revert")}  ${p.file} ${pc10.dim(`(${p.patch.kind})`)}`);
+      log7.step(`${pc10.red("revert")}  ${p.file} ${pc10.dim(`(${p.patch.kind})`)}`);
     }
+    await formatPatchedFiles(
+      root,
+      result.patchesReversed.map((p) => p.file)
+    );
     const refusals = new Map(
       result.patchRefusals.map((r) => [r.patch, r.reason])
     );
@@ -8079,15 +8191,15 @@ async function runRemove(argv) {
         continue;
       }
       const reason = refusals.get(p);
-      log6.warn(
+      log7.warn(
         reason === void 0 ? `Config patch on ${pc10.cyan(p.file)} ${pc10.dim(`(${p.patch.kind})`)} was already gone \u2014 nothing to revert.` : `Config patch on ${pc10.cyan(p.file)} ${pc10.dim(`(${p.patch.kind})`)} left untouched \u2014 ${reason}.`
       );
     }
     for (const dir of result.prunedDirs) {
-      log6.step(`${pc10.dim("prune")}  ${dir}`);
+      log7.step(`${pc10.dim("prune")}  ${dir}`);
     }
     for (const alias of result.droppedAliases) {
-      log6.warn(
+      log7.warn(
         `Alias ${pc10.cyan(alias)} dropped \u2014 its target directory is gone.`
       );
     }
@@ -8128,13 +8240,13 @@ ${pc10.dim("Hand-edited since \u2014 left on disk, now untracked.")}`
 
 // src/commands/update.ts
 import { mkdir as mkdir10, realpath, writeFile as writeFile13 } from "fs/promises";
-import { basename as basename4, dirname as dirname13, isAbsolute as isAbsolute4, join as join20, resolve as resolve8 } from "path";
+import { basename as basename4, dirname as dirname13, isAbsolute as isAbsolute4, join as join21, resolve as resolve8 } from "path";
 import {
   cancel as cancel9,
   confirm as confirm3,
   intro as intro9,
   isCancel as isCancel6,
-  log as log7,
+  log as log8,
   note as note9,
   outro as outro9
 } from "@clack/prompts";
@@ -8149,14 +8261,14 @@ import {
   rm as rmPath3,
   writeFile as writeFile12
 } from "fs/promises";
-import { dirname as dirname12, join as join19 } from "path";
-var BACKUP_DIR = join19(".saasaloy", "backups");
+import { dirname as dirname12, join as join20 } from "path";
+var BACKUP_DIR = join20(".saasaloy", "backups");
 var RECORD_FILE = "backup.json";
 var STATE_FILES = [
   "saasaloy.json",
   "saasaloy-lock.json",
   "package.json",
-  join19(".saasaloy", "manifest.json")
+  join20(".saasaloy", "manifest.json")
 ];
 function stampName(now) {
   return now.toISOString().replaceAll(/[:.]/g, "-");
@@ -8164,8 +8276,8 @@ function stampName(now) {
 async function writeBackup(args) {
   const { root, targets, cliVersion } = args;
   const createdAt = (args.now ?? /* @__PURE__ */ new Date()).toISOString();
-  const rel = join19(BACKUP_DIR, stampName(args.now ?? new Date(createdAt)));
-  const dir = join19(root, rel);
+  const rel = join20(BACKUP_DIR, stampName(args.now ?? new Date(createdAt)));
+  const dir = join20(root, rel);
   const files = [];
   const absent = [];
   for (const target of /* @__PURE__ */ new Set([...targets, ...STATE_FILES])) {
@@ -8174,7 +8286,7 @@ async function writeBackup(args) {
       absent.push(target);
       continue;
     }
-    const destination = join19(dir, target);
+    const destination = join20(dir, target);
     await mkdir9(dirname12(destination), { recursive: true });
     await copyFile(source, destination);
     files.push(target);
@@ -8187,7 +8299,7 @@ async function writeBackup(args) {
   };
   await mkdir9(dir, { recursive: true });
   await writeFile12(
-    join19(dir, RECORD_FILE),
+    join20(dir, RECORD_FILE),
     `${JSON.stringify(record, null, 2)}
 `,
     "utf-8"
@@ -8195,7 +8307,7 @@ async function writeBackup(args) {
   return rel;
 }
 async function listBackups(root) {
-  const dir = join19(root, BACKUP_DIR);
+  const dir = join20(root, BACKUP_DIR);
   if (!await pathExists(dir)) {
     return [];
   }
@@ -8210,25 +8322,25 @@ async function restoreLatestBackup(root) {
       `No backup to restore \u2014 nothing under ${BACKUP_DIR}. \`saasaloy update\` writes one before it applies a plan.`
     );
   }
-  const rel = join19(BACKUP_DIR, newest);
-  const dir = join19(root, rel);
-  const raw = await readIfPresent(join19(dir, RECORD_FILE));
+  const rel = join20(BACKUP_DIR, newest);
+  const dir = join20(root, rel);
+  const raw = await readIfPresent(join20(dir, RECORD_FILE));
   if (raw === void 0) {
     throw new RefusalError(
-      `${join19(rel, RECORD_FILE)} is missing \u2014 that backup can't be restored safely.`
+      `${join20(rel, RECORD_FILE)} is missing \u2014 that backup can't be restored safely.`
     );
   }
   let record;
   try {
     record = JSON.parse(raw);
   } catch (error) {
-    throw new RefusalError(`${join19(rel, RECORD_FILE)} is invalid.`, {
+    throw new RefusalError(`${join20(rel, RECORD_FILE)} is invalid.`, {
       cause: error
     });
   }
   const restored = [];
   for (const target of record.files) {
-    const source = join19(dir, target);
+    const source = join20(dir, target);
     const destination = resolveWithinRoot(root, target);
     if (!await pathExists(source)) {
       continue;
@@ -8670,18 +8782,18 @@ function summarizePlan2(plan) {
   lines.push(pc11.dim(`${writing} file(s) to apply, ${merging} needing merge`));
   note9(wrapForNote(lines.join("\n")), "Plan", TUI_ON_STDERR);
   for (const comparison of plan.skipped) {
-    log7.info(
+    log8.info(
       `${pc11.cyan(comparison.name)} ${pc11.dim(`\u2014 ${skipReason(comparison)}`)}`,
       TUI_ON_STDERR
     );
   }
   for (const mod of plan.modules) {
     for (const conflict of mod.depConflicts) {
-      log7.warn(`Dependency version conflict \u2014 ${conflict}.`, TUI_ON_STDERR);
+      log8.warn(`Dependency version conflict \u2014 ${conflict}.`, TUI_ON_STDERR);
     }
     for (const patch of mod.patches) {
       if (patch.action === "missing") {
-        log7.warn(
+        log8.warn(
           `Config patch target ${pc11.cyan(patch.file)} is missing \u2014 ${patch.patch.kind} not applied.`,
           TUI_ON_STDERR
         );
@@ -8753,7 +8865,7 @@ async function canonicalPath(path) {
     return await realpath(path);
   } catch {
     try {
-      return join20(await realpath(dirname13(path)), basename4(path));
+      return join21(await realpath(dirname13(path)), basename4(path));
     } catch {
       return path;
     }
@@ -8770,7 +8882,7 @@ async function emitMergePlan(document, out) {
   const target = resolvePlanOut(out);
   await mkdir10(dirname13(target), { recursive: true });
   await writeFile13(target, document, "utf-8");
-  log7.success(`Merge plan written to ${pc11.cyan(out)}`, TUI_ON_STDERR);
+  log8.success(`Merge plan written to ${pc11.cyan(out)}`, TUI_ON_STDERR);
 }
 function backupTargets(plan) {
   const targets = /* @__PURE__ */ new Set();
@@ -8827,10 +8939,10 @@ async function runUpdate(argv) {
     try {
       const restored = await restoreLatestBackup(root);
       for (const target of restored.restored) {
-        log7.step(`${pc11.green("restore")}  ${target}`, TUI_ON_STDERR);
+        log8.step(`${pc11.green("restore")}  ${target}`, TUI_ON_STDERR);
       }
       for (const target of restored.removed) {
-        log7.step(
+        log8.step(
           `${pc11.red("remove")}  ${target} ${pc11.dim("(the update created it)")}`,
           TUI_ON_STDERR
         );
@@ -8897,7 +9009,7 @@ async function runUpdate(argv) {
     if (wantsBase) {
       templateDir = await baseTemplateDir();
       if (project.source === "directory") {
-        log7.warn(
+        log8.warn(
           `No \`name\` in ${CONFIG_FILE} and no root package.json name \u2014 falling back to the directory name ${pc11.cyan(project.name)}. Set \`name\` in ${CONFIG_FILE} if that isn't this project's name.`,
           TUI_ON_STDERR
         );
@@ -8947,7 +9059,7 @@ async function runUpdate(argv) {
         return EXIT_REFUSED;
       }
       if (recorded !== cliVersion) {
-        log7.info(
+        log8.info(
           `Base recorded at CLI ${pc11.cyan(recorded)}; ${pc11.cyan(cliVersion)} is running.`,
           TUI_ON_STDERR
         );
@@ -8989,7 +9101,7 @@ async function runUpdate(argv) {
         return entry && entry.source !== "local";
       });
       if (fromRemote.length > 0) {
-        log7.warn(
+        log8.warn(
           `${REGISTRY_ENV} is set, so ${fromRemote.join(", ")} will be updated from that working copy rather than ${pc11.cyan(lock.modules[fromRemote[0]]?.source ?? "the registry")} \u2014 ${pc11.dim("there is no merge base for a working copy")}.`,
           TUI_ON_STDERR
         );
@@ -9014,7 +9126,7 @@ async function runUpdate(argv) {
         }
       }
       for (const comparison of skipped) {
-        log7.info(
+        log8.info(
           `${pc11.cyan(comparison.name)} ${pc11.dim(`\u2014 ${skipReason(comparison, preview)}`)}`,
           TUI_ON_STDERR
         );
@@ -9137,7 +9249,7 @@ async function runUpdate(argv) {
       }
     }
     if (missingLockEntries.size > 0) {
-      log7.warn(
+      log8.warn(
         `No lock entry for ${[...missingLockEntries].map((m) => pc11.cyan(m)).join(", ")} \u2014 any conflict they declare can't be checked ${pc11.dim("(re-add them to record it)")}.`,
         TUI_ON_STDERR
       );
@@ -9154,9 +9266,9 @@ async function runUpdate(argv) {
       for (const comparison of skipped) {
         const line = `${pc11.cyan(comparison.name)} ${pc11.dim(`\u2014 ${skipReason(comparison)}`)}`;
         if (comparison.status === "unresolvable") {
-          log7.warn(line, TUI_ON_STDERR);
+          log8.warn(line, TUI_ON_STDERR);
         } else {
-          log7.info(line, TUI_ON_STDERR);
+          log8.info(line, TUI_ON_STDERR);
         }
       }
       outro9(pc11.yellow("Nothing could be updated."), TUI_ON_STDERR);
@@ -9164,7 +9276,7 @@ async function runUpdate(argv) {
     }
     const pkg = await readRootPackageJson(root);
     if (!pkg) {
-      log7.warn(
+      log8.warn(
         "No package.json at the project root \u2014 dependency pins won't be updated.",
         TUI_ON_STDERR
       );
@@ -9224,7 +9336,7 @@ async function runUpdate(argv) {
       targets: backupTargets(plan),
       cliVersion
     });
-    log7.info(
+    log8.info(
       `Pre-update copies in ${pc11.cyan(backupDir)} ${pc11.dim("\u2014 `saasaloy update --abort` restores them")}`,
       TUI_ON_STDERR
     );
@@ -9248,6 +9360,11 @@ async function runUpdate(argv) {
     }
     const result = outcome.value;
     reportResult(result);
+    await formatPatchedFiles(
+      root,
+      result.patched.map((p) => p.file),
+      TUI_ON_STDERR
+    );
     const document = renderMergePlan(plan);
     if (document) {
       await emitMergePlan(document, opts.out);
@@ -9297,37 +9414,37 @@ function summarizeOutcome(plan, result) {
 }
 function reportResult(result) {
   for (const name of result.prereqsInstalled) {
-    log7.step(
+    log8.step(
       `${pc11.green("install")}  ${pc11.cyan(name)} ${pc11.dim("(new prerequisite)")}`,
       TUI_ON_STDERR
     );
   }
   for (const file of result.written) {
-    log7.step(`${ACTION_LABEL2[file.action]}  ${file.target}`, TUI_ON_STDERR);
+    log8.step(`${ACTION_LABEL2[file.action]}  ${file.target}`, TUI_ON_STDERR);
   }
   for (const file of result.deleted) {
-    log7.step(`${pc11.red("delete")}  ${file.target}`, TUI_ON_STDERR);
+    log8.step(`${pc11.red("delete")}  ${file.target}`, TUI_ON_STDERR);
   }
   for (const file of result.untracked) {
-    log7.step(
+    log8.step(
       `${pc11.dim("untrack")}  ${file.target} ${pc11.dim("(already gone)")}`,
       TUI_ON_STDERR
     );
   }
   for (const patch of result.patched) {
-    log7.step(
+    log8.step(
       `${pc11.green("patch")}  ${patch.file} ${pc11.dim(`\u2014 ${patch.patch.kind}`)}`,
       TUI_ON_STDERR
     );
   }
   for (const link of result.linkConflicts) {
-    log7.warn(
+    log8.warn(
       `Skill link ${pc11.cyan(link.path)} left untouched \u2014 not ours to replace.`,
       TUI_ON_STDERR
     );
   }
   for (const dep of result.depsWritten) {
-    log7.step(`${pc11.cyan("dep")}  ${dep.name}@${dep.version}`, TUI_ON_STDERR);
+    log8.step(`${pc11.cyan("dep")}  ${dep.name}@${dep.version}`, TUI_ON_STDERR);
   }
   if (result.lateDrift.length > 0) {
     const lines = result.lateDrift.map((f) => `  ${pc11.yellow("kept")}  ${f.target}`).join("\n");
@@ -9407,8 +9524,8 @@ ${pc12.dim("Set SAASALOY_DEBUG=1 to print the full cause chain behind a failure.
   );
 }
 async function pickCommand(deps) {
-  const { registry, select: select6, isCancel: isCancel7 } = deps;
-  const picked = await select6({
+  const { registry, select: select5, isCancel: isCancel7 } = deps;
+  const picked = await select5({
     message: "What would you like to do?",
     options: Object.entries(registry).map(([name, command2]) => ({
       value: name,
@@ -9429,7 +9546,7 @@ async function pickCommand(deps) {
 async function main(argv, deps = {}) {
   const {
     registry = COMMANDS,
-    select: select6 = clackSelect,
+    select: select5 = clackSelect,
     isCancel: isCancel7 = clackIsCancel
   } = deps;
   const [name, ...rest] = argv;
@@ -9446,7 +9563,7 @@ async function main(argv, deps = {}) {
       printHelp(registry);
       return EXIT_OK;
     }
-    return pickCommand({ registry, select: select6, isCancel: isCancel7 });
+    return pickCommand({ registry, select: select5, isCancel: isCancel7 });
   }
   const command = Object.hasOwn(registry, name) ? registry[name] : void 0;
   if (!command) {