@caoscompanybr/merlin 3.5.0

package/.merlin-core/tools/migrate-frontmatter-v3.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * Migrate SKILL.md frontmatter to Agent Skills Standard v3 format.
+ *
+ * Moves Merlin-specific attributes (auto_activate, tool_reminders, file_triggers,
+ * allowed-tools) from top-level into the metadata: block.
+ *
+ * Usage:
+ *   node migrate-frontmatter-v3.js [--dry-run]
+ *
+ * --dry-run: Show what would change without writing files.
+ *
+ * @since v3.0.0
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const DRY_RUN = process.argv.includes("--dry-run");
+const PROJECT_ROOT = path.resolve(__dirname, "..");
+const SKILL_DIRS = [
+  path.join(PROJECT_ROOT, "skills", "general"),
+  path.join(PROJECT_ROOT, "skills", "domain"),
+];
+
+// Fields to move from top-level into metadata:
+const FIELDS_TO_MOVE = [
+  "auto_activate",
+  "tool_reminders",
+  "file_triggers",
+  "allowed-tools",
+];
+
+function findSkillFiles() {
+  const files = [];
+  for (const dir of SKILL_DIRS) {
+    if (!fs.existsSync(dir)) continue;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const skillFile = path.join(dir, entry.name, "SKILL.md");
+      if (fs.existsSync(skillFile)) files.push(skillFile);
+    }
+  }
+  return files;
+}
+
+function migrateFile(filePath) {
+  const content = fs.readFileSync(filePath, "utf8");
+  const match = content.match(/^---\r?\n([\s\S]*?)(?:\r?\n)?---/);
+  if (!match) return { changed: false, reason: "no frontmatter" };
+
+  const raw = match[1];
+  const body = content.slice(match[0].length);
+  const lines = raw.split(/\r?\n/);
+
+  // Extract fields to move
+  const fieldsFound = {};
+  const linesToRemove = new Set();
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const field of FIELDS_TO_MOVE) {
+      if (line.trimStart().startsWith(`${field}:`)) {
+        // Check if it's a top-level field (no indentation)
+        if (line.match(/^\s+/)) continue; // Skip if indented (already in metadata)
+
+        const valueAfterColon = line.replace(`${field}:`, "").trim();
+
+        // Inline array: field: [a, b, c]
+        if (valueAfterColon.startsWith("[") && valueAfterColon.endsWith("]")) {
+          fieldsFound[field] = valueAfterColon;
+          linesToRemove.add(i);
+        }
+        // Inline scalar: field: value
+        else if (valueAfterColon && !valueAfterColon.startsWith("[")) {
+          fieldsFound[field] = valueAfterColon;
+          linesToRemove.add(i);
+        }
+        // Multi-line array or bracket: collect continuation lines
+        else {
+          linesToRemove.add(i);
+          const subLines = [];
+          for (let j = i + 1; j < lines.length; j++) {
+            if (lines[j].match(/^\s+/)) {
+              subLines.push(lines[j].trim());
+              linesToRemove.add(j);
+            } else {
+              break;
+            }
+          }
+          // Reconstruct as inline array
+          const joined = subLines.join(" ");
+          if (joined.startsWith("[")) {
+            // Multi-line bracket: [a,\n  b,\n]
+            fieldsFound[field] = joined.replace(/\s+/g, " ");
+          } else {
+            // Multi-line dash: - a\n- b
+            const items = subLines
+              .filter((l) => l.startsWith("- "))
+              .map((l) =>
+                l
+                  .substring(2)
+                  .trim()
+                  .replace(/^['"]|['"]$/g, ""),
+              );
+            fieldsFound[field] = `[${items.join(", ")}]`;
+          }
+        }
+      }
+    }
+  }
+
+  if (Object.keys(fieldsFound).length === 0) {
+    return { changed: false, reason: "no fields to move" };
+  }
+
+  // Rebuild frontmatter without moved fields
+  const remainingLines = lines.filter((_, i) => !linesToRemove.has(i));
+
+  // Find existing metadata block
+  const metaIdx = remainingLines.findIndex((l) =>
+    l.trim().startsWith("metadata:"),
+  );
+
+  if (metaIdx !== -1) {
+    // Insert new fields into existing metadata block
+    const insertLines = [];
+    for (const [field, value] of Object.entries(fieldsFound)) {
+      // Normalize allowed-tools to allowed_tools in metadata
+      const metaField = field.replace(/-/g, "_");
+      insertLines.push(`  ${metaField}: ${value}`);
+    }
+    // Find the end of the metadata block
+    let insertAt = metaIdx + 1;
+    for (let i = metaIdx + 1; i < remainingLines.length; i++) {
+      if (remainingLines[i].match(/^\s+/)) {
+        insertAt = i + 1;
+      } else {
+        break;
+      }
+    }
+    remainingLines.splice(insertAt, 0, ...insertLines);
+  } else {
+    // Create new metadata block
+    const insertLines = ["metadata:"];
+    for (const [field, value] of Object.entries(fieldsFound)) {
+      const metaField = field.replace(/-/g, "_");
+      insertLines.push(`  ${metaField}: ${value}`);
+    }
+    remainingLines.push(...insertLines);
+  }
+
+  const newRaw = remainingLines.join("\n");
+  const newContent = `---\n${newRaw}\n---${body}`;
+
+  if (!DRY_RUN) {
+    fs.writeFileSync(filePath, newContent, "utf8");
+  }
+
+  return {
+    changed: true,
+    fieldsMoved: Object.keys(fieldsFound),
+    reason: `moved ${Object.keys(fieldsFound).join(", ")} into metadata`,
+  };
+}
+
+// Main
+const files = findSkillFiles();
+let changed = 0;
+let unchanged = 0;
+
+console.log(
+  `${DRY_RUN ? "[DRY RUN] " : ""}Migrating ${files.length} SKILL.md files to v3 format...`,
+);
+
+for (const file of files) {
+  const rel = path.relative(PROJECT_ROOT, file);
+  const result = migrateFile(file);
+  if (result.changed) {
+    console.log(`  ✓ ${rel} — ${result.reason}`);
+    changed++;
+  } else {
+    unchanged++;
+  }
+}
+
+console.log(
+  `\nDone: ${changed} migrated, ${unchanged} unchanged (of ${files.length} total)`,
+);
+if (DRY_RUN) console.log("(dry run — no files written)");

