@openplaybooks/converge 0.2.2 → 0.2.3

package/dist/examples-catalog.json

@@ -0,0 +1,55 @@
+{
+  "version": 1,
+  "examples": {
+    "acp-demo": {
+      "description": "ACP (Claude Agent SDK) provider demo — programmatic agent invocation",
+      "playbookName": "default",
+      "hasApiKeys": true
+    },
+    "data-pipeline": {
+      "description": "Sequential pipeline: fetch → transform → validate",
+      "playbookName": "default",
+      "hasApiKeys": false
+    },
+    "deep-research": {
+      "description": "Layered iterative-deepening research with quality-gated progression",
+      "playbookName": "deep-research",
+      "hasApiKeys": true
+    },
+    "evolutionary-optimization": {
+      "description": "Fitness-landscape search for prompt tuning and hyperparameter sweeps",
+      "playbookName": "default",
+      "hasApiKeys": false
+    },
+    "flutter-app": {
+      "description": "Autonomous Flutter mobile app generation — design system → screens → wiring",
+      "playbookName": "default",
+      "hasApiKeys": true
+    },
+    "frontier-research": {
+      "description": "Beam-search frontier research with parallel beams and convergence tracking",
+      "playbookName": "default",
+      "hasApiKeys": false
+    },
+    "fullstack-app": {
+      "description": "Seed-driven dynamic backend + frontend generation",
+      "playbookName": "default",
+      "hasApiKeys": false
+    },
+    "hello-world": {
+      "description": "Simplest possible playbook — one task, two checks",
+      "playbookName": "default",
+      "hasApiKeys": false
+    },
+    "scientific-research": {
+      "description": "Bayesian reasoning, GRADE evidence, meta-analysis — 8-phase epoch loop",
+      "playbookName": "default",
+      "hasApiKeys": false
+    },
+    "social-sim": {
+      "description": "Persona-driven OASIS-style social simulation with tick-based iteration",
+      "playbookName": "social-sim",
+      "hasApiKeys": true
+    }
+  }
+}

package/dist/index.js

@@ -13877,19 +13877,33 @@ function createStoragePaths(convergeDir = ".converge") {
     taskLog: (playbookId, taskId) => `${convergeDir}/playbooks/${playbookId}/tasks/${taskId}.log.md`
   };
 }
-function interpolateEnv(content, sourcePath) {
-  return content.replace(
-    /\$(\$)|\$\{([A-Z0-9_]+)(?::-([^}]*))?\}/g,
-    (_match, dollar, name, fallback) => {
-      if (dollar) return "$";
-      const value = process.env[name];
-      if (value !== void 0) return value;
-      if (fallback !== void 0) return fallback;
-      throw new Error(
-        `${sourcePath}: ${name} is not set. Add it to .env.local or export it before running the CLI.`
-      );
+function interpolateEnv(value, sourcePath, allowMissing) {
+  if (typeof value === "string") {
+    return value.replace(
+      /\$(\$)|\$\{([A-Z0-9_]+)(?::-([^}]*))?\}/g,
+      (_match, dollar, name, fallback) => {
+        if (dollar) return "$";
+        const envValue = process.env[name];
+        if (envValue !== void 0) return envValue;
+        if (fallback !== void 0) return fallback;
+        if (allowMissing) return "";
+        throw new Error(
+          `${sourcePath}: ${name} is not set. Add it to .env.local or export it before running the CLI.`
+        );
+      }
+    );
+  }
+  if (Array.isArray(value)) {
+    return value.map((v22) => interpolateEnv(v22, sourcePath, allowMissing));
+  }
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k102, v22] of Object.entries(value)) {
+      out[k102] = interpolateEnv(v22, sourcePath, allowMissing);
     }
-  );
+    return out;
+  }
+  return value;
 }
 function createFilesystemStorage(convergeDir = ".converge") {
   return new FilesystemStorage(convergeDir);
@@ -13914,7 +13928,7 @@ async function findConvergeConfig(startDir) {
     dir = parent;
   }
 }
-async function loadProjectMdConfig(configPath) {
+async function loadProjectMdConfig(configPath, opts = {}) {
   let raw;
   try {
     raw = await readFile(configPath, "utf-8");
@@ -13944,11 +13958,16 @@ See PROJECT.md format reference.`
 See PROJECT.md format reference.`
     );
   }
+  frontmatter = substituteEnvVarsInTree(
+    frontmatter,
+    configPath,
+    opts.allowMissingEnv ?? false
+  );
   const body = raw.slice(match2[0].length).trim();
   const projectDir = dirname(dirname(configPath));
   return buildConfigFromData(frontmatter, projectDir, body);
 }