package/.merlin-core/tools/modules-catalog.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * modules-catalog.mjs — the Merlin Modules registry (v3.5, net-new).
+ *
+ * Filesystem-as-registry: walks `.merlin-core/modules/<id>/module.json`, validates
+ * each manifest against `schemas/module.schema.json` (ajv), and returns the catalog.
+ * The mechanism lives in the framework (gestao-merlin); CAOS is the 1st consumer.
+ *
+ *   import { loadCatalog, validateManifest } from "./modules-catalog.mjs"
+ *   node .merlin-core/tools/modules-catalog.mjs            # list + validate (exit 1 if any invalid)
+ *
+ * See research/2026-06-14-merlin-modules-architecture.md §4 (registry + enablement).
+ */
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join, dirname, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import Ajv2020 from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MERLIN_CORE = join(__dirname, "..");
+const MODULES_DIR = join(MERLIN_CORE, "modules");
+const SCHEMA_PATH = join(MERLIN_CORE, "schemas", "module.schema.json");
+
+let _validator = null;
+function getValidator() {
+  if (_validator) return _validator;
+  const schema = JSON.parse(readFileSync(SCHEMA_PATH, "utf8"));
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  _validator = ajv.compile(schema);
+  return _validator;
+}
+
+/** Validate a parsed manifest object against module.schema.json. */
+export function validateManifest(manifest) {
+  const validate = getValidator();
+  const ok = validate(manifest);
+  return {
+    ok,
+    errors: ok
+      ? []
+      : (validate.errors || []).map(
+          (e) => `${e.instancePath || "/"} ${e.message}`,
+        ),
+  };
+}
+
+const withMd = (ref) => (ref.endsWith(".md") ? ref : `${ref}.md`);
+
+/**
+ * existsSync, but only for a path CONTAINED within `core`. A manifest ref like
+ * `../../etc/passwd` must never resolve outside the framework tree (manifests
+ * are first-party today, but the registry is meant to take third-party modules).
+ */
+function safeExists(core, ...segs) {
+  const target = resolve(join(core, ...segs));
+  if (target !== resolve(core) && !target.startsWith(resolve(core) + sep))
+    return false;
+  return existsSync(target);
+}
+
+/**
+ * Resolvers for each framework-face reference type → does the file exist on disk?
+ * Refs resolve by their FULL relative path (a nested ref like
+ * `marketing-ops/competitor-profiling` must resolve that exact skill dir, not its
+ * first segment — otherwise a non-existent nested skill falsely passes).
+ */
+const FRAMEWORK_REF_RESOLVERS = {
+  skills: (ref, core) =>
+    safeExists(core, "skills", "general", ref, "SKILL.md") ||
+    safeExists(core, "skills", "domain", ref, "SKILL.md"),
+  agents: (ref, core) => safeExists(core, "development", "agents", withMd(ref)),
+  commands: (ref, core) => safeExists(core, "commands", withMd(ref)),
+  checklists: (ref, core) =>
+    safeExists(core, "development", "checklists", withMd(ref)),
+};
+
+/**
+ * Check that every framework-face reference (skills/agents/commands/checklists)
+ * resolves to a real file. A manifest can be schema-valid yet point at a command
+ * that does not exist — this catches that integration gap.
+ * Returns an array of "<type>:<ref>" strings for refs that do not resolve.
+ */
+export function checkFrameworkRefs(
+  manifest,
+  { merlinCore = MERLIN_CORE } = {},
+) {
+  const fw = manifest.framework;
+  if (!fw) return [];
+  const missing = [];
+  for (const [type, resolver] of Object.entries(FRAMEWORK_REF_RESOLVERS)) {
+    for (const ref of fw[type] || []) {
+      if (!resolver(ref, merlinCore)) missing.push(`${type}:${ref}`);
+    }
+  }
+  return missing;
+}
+
+/**
+ * Walk the modules dir, parse + validate every module.json.
+ * Returns { modules: [valid manifests, id-sorted], invalid: [{dir, path, errors}],
+ * integrity: [{id, missing}] } — `integrity` lists schema-valid modules whose
+ * framework refs point at files that do not exist.
+ */
+export function loadCatalog({
+  modulesDir = MODULES_DIR,
+  merlinCore = MERLIN_CORE,
+} = {}) {
+  const catalog = { modules: [], invalid: [], integrity: [] };
+  if (!existsSync(modulesDir)) return catalog;
+  for (const entry of readdirSync(modulesDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const path = join(modulesDir, entry.name, "module.json");
+    if (!existsSync(path)) continue;
+    let manifest;
+    try {
+      manifest = JSON.parse(readFileSync(path, "utf8"));
+    } catch (e) {
+      catalog.invalid.push({
+        dir: entry.name,
+        path,
+        errors: [`JSON parse error: ${e.message}`],
+      });
+      continue;
+    }
+    const { ok, errors } = validateManifest(manifest);
+    if (!ok) {
+      catalog.invalid.push({ dir: entry.name, path, errors });
+      continue;
+    }
+    if (manifest.id !== entry.name) {
+      catalog.invalid.push({
+        dir: entry.name,
+        path,
+        errors: [
+          `id "${manifest.id}" must equal the directory name "${entry.name}"`,
+        ],
+      });
+      continue;
+    }
+    catalog.modules.push(manifest);
+    const missing = checkFrameworkRefs(manifest, { merlinCore });
+    if (missing.length) catalog.integrity.push({ id: manifest.id, missing });
+  }
+  catalog.modules.sort((a, b) => a.id.localeCompare(b.id));
+  catalog.integrity.sort((a, b) => a.id.localeCompare(b.id));
+  return catalog;
+}
+
+// --- CLI (when run directly) ---
+if (process.argv[1] && process.argv[1].endsWith("modules-catalog.mjs")) {
+  const catalog = loadCatalog();
+  console.log(
+    `\nMerlin Modules catalog — ${catalog.modules.length} valid, ${catalog.invalid.length} invalid, ${catalog.integrity.length} with missing refs\n`,
+  );
+  for (const m of catalog.modules) {
+    console.log(
+      `  ✓ ${m.id.padEnd(16)} ${m.kind.padEnd(20)} ${m.deploy_kind.padEnd(16)} tier:${m.tier_min.padEnd(8)} v${m.version}`,
+    );
+  }
+  for (const bad of catalog.invalid) {
+    console.log(`  ✗ ${bad.dir}`);
+    for (const err of bad.errors) console.log(`      ${err}`);
+  }
+  for (const issue of catalog.integrity) {
+    console.log(`  ⚠ ${issue.id} — framework refs not found on disk:`);
+    for (const ref of issue.missing) console.log(`      ${ref}`);
+  }
+  console.log("");
+  process.exit(
+    catalog.invalid.length > 0 || catalog.integrity.length > 0 ? 1 : 0,
+  );
+}

package/.merlin-core/tools/provision-module.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * provision-module.mjs — the Merlin Modules provisioner (v3.5, net-new).
+ *
+ * Orchestrates a module unlock, dispatched by `deploy_kind` (research §5 + §3.2c;
+ * grimorio.md §4). Framework-generic: NO tenant defaults (especially no default
+ * workspaceId — that footgun dumps one client's data into another). Dry-run by
+ * default; every external/billable step is HIGH-stake.
+ *
+ *  - `framework-skill` (EXECUTES): verifyModule → on --apply, add the id to
+ *    config/modules.enabled[] (idempotent). No Firestore flag.
+ *  - cloud deploy_kinds (PLAN-EMIT): require an explicit --workspace, then drive a
+ *    Deployer (default PlanOnlyDeployer prints the ordered 8-step plan, executes
+ *    nothing). Real execution is delegated to the platform adapter / operator runbook.
+ *
+ *   node provision-module.mjs --module=scraping [--apply]
+ *   node provision-module.mjs --module=editorial --workspace=ws-x --tier=time \
+ *        --firebase-project=fp [--apply]
+ *
+ * @module tools/provision-module
+ */
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadCatalog } from "./modules-catalog.mjs";
+import { verifyModule } from "./verify-module.mjs";
+import { readEnabledModules, enableModule } from "./lib/modules-activation.mjs";
+import { PlanOnlyDeployer } from "./lib/deployer.mjs";
+import entitlement from "../core/licensing/entitlement.js";
+
+const { checkEntitlement } = entitlement;
+const FRAMEWORK_CORE = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/**
+ * @param {object} opts
+ * @param {string} opts.moduleId
+ * @param {string} [opts.projectRoot] - where config/modules.enabled[] is written
+ * @param {string} [opts.merlinCore] - .merlin-core root for refs (defaults to projectRoot's)
+ * @param {string} [opts.modulesDir] - module manifests dir
+ * @param {string} [opts.workspace] - REQUIRED for cloud deploy_kinds (asserted explicit)
+ * @param {string} [opts.tier] @param {string} [opts.firebaseProject]
+ * @param {boolean} [opts.apply=false]
+ * @param {object} [opts.deployer] @param {function} [opts.log]
+ */
+export async function provisionModule(opts = {}) {
+  const { moduleId, apply = false } = opts;
+  const projectRoot = opts.projectRoot || process.cwd();
+  const merlinCore = opts.merlinCore || join(projectRoot, ".merlin-core");
+  const modulesDir = opts.modulesDir || join(merlinCore, "modules");
+  const log = opts.log || (() => {});
+  const deployer = opts.deployer || new PlanOnlyDeployer({ log });
+
+  if (!moduleId) return { ok: false, error: "missing --module" };
+
+  const catalog = loadCatalog({ modulesDir, merlinCore });
+  const manifest = catalog.modules.find((m) => m.id === moduleId);
+  if (!manifest) {
+    return {
+      ok: false,
+      moduleId,
+      error: `module "${moduleId}" not found or invalid in ${modulesDir}`,
+      invalid: catalog.invalid,
+    };
+  }
+
+  // depends_on (warn-only: a missing dep is surfaced, not silently provisioned over)
+  const enabled = readEnabledModules(projectRoot);
+  const missingDeps = (manifest.depends_on || []).filter(
+    (d) => !enabled.includes(d),
+  );
+
+  // entitlement (manifest-aware; warn-only by default — license is dormant)
+  const entitled = checkEntitlement(manifest, { mode: opts.entitlementMode });
+
+  const base = {
+    moduleId,
+    deploy_kind: manifest.deploy_kind,
+    entitlement: entitled,
+    missingDeps,
+  };
+
+  // Only in explicit block mode does a denied-but-applicable entitlement stop us.
+  if (entitled.mode === "block" && entitled.applicable && !entitled.entitled) {
+    return {
+      ...base,
+      ok: false,
+      error: `entitlement denied: ${entitled.reason}`,
+    };
+  }
+
+  // --- framework-skill: EXECUTES ---
+  if (manifest.deploy_kind === "framework-skill") {
+    const verify = await verifyModule(manifest, { merlinCore });
+    if (!verify.ok) {
+      return { ...base, ok: false, verify, error: "verifyModule failed" };
+    }
+    const activation = enableModule(projectRoot, moduleId, { apply });
+    if (activation.error) {
+      return {
+        ...base,
+        ok: false,
+        verify,
+        activation,
+        error: activation.error,
+      };
+    }
+    return {
+      ...base,
+      ok: true,
+      verify,
+      applied: Boolean(apply && activation.changed),
+      activation,
+    };
+  }
+
+  // Only `firebase` has a provisioner today — the Deployer contract is
+  // Firebase-shaped (functions/rules/secrets/hosting/seed/flag). The other cloud
+  // kinds (rails-kamal/browser-extension/electron-app/dedicated-infra) ship via
+  // their own operator runbooks; refuse rather than emit a bogus Firebase plan.
+  if (manifest.deploy_kind !== "firebase") {
+    return {
+      ...base,
+      ok: false,
+      error: `deploy_kind '${manifest.deploy_kind}' has no provisioner yet — only framework-skill and firebase are supported (this kind ships via its own operator runbook)`,
+    };
+  }
+
+  // --- cloud deploy_kinds: PLAN-EMIT (require explicit workspace) ---
+  if (!opts.workspace) {
+    return {
+      ...base,
+      ok: false,
+      error:
+        "explicit --workspace is required for a cloud deploy_kind (no tenant default — guards the ws-vHvJACHk footgun)",
+    };
+  }
+
+  const ctx = {
+    workspace: opts.workspace,
+    tier: opts.tier,
+    firebaseProject: opts.firebaseProject,
+    apply,
+  };
+  const steps = [];
+  steps.push(await deployer.deployFunctions(manifest, ctx)); // §4.2
+  steps.push(await deployer.composeAndDeployRules(manifest, ctx)); // §4.3
+  steps.push(await deployer.setSecrets(manifest, ctx)); // §4.4
+  steps.push(await deployer.deployHosting(manifest, ctx)); // §4.5
+  steps.push(await deployer.seed(manifest, ctx)); // §4.6
+  const verify = await verifyModule(manifest, { merlinCore, deployer }); // §4.7
+  steps.push(await deployer.flipFlagAndWriteInstalledModules(manifest, ctx)); // §4.8
+  const executed = steps.some((s) => s && s.executed);
+
+  return {
+    ...base,
+    ok: true,
+    workspace: opts.workspace,
+    verify,
+    steps,
+    applied: Boolean(apply && executed),
+    note:
+      deployer instanceof PlanOnlyDeployer
+        ? "plan-only: cloud execution delegated to the platform adapter / operator runbook"
+        : undefined,
+  };
+}
+
+// --- CLI ---
+if (process.argv[1] && process.argv[1].endsWith("provision-module.mjs")) {
+  const args = process.argv.slice(2);
+  const val = (flag) => {
+    const eq = args.find((a) => a.startsWith(`${flag}=`));
+    if (eq) return eq.split("=").slice(1).join("=");
+    const i = args.indexOf(flag);
+    return i >= 0 && args[i + 1] && !args[i + 1].startsWith("--")
+      ? args[i + 1]
+      : undefined;
+  };
+  const result = await provisionModule({
+    projectRoot: process.cwd(),
+    merlinCore: FRAMEWORK_CORE,
+    moduleId: val("--module"),
+    workspace: val("--workspace"),
+    tier: val("--tier"),
+    firebaseProject: val("--firebase-project"),
+    apply: args.includes("--apply"),
+    log: (m) => console.log(m),
+  });
+  console.log(JSON.stringify(result, null, 2));
+  process.exit(result.ok ? 0 : 1);
+}

package/.merlin-core/tools/verify-module.mjs

@@ -0,0 +1,99 @@
+/**
+ * verify-module.mjs — the probe gate (v3.5, net-new).
+ *
+ * `verifyModule()` is the HARD pre-condition of activation: the flag/config entry
+ * flips ONLY if this passes (research §7.2). It is the seam that kills the
+ * "flag ON, code absent → silent failure" bug class.
+ *
+ *  - `framework-skill`: fully checked here (zero cloud) — framework refs resolve
+ *    on disk, the activation target is config/modules.enabled[], vault stubs are
+ *    declared.
+ *  - cloud `deploy_kind`s: delegated to an injected `deployer.probe()` (function +
+ *    rules + secret). With no deployer, returns a "planned" verdict listing the
+ *    probes it WOULD run — so the cloud path stays plan-only in the framework.
+ *
+ * @module tools/verify-module
+ */
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { checkFrameworkRefs } from "./modules-catalog.mjs";
+
+const MERLIN_CORE = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+const PLANNED_CLOUD_PROBES = [
+  { name: "function-probe", ok: false, detail: "planned: callable ping" },
+  {
+    name: "rules-read",
+    ok: false,
+    detail: "planned: rules get() on a module collection",
+  },
+  {
+    name: "secret-present",
+    ok: false,
+    detail: "planned: secret exists in the project store",
+  },
+];
+
+/**
+ * @param {object} manifest - a validated module manifest
+ * @param {object} [opts]
+ * @param {string} [opts.merlinCore] - .merlin-core root (refs resolution)
+ * @param {object} [opts.deployer] - cloud probe adapter (Phase 4); omitted ⇒ plan-only
+ * @returns {Promise<{ok:boolean, planned:boolean, checks:Array<{name,ok,detail}>}>}
+ */
+export async function verifyModule(manifest, opts = {}) {
+  const merlinCore = opts.merlinCore || MERLIN_CORE;
+
+  if (manifest.deploy_kind === "framework-skill") {
+    const checks = [];
+
+    // 1. Framework-face refs must resolve on disk (reuses the catalog check).
+    const missing = checkFrameworkRefs(manifest, { merlinCore });
+    checks.push({
+      name: "framework-refs",
+      ok: missing.length === 0,
+      detail:
+        missing.length === 0
+          ? "all skills/agents/commands/checklists resolve"
+          : `missing: ${missing.join(", ")}`,
+    });
+
+    // 2. Activation target must be config/modules.enabled[] (not a Firestore flag).
+    const activation = manifest.tenant && manifest.tenant.activation;
+    const activationOk =
+      typeof activation === "string" && /modules\.enabled/.test(activation);
+    checks.push({
+      name: "activation-target",
+      ok: activationOk,
+      detail: activationOk
+        ? `activates via ${activation}`
+        : "framework-skill must activate via config/modules.enabled[]",
+    });
+
+    // 3. Vault stubs are informational — declared now, brought by the client later.
+    const stubs =
+      (manifest.tenant && manifest.tenant.secrets_vault_stubs) || [];
+    checks.push({
+      name: "vault-stubs",
+      ok: true,
+      detail: stubs.length
+        ? `client brings: ${stubs.join(", ")}`
+        : "no client secrets required",
+    });
+
+    return { ok: checks.every((c) => c.ok), planned: false, checks };
+  }
+
+  // Cloud deploy_kinds — delegate to the injected probe, else plan-only.
+  if (opts.deployer && typeof opts.deployer.probe === "function") {
+    const result = await opts.deployer.probe(manifest, opts);
+    return {
+      ok: Boolean(result.ok),
+      planned: Boolean(result.planned),
+      checks: result.checks || [],
+    };
+  }
+
+  return { ok: false, planned: true, checks: PLANNED_CLOUD_PROBES };
+}