-async function loadProjectYamlConfig(configPath) {
+async function loadProjectYamlConfig(configPath, opts = {}) {
   let raw;
   try {
     raw = await readFile(configPath, "utf-8");
@@ -13958,18 +13977,6 @@ async function loadProjectYamlConfig(configPath) {
   ${err.message}`
     );
   }
-  raw = raw.replace(
-    /\$(\$)|\$\{([A-Z0-9_]+)(?::-([^}]*))?\}/g,
-    (_m, dollar, name, fallback) => {
-      if (dollar) return "$";
-      const value = process.env[name];
-      if (value !== void 0) return value;
-      if (fallback !== void 0) return fallback;
-      throw new Error(
-        `${configPath}: ${name} is not set. Add it to .env.local or export it before running the CLI.`
-      );
-    }
-  );
   let data;
   try {
     data = parse(raw);
@@ -13983,9 +13990,44 @@ async function loadProjectYamlConfig(configPath) {
 See project.yaml format reference.`
     );
   }
+  data = substituteEnvVarsInTree(
+    data,
+    configPath,
+    opts.allowMissingEnv ?? false
+  );
   const projectDir = dirname(dirname(configPath));
   return buildConfigFromData(data, projectDir);
 }
+function substituteEnvVarsInTree(value, configPath, allowMissingEnv) {
+  if (typeof value === "string") {
+    return value.replace(
+      /\$(\$)|\$\{([A-Z0-9_]+)(?::-([^}]*))?\}/g,
+      (_m, dollar, name, fallback) => {
+        if (dollar) return "$";
+        const envValue = process.env[name];
+        if (envValue !== void 0) return envValue;
+        if (fallback !== void 0) return fallback;
+        if (allowMissingEnv) return "";
+        throw new Error(
+          `${configPath}: ${name} is not set. Add it to .env.local or export it before running the CLI.`
+        );
+      }
+    );
+  }
+  if (Array.isArray(value)) {
+    return value.map(
+      (v22) => substituteEnvVarsInTree(v22, configPath, allowMissingEnv)
+    );
+  }
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k102, v22] of Object.entries(value)) {
+      out[k102] = substituteEnvVarsInTree(v22, configPath, allowMissingEnv);
+    }
+    return out;
+  }
+  return value;
+}
 function buildConfigFromData(data, projectDir, body) {
   const config = {
     name: data.name,
@@ -14012,12 +14054,12 @@ function buildConfigFromData(data, projectDir, body) {
   }
   return config;
 }
-async function loadConvergeConfig(configPath, type2) {
+async function loadConvergeConfig(configPath, type2, opts = {}) {
   const configType = type2 || (configPath.endsWith("project.yaml") || configPath.endsWith("project.yml") ? "project.yaml" : "PROJECT.md");
   if (configType === "project.yaml") {
-    return loadProjectYamlConfig(configPath);
+    return loadProjectYamlConfig(configPath, opts);
   } else {
-    return loadProjectMdConfig(configPath);
+    return loadProjectMdConfig(configPath, opts);
   }
 }
 function convertScriptHooks(hooks, projectDir) {
@@ -14074,10 +14116,13 @@ function buildSafePayload(event, payload) {
   }
   return safe;
 }
-async function resolveConvergeConfig(startDir) {
+async function resolveConvergeConfig(startDir, opts = {}) {
   const result = await findConvergeConfig(startDir);
   if (!result) return null;
-  const config = await loadConvergeConfig(result.path, result.type);
+  const effective = {
+    allowMissingEnv: opts.allowMissingEnv ?? process.env.CONVERGE_ALLOW_MISSING_ENV === "1"
+  };
+  const config = await loadConvergeConfig(result.path, result.type, effective);
   return { config, configPath: result.path, type: result.type };
 }
 function readEnvValue(varName) {
@@ -44069,13 +44114,22 @@ checkpoints/*.yaml
           /*  Project Configuration                                         */
           /* ────────────────────────────────────────────────────────────── */
           /**
-           * Read project configuration
+           * Read project configuration.
+           *
+           * `allowMissingEnv` skips throwing on unset ${VAR} placeholders — used by
+           * `--dry` and `converge doctor`, which validate config shape without
+           * requiring credentials.
            */
-          readProject() {
+          readProject(opts = {}) {
             const content = readFileSync(this.paths.project, "utf8");
-            const interpolated = interpolateEnv(content, this.paths.project);
-            const data = parse(interpolated);
-            return ProjectConfigSchema.parse(data);
+            const parsed = parse(content);
+            const allowMissing = opts.allowMissingEnv ?? process.env.CONVERGE_ALLOW_MISSING_ENV === "1";
+            const interpolated = interpolateEnv(
+              parsed,
+              this.paths.project,
+              allowMissing
+            );
+            return ProjectConfigSchema.parse(interpolated);
           }
           /**
            * Write project configuration
@@ -73936,19 +73990,33 @@ function createStoragePaths2(convergeDir = ".converge") {
     taskLog: (playbookId, taskId) => `${convergeDir}/playbooks/${playbookId}/tasks/${taskId}.log.md`
   };
 }
-function interpolateEnv2(content, sourcePath) {
-  return content.replace(
-    /\$(\$)|\$\{([A-Z0-9_]+)(?::-([^}]*))?\}/g,
-    (_match, dollar, name, fallback) => {
-      if (dollar) return "$";
-      const value = process.env[name];
-      if (value !== void 0) return value;
-      if (fallback !== void 0) return fallback;
-      throw new Error(
-        `${sourcePath}: ${name} is not set. Add it to .env.local or export it before running the CLI.`
-      );
+function interpolateEnv2(value, sourcePath, allowMissing) {
+  if (typeof value === "string") {
+    return value.replace(
+      /\$(\$)|\$\{([A-Z0-9_]+)(?::-([^}]*))?\}/g,
+      (_match, dollar, name, fallback) => {
+        if (dollar) return "$";
+        const envValue = process.env[name];
+        if (envValue !== void 0) return envValue;
+        if (fallback !== void 0) return fallback;
+        if (allowMissing) return "";
+        throw new Error(
+          `${sourcePath}: ${name} is not set. Add it to .env.local or export it before running the CLI.`
+        );
+      }
+    );
+  }
+  if (Array.isArray(value)) {
+    return value.map((v18) => interpolateEnv2(v18, sourcePath, allowMissing));
+  }
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k19, v18] of Object.entries(value)) {
+      out[k19] = interpolateEnv2(v18, sourcePath, allowMissing);
     }
-  );
+    return out;
+  }
+  return value;
 }
 var dynamicImport2 = new Function(
   "p",
@@ -74005,13 +74073,22 @@ checkpoints/*.yaml
   /*  Project Configuration                                         */
   /* ────────────────────────────────────────────────────────────── */
   /**
-   * Read project configuration
+   * Read project configuration.
+   *
+   * `allowMissingEnv` skips throwing on unset ${VAR} placeholders — used by
+   * `--dry` and `converge doctor`, which validate config shape without
+   * requiring credentials.
    */
-  readProject() {
+  readProject(opts = {}) {
     const content = readFileSync(this.paths.project, "utf8");
-    const interpolated = interpolateEnv2(content, this.paths.project);
-    const data = parse(interpolated);
-    return ProjectConfigSchema2.parse(data);
+    const parsed = parse(content);
+    const allowMissing = opts.allowMissingEnv ?? process.env.CONVERGE_ALLOW_MISSING_ENV === "1";
+    const interpolated = interpolateEnv2(
+      parsed,
+      this.paths.project,
+      allowMissing
+    );
+    return ProjectConfigSchema2.parse(interpolated);
   }
   /**
    * Write project configuration
@@ -98108,19 +98185,33 @@ var init_types23 = __esm3({
     });
   }
 });
-function interpolateEnv3(content, sourcePath) {
-  return content.replace(
-    /\$(\$)|\$\{([A-Z0-9_]+)(?::-([^}]*))?\}/g,
-    (_match, dollar, name, fallback) => {
-      if (dollar) return "$";
-      const value = process.env[name];
-      if (value !== void 0) return value;
-      if (fallback !== void 0) return fallback;
-      throw new Error(
-        `${sourcePath}: ${name} is not set. Add it to .env.local or export it before running the CLI.`
-      );
+function interpolateEnv3(value, sourcePath, allowMissing) {
+  if (typeof value === "string") {
+    return value.replace(
+      /\$(\$)|\$\{([A-Z0-9_]+)(?::-([^}]*))?\}/g,
+      (_match, dollar, name, fallback) => {
+        if (dollar) return "$";
+        const envValue = process.env[name];
+        if (envValue !== void 0) return envValue;
+        if (fallback !== void 0) return fallback;
+        if (allowMissing) return "";
+        throw new Error(
+          `${sourcePath}: ${name} is not set. Add it to .env.local or export it before running the CLI.`
+        );
+      }
+    );
+  }
+  if (Array.isArray(value)) {
+    return value.map((v22) => interpolateEnv3(v22, sourcePath, allowMissing));
+  }
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k102, v22] of Object.entries(value)) {
+      out[k102] = interpolateEnv3(v22, sourcePath, allowMissing);
     }
-  );
+    return out;
+  }
+  return value;
 }
 var dynamicImport3;
 var FilesystemStorage3;
@@ -98183,13 +98274,22 @@ checkpoints/*.yaml
       /*  Project Configuration                                         */
       /* ────────────────────────────────────────────────────────────── */
       /**
-       * Read project configuration
+       * Read project configuration.
+       *
+       * `allowMissingEnv` skips throwing on unset ${VAR} placeholders — used by
+       * `--dry` and `converge doctor`, which validate config shape without
+       * requiring credentials.
        */
-      readProject() {
+      readProject(opts = {}) {
         const content = readFileSync(this.paths.project, "utf8");
-        const interpolated = interpolateEnv3(content, this.paths.project);
-        const data = parse(interpolated);
-        return ProjectConfigSchema3.parse(data);
+        const parsed = parse(content);
+        const allowMissing = opts.allowMissingEnv ?? process.env.CONVERGE_ALLOW_MISSING_ENV === "1";
+        const interpolated = interpolateEnv3(
+          parsed,
+          this.paths.project,
+          allowMissing
+        );
+        return ProjectConfigSchema3.parse(interpolated);
       }
       /**
        * Write project configuration
@@ -98505,7 +98605,7 @@ ${message}
     };
   }
 });
-async function loadProjectMdConfig2(configPath) {
+async function loadProjectMdConfig2(configPath, opts = {}) {
   let raw;
   try {
     raw = await readFile(configPath, "utf-8");
@@ -98535,11 +98635,16 @@ See PROJECT.md format reference.`
 See PROJECT.md format reference.`
     );
   }
+  frontmatter = substituteEnvVarsInTree2(
+    frontmatter,
+    configPath,
+    opts.allowMissingEnv ?? false
+  );
   const body = raw.slice(match2[0].length).trim();
   const projectDir = dirname(dirname(configPath));
   return buildConfigFromData2(frontmatter, projectDir, body);
 }
-async function loadProjectYamlConfig2(configPath) {
+async function loadProjectYamlConfig2(configPath, opts = {}) {
   let raw;
   try {
     raw = await readFile(configPath, "utf-8");
@@ -98549,18 +98654,6 @@ async function loadProjectYamlConfig2(configPath) {
   ${err.message}`
     );
   }
-  raw = raw.replace(
-    /\$(\$)|\$\{([A-Z0-9_]+)(?::-([^}]*))?\}/g,
-    (_m, dollar, name, fallback) => {
-      if (dollar) return "$";
-      const value = process.env[name];
-      if (value !== void 0) return value;
-      if (fallback !== void 0) return fallback;
-      throw new Error(
-        `${configPath}: ${name} is not set. Add it to .env.local or export it before running the CLI.`
-      );
-    }
-  );
   let data;
   try {
     data = parse(raw);
@@ -98574,9 +98667,44 @@ async function loadProjectYamlConfig2(configPath) {
 See project.yaml format reference.`
     );
   }
+  data = substituteEnvVarsInTree2(
+    data,
+    configPath,
+    opts.allowMissingEnv ?? false
+  );
   const projectDir = dirname(dirname(configPath));
   return buildConfigFromData2(data, projectDir);
 }
+function substituteEnvVarsInTree2(value, configPath, allowMissingEnv) {
+  if (typeof value === "string") {
+    return value.replace(
+      /\$(\$)|\$\{([A-Z0-9_]+)(?::-([^}]*))?\}/g,
+      (_m, dollar, name, fallback) => {
+        if (dollar) return "$";
+        const envValue = process.env[name];
+        if (envValue !== void 0) return envValue;
+        if (fallback !== void 0) return fallback;
+        if (allowMissingEnv) return "";
+        throw new Error(
+          `${configPath}: ${name} is not set. Add it to .env.local or export it before running the CLI.`
+        );
+      }
+    );
+  }
+  if (Array.isArray(value)) {
+    return value.map(
+      (v22) => substituteEnvVarsInTree2(v22, configPath, allowMissingEnv)
+    );
+  }
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k102, v22] of Object.entries(value)) {
+      out[k102] = substituteEnvVarsInTree2(v22, configPath, allowMissingEnv);
+    }
+    return out;
+  }
+  return value;
+}
 function buildConfigFromData2(data, projectDir, body) {
   const config = {
     name: data.name,
@@ -98603,12 +98731,12 @@ function buildConfigFromData2(data, projectDir, body) {
   }
   return config;
 }
-async function loadConvergeConfig2(configPath, type2) {
+async function loadConvergeConfig2(configPath, type2, opts = {}) {
   const configType = configPath.endsWith("project.yaml") || configPath.endsWith("project.yml") ? "project.yaml" : "PROJECT.md";
   if (configType === "project.yaml") {
-    return loadProjectYamlConfig2(configPath);
+    return loadProjectYamlConfig2(configPath, opts);
   } else {
-    return loadProjectMdConfig2(configPath);
+    return loadProjectMdConfig2(configPath, opts);
   }
 }
 function convertScriptHooks2(hooks, projectDir) {
@@ -139658,19 +139786,33 @@ var init_types24 = __esm4({
     });
   }
 });
-function interpolateEnv4(content, sourcePath) {
-  return content.replace(
-    /\$(\$)|\$\{([A-Z0-9_]+)(?::-([^}]*))?\}/g,
-    (_match, dollar, name, fallback) => {
-      if (dollar) return "$";
-      const value = process.env[name];
-      if (value !== void 0) return value;
-      if (fallback !== void 0) return fallback;
-      throw new Error(
-        `${sourcePath}: ${name} is not set. Add it to .env.local or export it before running the CLI.`
-      );
+function interpolateEnv4(value, sourcePath, allowMissing) {
+  if (typeof value === "string") {
+    return value.replace(
+      /\$(\$)|\$\{([A-Z0-9_]+)(?::-([^}]*))?\}/g,
+      (_match, dollar, name, fallback) => {
+        if (dollar) return "$";
+        const envValue = process.env[name];
+        if (envValue !== void 0) return envValue;
+        if (fallback !== void 0) return fallback;
+        if (allowMissing) return "";
+        throw new Error(
+          `${sourcePath}: ${name} is not set. Add it to .env.local or export it before running the CLI.`
+        );
+      }
+    );
+  }
+  if (Array.isArray(value)) {
+    return value.map((v22) => interpolateEnv4(v22, sourcePath, allowMissing));
+  }
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k102, v22] of Object.entries(value)) {
+      out[k102] = interpolateEnv4(v22, sourcePath, allowMissing);
     }
-  );
+    return out;
+  }
+  return value;
 }
 var dynamicImport4;
 var FilesystemStorage4;
@@ -139733,13 +139875,22 @@ checkpoints/*.yaml
       /*  Project Configuration                                         */
       /* ────────────────────────────────────────────────────────────── */
       /**
-       * Read project configuration
+       * Read project configuration.
+       *
+       * `allowMissingEnv` skips throwing on unset ${VAR} placeholders — used by
+       * `--dry` and `converge doctor`, which validate config shape without
+       * requiring credentials.
        */
-      readProject() {
+      readProject(opts = {}) {
         const content = readFileSync(this.paths.project, "utf8");
-        const interpolated = interpolateEnv4(content, this.paths.project);
-        const data = parse(interpolated);
-        return ProjectConfigSchema4.parse(data);
+        const parsed = parse(content);
+        const allowMissing = opts.allowMissingEnv ?? process.env.CONVERGE_ALLOW_MISSING_ENV === "1";
+        const interpolated = interpolateEnv4(
+          parsed,
+          this.paths.project,
+          allowMissing
+        );
+        return ProjectConfigSchema4.parse(interpolated);
       }
       /**
        * Write project configuration
@@ -140055,7 +140206,7 @@ ${message}
     };
   }
 });
-async function loadProjectMdConfig3(configPath) {
+async function loadProjectMdConfig3(configPath, opts = {}) {
   let raw;
   try {
     raw = await readFile(configPath, "utf-8");
@@ -140085,11 +140236,16 @@ See PROJECT.md format reference.`
 See PROJECT.md format reference.`
     );
   }
+  frontmatter = substituteEnvVarsInTree3(
+    frontmatter,
+    configPath,
+    opts.allowMissingEnv ?? false
+  );
   const body = raw.slice(match2[0].length).trim();
   const projectDir = dirname(dirname(configPath));
   return buildConfigFromData3(frontmatter, projectDir, body);
 }
-async function loadProjectYamlConfig3(configPath) {
+async function loadProjectYamlConfig3(configPath, opts = {}) {
   let raw;
   try {
     raw = await readFile(configPath, "utf-8");
@@ -140099,18 +140255,6 @@ async function loadProjectYamlConfig3(configPath) {
   ${err.message}`
     );
   }
-  raw = raw.replace(
-    /\$(\$)|\$\{([A-Z0-9_]+)(?::-([^}]*))?\}/g,
-    (_m, dollar, name, fallback) => {
-      if (dollar) return "$";
-      const value = process.env[name];
-      if (value !== void 0) return value;
-      if (fallback !== void 0) return fallback;
-      throw new Error(
-        `${configPath}: ${name} is not set. Add it to .env.local or export it before running the CLI.`
-      );
-    }
-  );
   let data;
   try {
     data = parse(raw);
@@ -140124,9 +140268,44 @@ async function loadProjectYamlConfig3(configPath) {
 See project.yaml format reference.`
     );
   }
+  data = substituteEnvVarsInTree3(
+    data,
+    configPath,
+    opts.allowMissingEnv ?? false
+  );
   const projectDir = dirname(dirname(configPath));
   return buildConfigFromData3(data, projectDir);
 }
+function substituteEnvVarsInTree3(value, configPath, allowMissingEnv) {
+  if (typeof value === "string") {
+    return value.replace(
+      /\$(\$)|\$\{([A-Z0-9_]+)(?::-([^}]*))?\}/g,
+      (_m, dollar, name, fallback) => {
+        if (dollar) return "$";
+        const envValue = process.env[name];
+        if (envValue !== void 0) return envValue;
+        if (fallback !== void 0) return fallback;
+        if (allowMissingEnv) return "";
+        throw new Error(
+          `${configPath}: ${name} is not set. Add it to .env.local or export it before running the CLI.`
+        );
+      }
+    );
+  }
+  if (Array.isArray(value)) {
+    return value.map(
+      (v22) => substituteEnvVarsInTree3(v22, configPath, allowMissingEnv)
+    );
+  }
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k102, v22] of Object.entries(value)) {
+      out[k102] = substituteEnvVarsInTree3(v22, configPath, allowMissingEnv);
+    }
+    return out;
+  }
+  return value;
+}
 function buildConfigFromData3(data, projectDir, body) {
   const config = {
     name: data.name,
@@ -140153,12 +140332,12 @@ function buildConfigFromData3(data, projectDir, body) {
   }
   return config;
 }
-async function loadConvergeConfig3(configPath, type2) {
+async function loadConvergeConfig3(configPath, type2, opts = {}) {
   const configType = configPath.endsWith("project.yaml") || configPath.endsWith("project.yml") ? "project.yaml" : "PROJECT.md";
   if (configType === "project.yaml") {
-    return loadProjectYamlConfig3(configPath);
+    return loadProjectYamlConfig3(configPath, opts);
   } else {
-    return loadProjectMdConfig3(configPath);
+    return loadProjectMdConfig3(configPath, opts);
   }
 }
 function convertScriptHooks3(hooks, projectDir) {
@@ -158632,7 +158811,7 @@ async function findConvergeConfig2(startDir) {
   }
 }
 var FRONTMATTER_RE4 = /^---\r?\n([\s\S]*?)\r?\n---/;
-async function loadProjectMdConfig4(configPath) {
+async function loadProjectMdConfig4(configPath, opts = {}) {
   let raw;
   try {
     raw = await readFile(configPath, "utf-8");
@@ -158662,11 +158841,16 @@ See PROJECT.md format reference.`
 See PROJECT.md format reference.`
     );
   }
+  frontmatter = substituteEnvVarsInTree4(
+    frontmatter,
+    configPath,
+    opts.allowMissingEnv ?? false
+  );
   const body = raw.slice(match2[0].length).trim();
   const projectDir = dirname(dirname(configPath));
   return buildConfigFromData4(frontmatter, projectDir, body);
 }
-async function loadProjectYamlConfig4(configPath) {
+async function loadProjectYamlConfig4(configPath, opts = {}) {
   let raw;
   try {
     raw = await readFile(configPath, "utf-8");
@@ -158676,18 +158860,6 @@ async function loadProjectYamlConfig4(configPath) {
   ${err.message}`
     );
   }
-  raw = raw.replace(
-    /\$(\$)|\$\{([A-Z0-9_]+)(?::-([^}]*))?\}/g,
-    (_m, dollar, name, fallback) => {
-      if (dollar) return "$";
-      const value = process.env[name];
-      if (value !== void 0) return value;
-      if (fallback !== void 0) return fallback;
-      throw new Error(
-        `${configPath}: ${name} is not set. Add it to .env.local or export it before running the CLI.`
-      );
-    }
-  );
   let data;
   try {
     data = parse(raw);
@@ -158701,9 +158873,44 @@ async function loadProjectYamlConfig4(configPath) {
 See project.yaml format reference.`
     );
   }
+  data = substituteEnvVarsInTree4(
+    data,
+    configPath,
+    opts.allowMissingEnv ?? false
+  );
   const projectDir = dirname(dirname(configPath));
   return buildConfigFromData4(data, projectDir);
 }
+function substituteEnvVarsInTree4(value, configPath, allowMissingEnv) {
+  if (typeof value === "string") {
+    return value.replace(
+      /\$(\$)|\$\{([A-Z0-9_]+)(?::-([^}]*))?\}/g,
+      (_m, dollar, name, fallback) => {
+        if (dollar) return "$";
+        const envValue = process.env[name];
+        if (envValue !== void 0) return envValue;
+        if (fallback !== void 0) return fallback;
+        if (allowMissingEnv) return "";
+        throw new Error(
+          `${configPath}: ${name} is not set. Add it to .env.local or export it before running the CLI.`
+        );
+      }
+    );
+  }
+  if (Array.isArray(value)) {
+    return value.map(
+      (v22) => substituteEnvVarsInTree4(v22, configPath, allowMissingEnv)
+    );
+  }
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k102, v22] of Object.entries(value)) {
+      out[k102] = substituteEnvVarsInTree4(v22, configPath, allowMissingEnv);
+    }
+    return out;
+  }
+  return value;
+}
 function buildConfigFromData4(data, projectDir, body) {
   const config = {
     name: data.name,
@@ -158730,12 +158937,12 @@ function buildConfigFromData4(data, projectDir, body) {
   }
   return config;
 }
-async function loadConvergeConfig4(configPath, type2) {
+async function loadConvergeConfig4(configPath, type2, opts = {}) {
   const configType = type2 || (configPath.endsWith("project.yaml") || configPath.endsWith("project.yml") ? "project.yaml" : "PROJECT.md");
   if (configType === "project.yaml") {
-    return loadProjectYamlConfig4(configPath);
+    return loadProjectYamlConfig4(configPath, opts);
   } else {
-    return loadProjectMdConfig4(configPath);
+    return loadProjectMdConfig4(configPath, opts);
   }
 }
 var HOOK_TIMEOUT_MS4 = 3e4;
@@ -158793,10 +159000,13 @@ function buildSafePayload4(event, payload) {
   }
   return safe;
 }
-async function resolveConvergeConfig2(startDir) {
+async function resolveConvergeConfig2(startDir, opts = {}) {
   const result = await findConvergeConfig2(startDir);
   if (!result) return null;
-  const config = await loadConvergeConfig4(result.path, result.type);
+  const effective = {
+    allowMissingEnv: opts.allowMissingEnv ?? process.env.CONVERGE_ALLOW_MISSING_ENV === "1"
+  };
+  const config = await loadConvergeConfig4(result.path, result.type, effective);
   return { config, configPath: result.path, type: result.type };
 }
 init_esm_shims5();
@@ -191722,8 +191932,26 @@ async function doctorCommand({
     contradictoryFindings: [],
     staleSentinels: [],
     trippedCircuits: [],
-    malformedSkills: []
+    malformedSkills: [],
+    configErrors: []
   };
+  try {
+    await resolveConvergeConfig2(workspace, { allowMissingEnv: true });
+  } catch (err) {
+    const msg = err?.message ?? String(err);
+    const idx = msg.indexOf(": ");
+    if (idx > 0 && msg.slice(0, idx).includes(".converge/project")) {
+      report.configErrors.push({
+        path: msg.slice(0, idx),
+        reason: msg.slice(idx + 2).trim()
+      });
+    } else {
+      report.configErrors.push({
+        path: join(workspace, ".converge", "project.yaml"),
+        reason: msg
+      });
+    }
+  }
   const defGaps = await findDefinitionGaps2(workspace, playbook);
   for (const d16 of defGaps) {
     report.definitionGaps.push({
@@ -191807,7 +192035,7 @@ async function doctorCommand({
       }
     }
   }
-  const totalFindings = report.definitionGaps.length + report.phantomWorkItems.length + report.contradictoryFindings.length + report.staleSentinels.length + report.trippedCircuits.length + report.malformedSkills.length;
+  const totalFindings = report.definitionGaps.length + report.phantomWorkItems.length + report.contradictoryFindings.length + report.staleSentinels.length + report.trippedCircuits.length + report.malformedSkills.length + report.configErrors.length;
   if (jsonOut) {
     console.log(
       JSON.stringify({ totalFindings, ...report, fixed: fix }, null, 2)
@@ -191878,6 +192106,17 @@ function printHumanReport(report, total, fixed) {
     if (fixed) console.log(`    (re-armed by --fix)`);
     console.log();
   }
+  if (report.configErrors.length > 0) {
+    console.log(
+      `\u25CF ${report.configErrors.length} project config error(s) \u2014 .converge/project.yaml will fail to load:`
+    );
+    for (const c of report.configErrors) {
+      console.log(`    ${c.path}`);
+      console.log(`      reason: ${c.reason.split("\n")[0].slice(0, 200)}`);
+    }
+    console.log(`    (--fix does NOT touch project.yaml \u2014 edit it yourself)`);
+    console.log();
+  }
   if (report.malformedSkills.length > 0) {
     console.log(
       `\u25CF ${report.malformedSkills.length} malformed SKILL.md file(s) \u2014 skill directories silently skipped by the catalog loader:`
@@ -209958,7 +210197,7 @@ function renderProjectYaml(args) {
   if (args.description) lines.push(`description: ${yamlEscape(args.description)}`);
   lines.push("");
   lines.push("# AI provider configuration \u2014 one default, multiple enabled.");
-  lines.push("# Replace ${ENV_VAR} placeholders with real keys or export them in your shell.");
+  lines.push("# Replace $VAR placeholders with real keys or export them in your shell.");
   lines.push("ai:");
   lines.push(`  default: ${args.defaultAgent}`);
   lines.push("  providers:");
@@ -211478,7 +211717,13 @@ async function main() {
         const localProjectYaml = join(localConvergeDir, "project.yaml");
         const localProjectMd = join(localConvergeDir, "PROJECT.md");
         const hasLocalProject = existsSync(localProjectYml) || existsSync(localProjectYaml) || existsSync(localProjectMd);
-        let resolved = await resolveConvergeConfig2(searchDir);
+        const isDryRunEarly = !!(options.dry || options.plan);
+        if (isDryRunEarly) {
+          process.env.CONVERGE_ALLOW_MISSING_ENV = "1";
+        }
+        let resolved = await resolveConvergeConfig2(searchDir, {
+          allowMissingEnv: isDryRunEarly
+        });
         if (resolved && !hasLocalProject) {
           const resolvedDir = dirname(resolved.configPath);
           const resolvedIsParent = resolvedDir !== searchDir;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openplaybooks/converge",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "private": false,
   "type": "module",
   "description": "CLI for Converge - A build system for AI agents",
@@ -33,12 +33,12 @@
     "@clack/prompts": "^0.9.1",
     "glob": "^13.0.0",
     "yaml": "^2.8.3",
+    "@openplaybooks/codexfn": "0.1.0",
+    "@openplaybooks/openfn": "^0.1.0",
+    "@openplaybooks/converge-core": "0.2.3",
     "@openplaybooks/agentfn": "0.2.1",
-    "@openplaybooks/converge-core": "0.2.2",
     "@openplaybooks/deepcodefn": "0.1.0",
-    "@openplaybooks/openfn": "^0.1.0",
-    "@openplaybooks/claudefn": "0.1.0",
-    "@openplaybooks/codexfn": "0.1.0"
+    "@openplaybooks/claudefn": "0.1.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",