@odla-ai/cli 0.3.0 → 0.5.0

package/dist/bin.cjs

@@ -30,12 +30,54 @@ var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
 // src/cli.ts
 var import_node_fs7 = require("fs");
 
+// src/capabilities.ts
+var CAPABILITIES = {
+  cli: [
+    "register the app and enable configured services per environment",
+    "issue, persist, and explicitly rotate configured service credentials",
+    "write local Worker values and push deployed Worker secrets through Wrangler stdin",
+    "push db schema/rules and configure platform AI, auth, and deployment links",
+    "validate config offline and smoke-test a provisioned db environment"
+  ],
+  agent: [
+    "install and import the selected odla SDKs",
+    "wrap the Worker with withObservability and choose useful telemetry",
+    "make application-specific schema, rules, auth, UI, and migration decisions"
+  ],
+  human: [
+    "approve the odla device code and one-off third-party logins",
+    "consent to production changes with --yes",
+    "request destructive credential rotation explicitly",
+    "review application semantics, security findings, releases, and merges"
+  ],
+  studio: [
+    "view telemetry and environment state",
+    "perform manual credential recovery when the CLI's local shown-once copy is unavailable"
+  ]
+};
+function printCapabilities(json = false, out = console) {
+  if (json) {
+    out.log(JSON.stringify(CAPABILITIES, null, 2));
+    return;
+  }
+  out.log("odla-ai responsibility boundary\n");
+  printGroup(out, "CLI automates", CAPABILITIES.cli);
+  printGroup(out, "Coding agent changes source", CAPABILITIES.agent);
+  printGroup(out, "Human checkpoints", CAPABILITIES.human);
+  printGroup(out, "Studio", CAPABILITIES.studio);
+}
+function printGroup(out, heading, items) {
+  out.log(`${heading}:`);
+  for (const item of items) out.log(`  - ${item}`);
+  out.log("");
+}
+
 // src/config.ts
 var import_node_fs = require("fs");
 var import_node_path = require("path");
 var import_node_url = require("url");
 var DEFAULT_PLATFORM = "https://odla.ai";
-var DEFAULT_ENVS = ["prod", "dev"];
+var DEFAULT_ENVS = ["dev"];
 var DEFAULT_SERVICES = ["db", "ai"];
 async function loadProjectConfig(configPath = "odla.config.mjs") {
   const resolved = (0, import_node_path.resolve)(configPath);
@@ -137,8 +179,8 @@ function unique(values) {
 
 // src/doctor-checks.ts
 var import_node_child_process2 = require("child_process");
-var import_node_fs3 = require("fs");
-var import_node_path3 = require("path");
+var import_node_fs4 = require("fs");
+var import_node_path4 = require("path");
 
 // src/redact.ts
 var REPLACEMENTS = [
@@ -159,10 +201,136 @@ function looksSecret(value) {
   return redactSecrets(value) !== value || value.includes("-----BEGIN");
 }
 
-// src/wrangler.ts
-var import_node_child_process = require("child_process");
+// src/local.ts
 var import_node_fs2 = require("fs");
 var import_node_path2 = require("path");
+var GITIGNORE_LINES = [".odla/*.local.json", ".odla/dev-token.json", ".dev.vars"];
+function readJsonFile(path) {
+  try {
+    return JSON.parse((0, import_node_fs2.readFileSync)(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writePrivateJson(path, value) {
+  writePrivateText(path, `${JSON.stringify(value, null, 2)}
+`);
+}
+function readCredentials(path) {
+  if (!(0, import_node_fs2.existsSync)(path)) return null;
+  let value;
+  try {
+    value = JSON.parse((0, import_node_fs2.readFileSync)(path, "utf8"));
+  } catch {
+    throw new Error(`credentials file ${path} is not valid JSON; fix or remove it before provisioning`);
+  }
+  if (!value || typeof value !== "object" || typeof value.appId !== "string" || !value.envs || typeof value.envs !== "object") {
+    throw new Error(`credentials file ${path} has an invalid shape; fix or remove it before provisioning`);
+  }
+  return value;
+}
+function mergeCredential(current, update) {
+  const next = current ?? {
+    appId: update.appId,
+    platformUrl: update.platformUrl,
+    dbEndpoint: update.dbEndpoint,
+    updatedAt: (/* @__PURE__ */ new Date(0)).toISOString(),
+    envs: {}
+  };
+  next.appId = update.appId;
+  next.platformUrl = update.platformUrl;
+  next.dbEndpoint = update.dbEndpoint;
+  next.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  next.envs[update.env] = {
+    ...next.envs[update.env] ?? {},
+    tenantId: update.tenantId,
+    ...update.dbKey ? { dbKey: update.dbKey } : {},
+    ...update.o11yToken ? { o11yToken: update.o11yToken } : {}
+  };
+  return next;
+}
+function ensureGitignore(rootDir, localPaths = []) {
+  const path = (0, import_node_path2.resolve)(rootDir, ".gitignore");
+  const existing = (0, import_node_fs2.existsSync)(path) ? (0, import_node_fs2.readFileSync)(path, "utf8") : "";
+  const configured = localPaths.map((localPath) => gitignoreEntry(rootDir, localPath)).filter((line) => !!line);
+  const wanted = [.../* @__PURE__ */ new Set([...GITIGNORE_LINES, ...configured])];
+  const missing = wanted.filter((line) => !existing.split(/\r?\n/).includes(line));
+  if (missing.length === 0) return;
+  const prefix = existing && !existing.endsWith("\n") ? "\n" : "";
+  (0, import_node_fs2.writeFileSync)(path, `${existing}${prefix}${missing.join("\n")}
+`);
+}
+function o11yDevVars(cfg) {
+  if (!cfg.services.includes("o11y")) return void 0;
+  return {
+    endpoint: cfg.o11y?.endpoint ?? "https://o11y.odla.ai",
+    service: cfg.o11y?.service ?? cfg.app.id,
+    ...cfg.o11y?.version ? { version: cfg.o11y.version } : {}
+  };
+}
+function resolveWriteDevVarsTarget(cfg, requested) {
+  if (!requested) return null;
+  if (requested === true) return cfg.local.devVarsFile;
+  return (0, import_node_path2.resolve)((0, import_node_path2.dirname)(cfg.configPath), requested);
+}
+function writeDevVars(path, credentials, env, o11y) {
+  const entry = credentials.envs[env];
+  if (!entry) throw new Error(`no credentials for env "${env}" in ${path}`);
+  const lines = [`ODLA_PLATFORM="${credentials.platformUrl}"`];
+  if (entry.dbKey) lines.push(`ODLA_ENDPOINT="${credentials.dbEndpoint}"`);
+  lines.push(`ODLA_APP_ID="${credentials.appId}"`, `ODLA_ENV="${env}"`, `ODLA_TENANT="${entry.tenantId}"`);
+  if (entry.dbKey) lines.push(`ODLA_API_KEY="${entry.dbKey}"`);
+  if (o11y) {
+    lines.push(`ODLA_O11Y_ENDPOINT="${o11y.endpoint}"`, `ODLA_O11Y_SERVICE="${o11y.service}"`);
+    if (o11y.version) lines.push(`ODLA_O11Y_VERSION="${o11y.version}"`);
+    if (entry.o11yToken) lines.push(`ODLA_O11Y_TOKEN="${entry.o11yToken}"`);
+  }
+  const existing = (0, import_node_fs2.existsSync)(path) ? (0, import_node_fs2.readFileSync)(path, "utf8") : "";
+  const retained = existing.split(/\r?\n/).filter((line) => !isManagedDevVar(line));
+  while (retained.at(-1) === "") retained.pop();
+  const prefix = retained.length ? `${retained.join("\n")}
+
+` : "";
+  writePrivateText(path, `${prefix}${lines.join("\n")}
+`);
+}
+var MANAGED_DEV_VARS = /* @__PURE__ */ new Set([
+  "ODLA_PLATFORM",
+  "ODLA_ENDPOINT",
+  "ODLA_APP_ID",
+  "ODLA_ENV",
+  "ODLA_TENANT",
+  "ODLA_API_KEY",
+  "ODLA_O11Y_ENDPOINT",
+  "ODLA_O11Y_SERVICE",
+  "ODLA_O11Y_VERSION",
+  "ODLA_O11Y_TOKEN"
+]);
+function isManagedDevVar(line) {
+  const match = line.match(/^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=/);
+  return !!match?.[1] && MANAGED_DEV_VARS.has(match[1]);
+}
+function writePrivateText(path, text) {
+  (0, import_node_fs2.mkdirSync)((0, import_node_path2.dirname)(path), { recursive: true });
+  const temporary = `${path}.tmp-${process.pid}-${Date.now()}`;
+  (0, import_node_fs2.writeFileSync)(temporary, text, { mode: 384 });
+  (0, import_node_fs2.chmodSync)(temporary, 384);
+  (0, import_node_fs2.renameSync)(temporary, path);
+}
+function gitignoreEntry(rootDir, path) {
+  const rel = (0, import_node_path2.relative)((0, import_node_path2.resolve)(rootDir), (0, import_node_path2.resolve)(path));
+  if (!rel || rel === ".." || rel.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) || (0, import_node_path2.isAbsolute)(rel)) return null;
+  return rel.replaceAll("\\", "/");
+}
+function displayPath(path, rootDir = process.cwd()) {
+  const rel = (0, import_node_path2.relative)(rootDir, path);
+  return rel && !rel.startsWith("..") ? rel : path;
+}
+
+// src/wrangler.ts
+var import_node_child_process = require("child_process");
+var import_node_fs3 = require("fs");
+var import_node_path3 = require("path");
 var defaultRunner = (cmd, args, opts) => new Promise((resolvePromise, reject) => {
   const child = (0, import_node_child_process.spawn)(cmd, args, { cwd: opts?.cwd, stdio: ["pipe", "pipe", "pipe"] });
   let stdout = "";
@@ -176,15 +344,15 @@ var defaultRunner = (cmd, args, opts) => new Promise((resolvePromise, reject) =>
 var WRANGLER_CONFIG_FILES = ["wrangler.jsonc", "wrangler.json", "wrangler.toml"];
 function findWranglerConfig(rootDir) {
   for (const name of WRANGLER_CONFIG_FILES) {
-    const path = (0, import_node_path2.join)(rootDir, name);
-    if ((0, import_node_fs2.existsSync)(path)) return path;
+    const path = (0, import_node_path3.join)(rootDir, name);
+    if ((0, import_node_fs3.existsSync)(path)) return path;
   }
   return null;
 }
 function readWranglerConfig(path) {
   if (path.endsWith(".toml")) return null;
   try {
-    return JSON.parse(stripJsonComments((0, import_node_fs2.readFileSync)(path, "utf8")));
+    return JSON.parse(stripJsonComments((0, import_node_fs3.readFileSync)(path, "utf8")));
   } catch {
     return null;
   }
@@ -256,10 +424,11 @@ function lintRules(rules, entities, publicRead) {
   return warnings;
 }
 var defaultExec = (cmd, args, cwd) => (0, import_node_child_process2.execFileSync)(cmd, args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
-function trackedSecretFiles(rootDir, exec = defaultExec) {
+function trackedSecretFiles(rootDir, exec = defaultExec, localPaths = []) {
   let output;
   try {
-    output = exec("git", ["ls-files", "--", ".dev.vars", ".odla"], rootDir);
+    const custom = localPaths.map((path) => gitignoreEntry(rootDir, path)).filter((path) => !!path);
+    output = exec("git", ["ls-files", "--", ".dev.vars", ".odla", ...custom], rootDir);
   } catch {
     return [];
   }
@@ -281,10 +450,10 @@ function wranglerWarnings(rootDir) {
   for (const { label, block } of blocks) {
     const assets = block.assets;
     if (assets?.directory) {
-      const dir = (0, import_node_path3.resolve)(rootDir, assets.directory);
-      if (dir === (0, import_node_path3.resolve)(rootDir)) {
+      const dir = (0, import_node_path4.resolve)(rootDir, assets.directory);
+      if (dir === (0, import_node_path4.resolve)(rootDir)) {
         warnings.push(`${label}assets.directory is the project root \u2014 point it at a dedicated build dir (wrangler dev fails with "spawn EBADF")`);
-      } else if ((0, import_node_fs3.existsSync)((0, import_node_path3.join)(dir, "node_modules"))) {
+      } else if ((0, import_node_fs4.existsSync)((0, import_node_path4.join)(dir, "node_modules"))) {
         warnings.push(`${label}assets.directory contains node_modules \u2014 wrangler dev's watcher will exhaust file descriptors`);
       }
     }
@@ -303,96 +472,57 @@ function wranglerWarnings(rootDir) {
   }
   return warnings;
 }
-function readPackageJson(rootDir) {
-  try {
-    return JSON.parse((0, import_node_fs3.readFileSync)((0, import_node_path3.join)(rootDir, "package.json"), "utf8"));
-  } catch {
-    return null;
+function o11yProjectWarnings(rootDir) {
+  const warnings = [];
+  const pkg = readPackageJson(rootDir);
+  const dependencies = pkg?.dependencies;
+  const devDependencies = pkg?.devDependencies;
+  if (!dependencies?.["@odla-ai/o11y"]) {
+    warnings.push(
+      devDependencies?.["@odla-ai/o11y"] ? "@odla-ai/o11y is a devDependency \u2014 move it to dependencies so the Worker can import it" : 'Worker instrumentation is missing @odla-ai/o11y \u2014 install it and wrap the handler with "withObservability"'
+    );
   }
+  const configPath = findWranglerConfig(rootDir);
+  const config = configPath ? readWranglerConfig(configPath) : null;
+  if (!configPath || !config) {
+    warnings.push("cannot verify o11y Worker instrumentation \u2014 add a parseable wrangler.jsonc/json config");
+    return warnings;
+  }
+  const main = typeof config.main === "string" ? (0, import_node_path4.resolve)(rootDir, config.main) : null;
+  if (!main || !(0, import_node_fs4.existsSync)(main)) {
+    warnings.push("cannot verify o11y Worker instrumentation \u2014 wrangler main is missing or unreadable");
+  } else {
+    let source = "";
+    try {
+      source = (0, import_node_fs4.readFileSync)(main, "utf8");
+    } catch {
+    }
+    if (!/\bwithObservability\b/.test(source)) {
+      warnings.push(`wrangler entrypoint ${config.main} does not reference withObservability`);
+    }
+  }
+  const flags = Array.isArray(config.compatibility_flags) ? config.compatibility_flags : [];
+  if (!flags.includes("nodejs_compat")) {
+    warnings.push('wrangler compatibility_flags is missing "nodejs_compat" required by @odla-ai/o11y');
+  }
+  return warnings;
 }
-
-// src/local.ts
-var import_node_fs4 = require("fs");
-var import_node_path4 = require("path");
-var GITIGNORE_LINES = [".odla/*.local.json", ".odla/dev-token.json", ".dev.vars"];
-function readJsonFile(path) {
+function readPackageJson(rootDir) {
   try {
-    return JSON.parse((0, import_node_fs4.readFileSync)(path, "utf8"));
+    return JSON.parse((0, import_node_fs4.readFileSync)((0, import_node_path4.join)(rootDir, "package.json"), "utf8"));
   } catch {
     return null;
   }
 }
-function writePrivateJson(path, value) {
-  (0, import_node_fs4.mkdirSync)((0, import_node_path4.dirname)(path), { recursive: true });
-  (0, import_node_fs4.writeFileSync)(path, `${JSON.stringify(value, null, 2)}
-`);
-  (0, import_node_fs4.chmodSync)(path, 384);
-}
-function readCredentials(path) {
-  return readJsonFile(path);
-}
-function mergeCredential(current, update) {
-  const next = current ?? {
-    appId: update.appId,
-    platformUrl: update.platformUrl,
-    dbEndpoint: update.dbEndpoint,
-    updatedAt: (/* @__PURE__ */ new Date(0)).toISOString(),
-    envs: {}
-  };
-  next.appId = update.appId;
-  next.platformUrl = update.platformUrl;
-  next.dbEndpoint = update.dbEndpoint;
-  next.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-  next.envs[update.env] = {
-    ...next.envs[update.env] ?? {},
-    tenantId: update.tenantId,
-    ...update.dbKey ? { dbKey: update.dbKey } : {},
-    ...update.o11yToken ? { o11yToken: update.o11yToken } : {}
-  };
-  return next;
-}
-function ensureGitignore(rootDir) {
-  const path = (0, import_node_path4.resolve)(rootDir, ".gitignore");
-  const existing = (0, import_node_fs4.existsSync)(path) ? (0, import_node_fs4.readFileSync)(path, "utf8") : "";
-  const missing = GITIGNORE_LINES.filter((line) => !existing.split(/\r?\n/).includes(line));
-  if (missing.length === 0) return;
-  const prefix = existing && !existing.endsWith("\n") ? "\n" : "";
-  (0, import_node_fs4.writeFileSync)(path, `${existing}${prefix}${missing.join("\n")}
-`);
-}
-function writeDevVars(path, credentials, env, o11y) {
-  const entry = credentials.envs[env];
-  if (!entry?.dbKey) throw new Error(`no db key for env "${env}" in ${path}`);
-  const lines = [
-    `ODLA_PLATFORM="${credentials.platformUrl}"`,
-    `ODLA_ENDPOINT="${credentials.dbEndpoint}"`,
-    `ODLA_APP_ID="${credentials.appId}"`,
-    `ODLA_ENV="${env}"`,
-    `ODLA_TENANT="${entry.tenantId}"`,
-    `ODLA_API_KEY="${entry.dbKey}"`
-  ];
-  if (o11y) {
-    lines.push(`ODLA_O11Y_ENDPOINT="${o11y.endpoint}"`, `ODLA_O11Y_SERVICE="${o11y.service}"`);
-    if (o11y.version) lines.push(`ODLA_O11Y_VERSION="${o11y.version}"`);
-    if (entry.o11yToken) lines.push(`ODLA_O11Y_TOKEN="${entry.o11yToken}"`);
-  }
-  (0, import_node_fs4.mkdirSync)((0, import_node_path4.dirname)(path), { recursive: true });
-  (0, import_node_fs4.writeFileSync)(path, `${lines.join("\n")}
-`);
-  (0, import_node_fs4.chmodSync)(path, 384);
-}
-function displayPath(path, rootDir = process.cwd()) {
-  const rel = (0, import_node_path4.relative)(rootDir, path);
-  return rel && !rel.startsWith("..") ? rel : path;
-}
 
 // src/doctor.ts
 async function doctor(options) {
   const out = options.stdout ?? console;
   const cfg = await loadProjectConfig(options.configPath);
   const plan = buildPlan(cfg);
-  const schema = await resolveDataExport(cfg, cfg.db?.schema, ["schema", "SCHEMA"]);
-  const configuredRules = await resolveDataExport(cfg, cfg.db?.rules, ["rules", "RULES"]);
+  const hasDb = cfg.services.includes("db");
+  const schema = hasDb ? await resolveDataExport(cfg, cfg.db?.schema, ["schema", "SCHEMA"]) : void 0;
+  const configuredRules = hasDb ? await resolveDataExport(cfg, cfg.db?.rules, ["rules", "RULES"]) : void 0;
   const rules = configuredRules ?? (schema && cfg.db?.defaultRules !== false ? rulesFromSchema(schema) : void 0);
   const entities = serializedEntities(schema);
   out.log(`config: ${cfg.configPath}`);
@@ -401,7 +531,7 @@ async function doctor(options) {
   out.log(`svc:    ${plan.services.join(", ")}`);
   out.log(`schema: ${schema ? `${entities.length} entities` : "none"}`);
   out.log(`rules:  ${rules ? `${Object.keys(rules).length} namespaces` : "none"}`);
-  out.log(`ai:     ${cfg.ai?.provider ?? "not configured"}`);
+  out.log(`ai:     ${cfg.services.includes("ai") ? cfg.ai?.provider ?? "not configured" : "not enabled"}`);
   const warnings = [];
   if (schema && entities.length === 0) warnings.push("schema has no entities");
   if (rules) {
@@ -417,7 +547,9 @@ async function doctor(options) {
       }
     }
   }
-  if (cfg.ai?.keyEnv && !process.env[cfg.ai.keyEnv]) warnings.push(`${cfg.ai.keyEnv} is not set; provision will skip provider key storage`);
+  if (cfg.services.includes("ai") && cfg.ai?.keyEnv && !process.env[cfg.ai.keyEnv]) {
+    warnings.push(`${cfg.ai.keyEnv} is not set; provision will skip provider key storage`);
+  }
   if (cfg.services.includes("o11y")) {
     const credentials = readCredentials(cfg.local.credentialsFile);
     for (const env of cfg.envs) {
@@ -425,9 +557,14 @@ async function doctor(options) {
         warnings.push(`o11y is enabled but env "${env}" has no ingest token \u2014 run "odla-ai provision" to mint one`);
       }
     }
+    warnings.push(...o11yProjectWarnings(cfg.rootDir));
   }
   warnings.push(...lintRules(rules, entities, cfg.db?.publicRead ?? []));
-  warnings.push(...trackedSecretFiles(cfg.rootDir));
+  warnings.push(...trackedSecretFiles(cfg.rootDir, void 0, [
+    cfg.local.tokenFile,
+    cfg.local.credentialsFile,
+    cfg.local.devVarsFile
+  ]));
   warnings.push(...wranglerWarnings(cfg.rootDir));
   if (warnings.length) {
     out.log("");
@@ -451,7 +588,7 @@ function initProject(options) {
   if (!/^[a-z0-9][a-z0-9-]*$/.test(options.appId)) {
     throw new Error("--app-id must be lowercase letters, numbers, and hyphens");
   }
-  const envs = options.envs?.length ? options.envs : ["prod", "dev"];
+  const envs = options.envs?.length ? options.envs : ["dev"];
   const services = options.services?.length ? options.services : ["db", "ai"];
   const aiProvider = options.aiProvider ?? "anthropic";
   (0, import_node_fs5.mkdirSync)((0, import_node_path5.dirname)(configPath), { recursive: true });
@@ -554,9 +691,8 @@ function relativeDisplay(path, rootDir) {
 }
 
 // src/provision.ts
-var import_apps = require("@odla-ai/apps");
+var import_apps2 = require("@odla-ai/apps");
 var import_ai = require("@odla-ai/ai");
-var import_node_path6 = require("path");
 var import_node_process3 = __toESM(require("process"), 1);
 
 // src/token.ts
@@ -569,7 +705,7 @@ var import_node_process = __toESM(require("process"), 1);
 async function openUrl(url, options = {}) {
   const command = openerFor(options.platform ?? import_node_process.default.platform);
   const doSpawn = options.spawnImpl ?? import_node_child_process3.spawn;
-  await new Promise((resolve7, reject) => {
+  await new Promise((resolve6, reject) => {
     const child = doSpawn(command.cmd, [...command.args, url], {
       stdio: "ignore",
       detached: true
@@ -577,7 +713,7 @@ async function openUrl(url, options = {}) {
     child.once("error", reject);
     child.once("spawn", () => {
       child.unref();
-      resolve7();
+      resolve6();
     });
   });
 }
@@ -631,35 +767,238 @@ function approvalBrowser(options) {
   return { open: true, mode: "auto" };
 }
 function handshakeUrl(platformUrl, userCode) {
-  const url = new URL("/handshakes", platformUrl);
+  const url = new URL("/studio", platformUrl);
   url.searchParams.set("code", userCode);
   return url.toString();
 }
 
+// src/provision-credentials.ts
+var import_apps = require("@odla-ai/apps");
+async function provisionEnvCredentials(opts) {
+  const tenantId = (0, import_apps.tenantIdFor)(opts.cfg.app.id, opts.env);
+  const prior = opts.credentials?.envs[opts.env];
+  let credentials = opts.credentials;
+  let dbKey = opts.cfg.services.includes("db") && !opts.rotateDb ? prior?.dbKey : void 0;
+  let o11yToken = opts.cfg.services.includes("o11y") && !opts.rotateO11y ? prior?.o11yToken : void 0;
+  if (opts.cfg.services.includes("db")) {
+    if (dbKey) {
+      opts.stdout.log(`${opts.env}: reusing local db key for ${tenantId}`);
+    } else {
+      dbKey = await mintDbKey(opts, tenantId);
+      credentials = save(opts, credentials, tenantId, { dbKey });
+      opts.stdout.log(`${opts.env}: minted db key for ${tenantId}`);
+    }
+  }
+  if (opts.cfg.services.includes("o11y")) {
+    if (o11yToken) {
+      opts.stdout.log(`${opts.env}: reusing local o11y ingest token`);
+    } else {
+      o11yToken = await issueO11yToken(opts);
+      credentials = save(opts, credentials, tenantId, { ...dbKey ? { dbKey } : {}, o11yToken });
+      opts.stdout.log(`${opts.env}: ${opts.rotateO11y ? "rotated" : "issued"} o11y ingest token`);
+    }
+  }
+  return save(opts, credentials, tenantId, {
+    ...dbKey ? { dbKey } : {},
+    ...o11yToken ? { o11yToken } : {}
+  });
+}
+function save(opts, current, tenantId, values) {
+  const next = mergeCredential(current, {
+    appId: opts.cfg.app.id,
+    platformUrl: opts.cfg.platformUrl,
+    dbEndpoint: opts.cfg.dbEndpoint,
+    env: opts.env,
+    tenantId,
+    ...values
+  });
+  if (opts.write) writePrivateJson(opts.cfg.local.credentialsFile, next);
+  return next;
+}
+async function mintDbKey(opts, tenantId) {
+  const headers = { authorization: `Bearer ${opts.developerToken}`, "content-type": "application/json" };
+  let res = await opts.fetch(`${opts.cfg.dbEndpoint}/admin/apps/${encodeURIComponent(tenantId)}/keys`, {
+    method: "POST",
+    headers,
+    body: "{}"
+  });
+  if (res.status === 404) {
+    const created = await opts.fetch(`${opts.cfg.dbEndpoint}/admin/apps`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        name: opts.env === "prod" ? opts.cfg.app.name : `${opts.cfg.app.name} (${opts.env})`,
+        appId: tenantId
+      })
+    });
+    if (!created.ok) throw new Error(`db app create (${tenantId}) failed: ${created.status} ${await safeText(created)}`);
+    res = await opts.fetch(`${opts.cfg.dbEndpoint}/admin/apps/${encodeURIComponent(tenantId)}/keys`, {
+      method: "POST",
+      headers,
+      body: "{}"
+    });
+  }
+  if (!res.ok) throw new Error(`db key mint (${tenantId}) failed: ${res.status} ${await safeText(res)}`);
+  const body = await res.json();
+  if (!body.key) throw new Error(`db key mint (${tenantId}) returned no key`);
+  return body.key;
+}
+async function issueO11yToken(opts) {
+  const suffix = opts.rotateO11y ? "/rotate" : "";
+  const res = await opts.fetch(
+    `${opts.cfg.platformUrl}/o11y/${encodeURIComponent(opts.cfg.app.id)}/token${suffix}?env=${encodeURIComponent(opts.env)}`,
+    { method: "POST", headers: { authorization: `Bearer ${opts.developerToken}` } }
+  );
+  if (res.status === 409 && !opts.rotateO11y) {
+    throw new Error(
+      `o11y token already exists for env "${opts.env}", but its shown-once value is not in the local credentials file; run "odla-ai provision --rotate-o11y-token --push-secrets" to replace it explicitly`
+    );
+  }
+  if (!res.ok) throw new Error(`o11y token ${opts.rotateO11y ? "rotation" : "issue"} (${opts.env}) failed: ${res.status} ${await safeText(res)}`);
+  const body = await res.json();
+  if (!body.token) throw new Error(`o11y token ${opts.rotateO11y ? "rotation" : "issue"} (${opts.env}) returned no token`);
+  return body.token;
+}
+async function safeText(res) {
+  try {
+    return redactSecrets((await res.text()).slice(0, 500));
+  } catch {
+    return "";
+  }
+}
+
+// src/secrets.ts
+var PROD_ENV_NAMES = /* @__PURE__ */ new Set(["prod", "production"]);
+async function secretsPush(options) {
+  await secretsPushImpl(options, true);
+}
+async function secretsPushAfterPreflight(options) {
+  await secretsPushImpl(options, false);
+}
+async function secretsPushImpl(options, preflight) {
+  const out = options.stdout ?? console;
+  const cfg = await loadProjectConfig(options.configPath);
+  const env = options.env;
+  if (!cfg.envs.includes(env)) {
+    throw new Error(`env "${env}" is not in config envs (${cfg.envs.join(", ")})`);
+  }
+  if (PROD_ENV_NAMES.has(env) && !options.yes) {
+    throw new Error(`refusing to push a secret to "${env}" without --yes`);
+  }
+  const credentialsPath = displayPath(cfg.local.credentialsFile, cfg.rootDir);
+  const credentials = readCredentials(cfg.local.credentialsFile);
+  if (!credentials) throw new Error(`no credentials at ${credentialsPath} \u2014 run "odla-ai provision" first`);
+  if (credentials.appId !== cfg.app.id) {
+    throw new Error(`credentials at ${credentialsPath} are for "${credentials.appId}", not "${cfg.app.id}"`);
+  }
+  const entry = credentials.envs[env];
+  if (!entry) throw new Error(`no credentials for env "${env}" in ${credentialsPath} \u2014 run "odla-ai provision" first`);
+  const secrets = [];
+  if (cfg.services.includes("o11y")) {
+    if (!entry.o11yToken) throw new Error(`no o11y token for env "${env}" in ${credentialsPath} \u2014 run "odla-ai provision" first`);
+    secrets.push({ name: "ODLA_O11Y_TOKEN", value: entry.o11yToken });
+  }
+  if (cfg.services.includes("db")) {
+    if (!entry.dbKey) throw new Error(`no db key for env "${env}" in ${credentialsPath} \u2014 run "odla-ai provision" first`);
+    secrets.push({ name: "ODLA_API_KEY", value: entry.dbKey });
+  }
+  if (secrets.length === 0) {
+    out.log(`${env}: no configured Worker secrets to push`);
+    return;
+  }
+  const wranglerEnv = PROD_ENV_NAMES.has(env) ? void 0 : env;
+  const target = wranglerEnv ? `wrangler env "${wranglerEnv}"` : "the top-level (prod) wrangler env";
+  if (options.dryRun) {
+    assertWranglerConfig(cfg);
+    for (const s of secrets) out.log(`dry run: would push ${s.name} (${redactSecrets(s.value)}) to ${target}`);
+    return;
+  }
+  const run = options.runner ?? defaultRunner;
+  if (preflight) await preflightLoadedConfig(cfg, run);
+  for (const s of secrets) {
+    const result = await wranglerPutSecret(run, { name: s.name, value: s.value, env: wranglerEnv, cwd: cfg.rootDir });
+    if (result.code !== 0) {
+      throw new Error(`wrangler secret put ${s.name} failed (exit ${result.code}): ${redactSecrets(`${result.stderr || result.stdout}`.trim())}`);
+    }
+    out.log(`${s.name} pushed to ${target} (value read from ${credentialsPath}, never echoed)`);
+  }
+}
+async function preflightSecretsPush(options) {
+  const cfg = await loadProjectConfig(options.configPath);
+  if (!cfg.services.some((service) => service === "db" || service === "o11y")) return;
+  await preflightLoadedConfig(cfg, options.runner ?? defaultRunner);
+}
+async function preflightLoadedConfig(cfg, run) {
+  assertWranglerConfig(cfg);
+  if (!await wranglerLoggedIn(run, cfg.rootDir)) {
+    throw new Error(`wrangler is not logged in \u2014 run "wrangler login" (a browser step for the human)`);
+  }
+}
+function assertWranglerConfig(cfg) {
+  if (!findWranglerConfig(cfg.rootDir)) {
+    throw new Error(`no wrangler config found in ${cfg.rootDir} (wrangler.jsonc, wrangler.json, or wrangler.toml)`);
+  }
+}
+
 // src/provision.ts
 async function provision(options) {
   const out = options.stdout ?? console;
   const cfg = await loadProjectConfig(options.configPath);
   const plan = buildPlan(cfg);
+  const hasDb = cfg.services.includes("db");
+  const hasO11y = cfg.services.includes("o11y");
+  if (options.rotateO11yToken && !hasO11y) {
+    throw new Error("--rotate-o11y-token requires the o11y service in odla.config.mjs");
+  }
+  if (options.pushSecrets && options.writeCredentials === false) {
+    throw new Error("--push-secrets cannot be combined with --no-write-credentials");
+  }
   out.log(`odla-ai: ${plan.appName} (${plan.appId})`);
   out.log(`  platform: ${plan.platformUrl}`);
   out.log(`  db:       ${plan.dbEndpoint}`);
   out.log(`  envs:     ${plan.envs.join(", ")}`);
   out.log(`  services: ${plan.services.join(", ")}`);
-  const schema = await resolveDataExport(cfg, cfg.db?.schema, ["schema", "SCHEMA"]);
-  const configuredRules = await resolveDataExport(cfg, cfg.db?.rules, ["rules", "RULES"]);
+  const productionEnvs = plan.envs.filter((env) => env === "prod" || env === "production");
+  if (!options.dryRun && productionEnvs.length > 0 && !options.yes) {
+    throw new Error(
+      `refusing to provision production env ${productionEnvs.join(", ")} without --yes; run --dry-run first`
+    );
+  }
+  const schema = hasDb ? await resolveDataExport(cfg, cfg.db?.schema, ["schema", "SCHEMA"]) : void 0;
+  const configuredRules = hasDb ? await resolveDataExport(cfg, cfg.db?.rules, ["rules", "RULES"]) : void 0;
   const rules = configuredRules ?? (schema && cfg.db?.defaultRules !== false ? rulesFromSchema(schema) : void 0);
   if (options.dryRun) {
     out.log("dry run: no network calls or file writes");
     out.log(`  schema: ${schema ? "yes" : "no"}`);
     out.log(`  rules:  ${rules ? Object.keys(rules).length : 0} namespaces`);
-    out.log(`  ai:     ${cfg.ai?.provider ?? "not configured"}`);
+    out.log(`  ai:     ${cfg.services.includes("ai") ? cfg.ai?.provider ?? "not configured" : "not enabled"}`);
+    out.log(`  secrets: ${options.pushSecrets ? "push configured Worker secrets" : "local only"}`);
     return;
   }
+  let credentials = readCredentials(cfg.local.credentialsFile);
+  if (credentials && credentials.appId !== cfg.app.id) {
+    throw new Error(
+      `credentials at ${displayPath(cfg.local.credentialsFile, cfg.rootDir)} are for "${credentials.appId}", not "${cfg.app.id}"`
+    );
+  }
+  const rotatesO11y = !!(options.rotateKeys || options.rotateO11yToken);
+  const missingO11y = cfg.envs.some((env) => !credentials?.envs[env]?.o11yToken);
+  const missingDb = cfg.envs.some((env) => !credentials?.envs[env]?.dbKey);
+  const losesShownOnceCredential = hasDb && (!!options.rotateKeys || missingDb) || hasO11y && (rotatesO11y || missingO11y);
+  if (options.writeCredentials === false && losesShownOnceCredential) {
+    throw new Error("credential issuance/rotation requires the private credentials file; remove --no-write-credentials");
+  }
+  const devVarsTarget = resolveWriteDevVarsTarget(cfg, options.writeDevVars);
+  if (cfg.local.gitignore) {
+    ensureGitignore(cfg.rootDir, [cfg.local.tokenFile, cfg.local.credentialsFile, ...devVarsTarget ? [devVarsTarget] : []]);
+  }
+  if (options.pushSecrets) {
+    await preflightSecretsPush({ configPath: cfg.configPath, runner: options.secretRunner });
+    out.log("secrets: Wrangler config and login preflight passed");
+  }
   const doFetch = options.fetch ?? fetch;
   const token = await getDeveloperToken(cfg, options, doFetch, out);
-  const auth = { authorization: `Bearer ${token}`, "content-type": "application/json" };
-  const apps = (0, import_apps.createAppsClient)({ endpoint: cfg.platformUrl, token, fetcher: { fetch: doFetch } });
+  const apps = (0, import_apps2.createAppsClient)({ endpoint: cfg.platformUrl, token, fetcher: { fetch: doFetch } });
   const existing = await readRegistryApp(cfg, token, doFetch);
   if (existing) {
     out.log(`app: ${cfg.app.id} already exists`);
@@ -693,26 +1032,40 @@ async function provision(options) {
       out.log(`${env}: link ${link ? "set" : "cleared"}`);
     }
   }
-  let credentials = readCredentials(cfg.local.credentialsFile);
   for (const env of cfg.envs) {
-    const tenantId = (0, import_apps.tenantIdFor)(cfg.app.id, env);
-    let dbKey = !options.rotateKeys ? credentials?.envs[env]?.dbKey : void 0;
-    if (dbKey) {
-      out.log(`${env}: reusing local db key for ${tenantId}`);
-    } else {
-      dbKey = await mintDbKey({ cfg, tenantId, env, token, auth, fetch: doFetch });
-      out.log(`${env}: minted db key for ${tenantId}`);
-    }
-    let o11yToken = cfg.services.includes("o11y") && !options.rotateKeys ? credentials?.envs[env]?.o11yToken : void 0;
-    if (cfg.services.includes("o11y")) {
-      if (o11yToken) {
-        out.log(`${env}: reusing local o11y ingest token`);
-      } else {
-        o11yToken = await mintO11yToken(cfg, env, token, doFetch);
-        out.log(`${env}: minted o11y ingest token`);
+    const tenantId = (0, import_apps2.tenantIdFor)(cfg.app.id, env);
+    credentials = await provisionEnvCredentials({
+      cfg,
+      env,
+      developerToken: token,
+      credentials,
+      rotateDb: !!options.rotateKeys,
+      rotateO11y: rotatesO11y,
+      write: options.writeCredentials !== false,
+      fetch: doFetch,
+      stdout: out
+    });
+    const dbKey = credentials.envs[env]?.dbKey;
+    if (options.pushSecrets) {
+      try {
+        await secretsPushAfterPreflight({
+          configPath: cfg.configPath,
+          env,
+          yes: options.yes,
+          runner: options.secretRunner,
+          stdout: out
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const consent = env === "prod" || env === "production" ? " --yes" : "";
+        throw new Error(
+          `${message}
+${env}: credentials are already saved; retry "odla-ai secrets push --env ${env}${consent}" without issuing or rotating again`,
+          { cause: error }
+        );
       }
     }
-    if (schema) {
+    if (schema && dbKey) {
       await postJson(doFetch, `${cfg.dbEndpoint}/app/${encodeURIComponent(tenantId)}/schema`, dbKey, { schema });
       out.log(`${env}: schema pushed`);
     }
@@ -720,7 +1073,7 @@ async function provision(options) {
       await postJson(doFetch, `${cfg.dbEndpoint}/app/${encodeURIComponent(tenantId)}/admin/rules`, token, rules);
       out.log(`${env}: rules pushed (${Object.keys(rules).length} namespaces)`);
     }
-    if (cfg.ai?.provider && cfg.ai.keyEnv) {
+    if (cfg.services.includes("ai") && cfg.ai?.provider && cfg.ai.keyEnv) {
       const key = import_node_process3.default.env[cfg.ai.keyEnv];
       if (key) {
         const secretName = cfg.ai.secretName ?? defaultSecretName(cfg.ai.provider);
@@ -730,36 +1083,17 @@ async function provision(options) {
         out.log(`${env}: ${cfg.ai.keyEnv} not set; skipped provider key storage`);
       }
     }
-    credentials = mergeCredential(credentials, {
-      appId: cfg.app.id,
-      platformUrl: cfg.platformUrl,
-      dbEndpoint: cfg.dbEndpoint,
-      env,
-      tenantId,
-      dbKey,
-      ...o11yToken ? { o11yToken } : {}
-    });
   }
-  if (cfg.local.gitignore) ensureGitignore(cfg.rootDir);
   if (options.writeCredentials !== false && credentials) {
-    writePrivateJson(cfg.local.credentialsFile, credentials);
-    out.log(`credentials: wrote ${displayPath(cfg.local.credentialsFile, cfg.rootDir)} (0600, gitignored)`);
+    const ignored = cfg.local.gitignore && gitignoreEntry(cfg.rootDir, cfg.local.credentialsFile);
+    out.log(`credentials: wrote ${displayPath(cfg.local.credentialsFile, cfg.rootDir)} (0600${ignored ? ", gitignored" : ""})`);
   }
-  const devVarsTarget = resolveWriteDevVarsTarget(cfg, options.writeDevVars);
   if (devVarsTarget && credentials) {
     const env = cfg.envs.includes("dev") ? "dev" : cfg.envs[0] ?? "prod";
     writeDevVars(devVarsTarget, credentials, env, o11yDevVars(cfg));
     out.log(`dev vars: wrote ${displayPath(devVarsTarget, cfg.rootDir)} for ${env}`);
   }
 }
-function o11yDevVars(cfg) {
-  if (!cfg.services.includes("o11y")) return void 0;
-  return {
-    endpoint: cfg.o11y?.endpoint ?? "https://o11y.odla.ai",
-    service: cfg.o11y?.service ?? cfg.app.id,
-    ...cfg.o11y?.version ? { version: cfg.o11y.version } : {}
-  };
-}
 async function readRegistryApp(cfg, token, doFetch) {
   const res = await doFetch(`${cfg.platformUrl}/registry/apps/${encodeURIComponent(cfg.app.id)}`, {
     headers: { authorization: `Bearer ${token}` }
@@ -769,50 +1103,13 @@ async function readRegistryApp(cfg, token, doFetch) {
   const json = await res.json();
   return json.app ?? null;
 }
-async function mintDbKey(opts) {
-  let res = await opts.fetch(`${opts.cfg.dbEndpoint}/admin/apps/${encodeURIComponent(opts.tenantId)}/keys`, {
-    method: "POST",
-    headers: opts.auth,
-    body: "{}"
-  });
-  if (res.status === 404) {
-    const created = await opts.fetch(`${opts.cfg.dbEndpoint}/admin/apps`, {
-      method: "POST",
-      headers: opts.auth,
-      body: JSON.stringify({
-        name: opts.env === "prod" ? opts.cfg.app.name : `${opts.cfg.app.name} (${opts.env})`,
-        appId: opts.tenantId
-      })
-    });
-    if (!created.ok) throw new Error(`db app create (${opts.tenantId}) failed: ${created.status} ${await safeText(created)}`);
-    res = await opts.fetch(`${opts.cfg.dbEndpoint}/admin/apps/${encodeURIComponent(opts.tenantId)}/keys`, {
-      method: "POST",
-      headers: opts.auth,
-      body: "{}"
-    });
-  }
-  if (!res.ok) throw new Error(`db key mint (${opts.tenantId}) failed: ${res.status} ${await safeText(res)}`);
-  const body = await res.json();
-  if (!body.key) throw new Error(`db key mint (${opts.tenantId}) returned no key`);
-  return body.key;
-}
-async function mintO11yToken(cfg, env, token, doFetch) {
-  const res = await doFetch(
-    `${cfg.platformUrl}/o11y/${encodeURIComponent(cfg.app.id)}/token?env=${encodeURIComponent(env)}`,
-    { method: "POST", headers: { authorization: `Bearer ${token}` } }
-  );
-  if (!res.ok) throw new Error(`o11y token mint (${env}) failed: ${res.status} ${await safeText(res)}`);
-  const body = await res.json();
-  if (!body.token) throw new Error(`o11y token mint (${env}) returned no token`);
-  return body.token;
-}
 async function postJson(doFetch, url, bearer, body) {
   const res = await doFetch(url, {
     method: "POST",
     headers: { authorization: `Bearer ${bearer}`, "content-type": "application/json" },
     body: JSON.stringify(body)
   });
-  if (!res.ok) throw new Error(`${new URL(url).pathname} failed: ${res.status} ${await safeText(res)}`);
+  if (!res.ok) throw new Error(`${new URL(url).pathname} failed: ${res.status} ${await safeText2(res)}`);
 }
 function normalizeClerkConfig(value) {
   if (!value) return null;
@@ -829,12 +1126,7 @@ function defaultSecretName(provider) {
   const names = import_ai.DEFAULT_SECRET_NAMES;
   return names[provider] ?? `${provider}_api_key`;
 }
-function resolveWriteDevVarsTarget(cfg, requested) {
-  if (!requested) return null;
-  if (requested === true) return cfg.local.devVarsFile;
-  return (0, import_node_path6.resolve)((0, import_node_path6.dirname)(cfg.configPath), requested);
-}
-async function safeText(res) {
+async function safeText2(res) {
   try {
     return redactSecrets((await res.text()).slice(0, 500));
   } catch {
@@ -842,106 +1134,253 @@ async function safeText(res) {
   }
 }
 
-// src/secrets.ts
-var PROD_ENV_NAMES = /* @__PURE__ */ new Set(["prod", "production"]);
-async function secretsPush(options) {
-  const out = options.stdout ?? console;
-  const cfg = await loadProjectConfig(options.configPath);
-  const env = options.env;
-  if (!cfg.envs.includes(env)) {
-    throw new Error(`env "${env}" is not in config envs (${cfg.envs.join(", ")})`);
-  }
-  if (PROD_ENV_NAMES.has(env) && !options.yes) {
-    throw new Error(`refusing to push a secret to "${env}" without --yes`);
-  }
-  const credentialsPath = displayPath(cfg.local.credentialsFile, cfg.rootDir);
-  const credentials = readCredentials(cfg.local.credentialsFile);
-  if (!credentials) throw new Error(`no credentials at ${credentialsPath} \u2014 run "odla-ai provision" first`);
-  if (credentials.appId !== cfg.app.id) {
-    throw new Error(`credentials at ${credentialsPath} are for "${credentials.appId}", not "${cfg.app.id}"`);
-  }
-  const dbKey = credentials.envs[env]?.dbKey;
-  if (!dbKey) throw new Error(`no db key for env "${env}" in ${credentialsPath} \u2014 run "odla-ai provision" first`);
-  const wranglerConfig = findWranglerConfig(cfg.rootDir);
-  if (!wranglerConfig) {
-    throw new Error(`no wrangler config found in ${cfg.rootDir} (wrangler.jsonc, wrangler.json, or wrangler.toml)`);
-  }
-  const wranglerEnv = PROD_ENV_NAMES.has(env) ? void 0 : env;
-  const target = wranglerEnv ? `wrangler env "${wranglerEnv}"` : "the top-level (prod) wrangler env";
-  const secrets = [{ name: "ODLA_API_KEY", value: dbKey }];
-  const o11yToken = credentials.envs[env]?.o11yToken;
-  if (o11yToken) secrets.push({ name: "ODLA_O11Y_TOKEN", value: o11yToken });
-  if (options.dryRun) {
-    for (const s of secrets) out.log(`dry run: would push ${s.name} (${redactSecrets(s.value)}) to ${target}`);
-    return;
-  }
-  const run = options.runner ?? defaultRunner;
-  if (!await wranglerLoggedIn(run, cfg.rootDir)) {
-    throw new Error(`wrangler is not logged in \u2014 run "wrangler login" (a browser step for the human)`);
-  }
-  for (const s of secrets) {
-    const result = await wranglerPutSecret(run, { name: s.name, value: s.value, env: wranglerEnv, cwd: cfg.rootDir });
-    if (result.code !== 0) {
-      throw new Error(`wrangler secret put ${s.name} failed (exit ${result.code}): ${redactSecrets(`${result.stderr || result.stdout}`.trim())}`);
+// src/skill.ts
+var import_node_fs6 = require("fs");
+var import_node_os = require("os");
+var import_node_path6 = require("path");
+var import_node_url2 = require("url");
+
+// src/skill-adapters.ts
+var PROJECT_INSTRUCTIONS = `<!-- odla-ai agent setup:start -->
+## odla agent workflow
+
+For work that creates an odla app or adds odla services, read and follow
+\`.agents/skills/odla/SKILL.md\`. It dispatches an existing static site to
+\`.agents/skills/odla-migrate/SKILL.md\`. For production telemetry triage, use
+\`.agents/skills/odla-o11y-debug/SKILL.md\`.
+
+The complete runbooks and their references are installed in this repository.
+Do not fetch online odla documentation as setup context. Network access is only
+needed when a runbook deliberately calls the odla service, npm, Cloudflare, or
+another configured provider.
+<!-- odla-ai agent setup:end -->`;
+var CURSOR_RULE = `---
+description: Build, migrate, provision, secure, or debug an odla app using the locally installed odla runbooks
+globs:
+alwaysApply: false
+---
+
+${PROJECT_INSTRUCTIONS}
+`;
+function claudeAdapter(skill, canonical) {
+  const match = canonical.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) throw new Error(`bundled skill ${skill} has no YAML frontmatter`);
+  const lines = match[1].split(/\r?\n/);
+  const frontmatter = [];
+  let keepIndented = false;
+  for (const line of lines) {
+    if (line.startsWith("name:") || line.startsWith("description:")) {
+      frontmatter.push(line);
+      keepIndented = line.startsWith("description:");
+    } else if (keepIndented && /^\s+/.test(line)) {
+      frontmatter.push(line);
+    } else {
+      keepIndented = false;
     }
-    out.log(`${s.name} pushed to ${target} (value read from ${credentialsPath}, never echoed)`);
   }
+  return `---
+${frontmatter.join("\n")}
+---
+
+# ${skill} (odla adapter)
+
+Read \`../../../.agents/skills/${skill}/SKILL.md\` completely and follow it. That
+canonical local skill owns every reference path and contains the full offline
+runbook. Do not substitute a remote documentation page for the installed copy.
+`;
 }
 
 // src/skill.ts
-var import_node_fs6 = require("fs");
-var import_node_os = require("os");
-var import_node_path7 = require("path");
-var import_node_url2 = require("url");
+var AGENT_HARNESSES = ["claude", "codex", "cursor", "copilot", "gemini", "agents"];
 function installSkill(options = {}) {
   const out = options.stdout ?? console;
   const sourceDir = options.sourceDir ?? (0, import_node_url2.fileURLToPath)(new URL("../skills", importMetaUrl));
-  const targetDir = options.global ? (0, import_node_path7.join)(options.homeDir ?? (0, import_node_os.homedir)(), ".claude", "skills") : (0, import_node_path7.resolve)(options.dir ?? process.cwd(), ".claude", "skills");
   const files = listFiles(sourceDir);
   if (files.length === 0) throw new Error(`no bundled skills found at ${sourceDir}`);
-  const written = [];
-  const unchanged = [];
-  const conflicts = [];
-  for (const rel of files) {
-    const target = (0, import_node_path7.join)(targetDir, rel);
-    const source = (0, import_node_fs6.readFileSync)((0, import_node_path7.join)(sourceDir, rel), "utf8");
-    if ((0, import_node_fs6.existsSync)(target)) {
-      const current = (0, import_node_fs6.readFileSync)(target, "utf8");
-      if (current === source) {
-        unchanged.push(rel);
-        continue;
-      }
-      if (!options.force) {
-        conflicts.push(rel);
-        continue;
+  const harnesses = normalizeHarnesses(options.harnesses, options.global === true);
+  const root = (0, import_node_path6.resolve)(options.dir ?? process.cwd());
+  const home = (0, import_node_path6.resolve)(options.homeDir ?? (0, import_node_os.homedir)());
+  const plans = /* @__PURE__ */ new Map();
+  const targets = /* @__PURE__ */ new Map();
+  const rememberTarget = (harness, target) => {
+    const current = targets.get(harness) ?? /* @__PURE__ */ new Set();
+    current.add(target);
+    targets.set(harness, current);
+  };
+  const plan = (target, content, managedMerge = false, boundary = root) => {
+    const existing = plans.get(target);
+    if (existing && existing.content !== content) throw new Error(`internal agent setup conflict for ${target}`);
+    plans.set(target, { target, content, boundary, managedMerge });
+  };
+  const planSkillTree = (targetDir2, boundary = root) => {
+    for (const rel of files) plan((0, import_node_path6.join)(targetDir2, rel), (0, import_node_fs6.readFileSync)((0, import_node_path6.join)(sourceDir, rel), "utf8"), false, boundary);
+  };
+  let targetDir;
+  if (options.global) {
+    const claudeRoot = (0, import_node_path6.join)(home, ".claude", "skills");
+    const codexRoot = (0, import_node_path6.resolve)(options.codexHomeDir ?? process.env.CODEX_HOME ?? (0, import_node_path6.join)(home, ".codex"), "skills");
+    targetDir = harnesses[0] === "codex" ? codexRoot : claudeRoot;
+    for (const harness of harnesses) {
+      const skillRoot = harness === "claude" ? claudeRoot : codexRoot;
+      planSkillTree(skillRoot, harness === "claude" ? home : (0, import_node_path6.dirname)((0, import_node_path6.dirname)(codexRoot)));
+      rememberTarget(harness, skillRoot);
+    }
+  } else {
+    const sharedRoot = (0, import_node_path6.join)(root, ".agents", "skills");
+    planSkillTree(sharedRoot);
+    const claudeRoot = (0, import_node_path6.join)(root, ".claude", "skills");
+    targetDir = harnesses.includes("claude") ? claudeRoot : sharedRoot;
+    for (const harness of harnesses) rememberTarget(harness, sharedRoot);
+    if (harnesses.includes("claude")) {
+      for (const skill of skillNames(files)) {
+        const canonical = (0, import_node_fs6.readFileSync)((0, import_node_path6.join)(sourceDir, skill, "SKILL.md"), "utf8");
+        plan((0, import_node_path6.join)(claudeRoot, skill, "SKILL.md"), claudeAdapter(skill, canonical));
       }
+      rememberTarget("claude", claudeRoot);
+    }
+    if (harnesses.includes("cursor")) {
+      const cursorRule = (0, import_node_path6.join)(root, ".cursor", "rules", "odla.mdc");
+      plan(cursorRule, CURSOR_RULE);
+      rememberTarget("cursor", cursorRule);
+    }
+    if (harnesses.includes("agents")) {
+      const agentsFile = (0, import_node_path6.join)(root, "AGENTS.md");
+      plan(agentsFile, managedFileContent(agentsFile, PROJECT_INSTRUCTIONS, options.force === true, root), true);
+      rememberTarget("agents", agentsFile);
+    }
+    if (harnesses.includes("copilot")) {
+      const copilotFile = (0, import_node_path6.join)(root, ".github", "copilot-instructions.md");
+      plan(copilotFile, managedFileContent(copilotFile, PROJECT_INSTRUCTIONS, options.force === true, root), true);
+      rememberTarget("copilot", copilotFile);
+    }
+    if (harnesses.includes("gemini")) {
+      const geminiFile = (0, import_node_path6.join)(root, "GEMINI.md");
+      plan(geminiFile, managedFileContent(geminiFile, PROJECT_INSTRUCTIONS, options.force === true, root), true);
+      rememberTarget("gemini", geminiFile);
+    }
+  }
+  const writtenPaths = /* @__PURE__ */ new Set();
+  const unchangedPaths = /* @__PURE__ */ new Set();
+  const conflicts = [];
+  for (const file of plans.values()) {
+    const symlink = symlinkedComponent(file.boundary, file.target);
+    if (symlink) {
+      conflicts.push(`${file.target} (redirected by symbolic link ${symlink})`);
+      continue;
+    }
+    if (!(0, import_node_fs6.existsSync)(file.target)) {
+      writtenPaths.add(file.target);
+      continue;
+    }
+    const current = (0, import_node_fs6.readFileSync)(file.target, "utf8");
+    if (current === file.content) {
+      unchangedPaths.add(file.target);
+    } else if (file.managedMerge || options.force) {
+      writtenPaths.add(file.target);
+      unchangedPaths.delete(file.target);
+    } else {
+      conflicts.push(file.target);
     }
-    written.push(rel);
   }
   if (conflicts.length > 0) {
     throw new Error(
-      `skill files modified locally (re-run with --force to overwrite):
-${conflicts.map((f) => `  - ${(0, import_node_path7.join)(targetDir, f)}`).join("\n")}`
+      `agent setup files modified locally (re-run with --force to replace only odla-managed content):
+${conflicts.map((f) => `  - ${f}`).join("\n")}`
     );
   }
-  for (const rel of written) {
-    const target = (0, import_node_path7.join)(targetDir, rel);
-    (0, import_node_fs6.mkdirSync)((0, import_node_path7.join)(target, ".."), { recursive: true });
-    (0, import_node_fs6.writeFileSync)(target, (0, import_node_fs6.readFileSync)((0, import_node_path7.join)(sourceDir, rel), "utf8"));
+  for (const file of plans.values()) {
+    if (!(0, import_node_fs6.existsSync)(file.target) || (0, import_node_fs6.readFileSync)(file.target, "utf8") !== file.content) {
+      (0, import_node_fs6.mkdirSync)((0, import_node_path6.dirname)(file.target), { recursive: true });
+      (0, import_node_fs6.writeFileSync)(file.target, file.content);
+    }
+  }
+  const skills = skillNames(files);
+  const installations = harnesses.map((harness) => ({ harness, targets: [...targets.get(harness) ?? []] }));
+  out.log(`agent harnesses: ${harnesses.join(", ")}`);
+  out.log(`offline skills: ${skills.join(", ")}`);
+  for (const installation of installations) out.log(`${installation.harness}: ${installation.targets.join(", ")}`);
+  out.log(`installed ${writtenPaths.size} managed file(s)${unchangedPaths.size ? ` (${unchangedPaths.size} unchanged)` : ""}`);
+  return {
+    targetDir,
+    written: pathsUnder(targetDir, writtenPaths),
+    unchanged: pathsUnder(targetDir, unchangedPaths),
+    writtenPaths: [...writtenPaths].sort(),
+    unchangedPaths: [...unchangedPaths].sort(),
+    harnesses: installations
+  };
+}
+function pathsUnder(root, paths) {
+  return [...paths].map((path) => (0, import_node_path6.relative)(root, path)).filter((path) => path !== ".." && !path.startsWith(`..${import_node_path6.sep}`) && !(0, import_node_path6.isAbsolute)(path)).sort();
+}
+function normalizeHarnesses(values, global) {
+  const requested = values?.length ? values : ["claude"];
+  const allowed = /* @__PURE__ */ new Set([...AGENT_HARNESSES, "all"]);
+  for (const harness of requested) {
+    if (!allowed.has(harness)) {
+      throw new Error(`unknown agent harness "${harness}"; choose all, ${AGENT_HARNESSES.join(", ")}`);
+    }
+  }
+  const expanded = requested.includes("all") ? global ? ["claude", "codex"] : [...AGENT_HARNESSES] : [...new Set(requested)];
+  if (global) {
+    const unsupported = expanded.filter((harness) => harness !== "claude" && harness !== "codex");
+    if (unsupported.length) {
+      throw new Error(`--global supports claude and codex only; ${unsupported.join(", ")} require a project-local adapter`);
+    }
+  }
+  return expanded;
+}
+function managedFileContent(path, block, force, boundary) {
+  const symlink = symlinkedComponent(boundary, path);
+  if (symlink) throw new Error(`refusing to manage ${path}: symbolic link component ${symlink}`);
+  if (!(0, import_node_fs6.existsSync)(path)) return `${block}
+`;
+  const current = (0, import_node_fs6.readFileSync)(path, "utf8");
+  const start = "<!-- odla-ai agent setup:start -->";
+  const end = "<!-- odla-ai agent setup:end -->";
+  const startAt = current.indexOf(start);
+  const endAt = current.indexOf(end);
+  if (startAt === -1 !== (endAt === -1) || startAt !== -1 && endAt < startAt) {
+    throw new Error(`malformed odla-managed section in ${path}`);
+  }
+  if (startAt === -1) {
+    const separator = current.length === 0 || current.endsWith("\n\n") ? "" : current.endsWith("\n") ? "\n" : "\n\n";
+    return `${current}${separator}${block}
+`;
+  }
+  const afterEnd = endAt + end.length;
+  const existing = current.slice(startAt, afterEnd);
+  if (existing !== block && !force) {
+    throw new Error(`odla-managed section modified locally in ${path}; re-run with --force to replace that section`);
+  }
+  return `${current.slice(0, startAt)}${block}${current.slice(afterEnd)}`;
+}
+function symlinkedComponent(boundary, target) {
+  const rel = (0, import_node_path6.relative)(boundary, target);
+  if (rel === ".." || rel.startsWith(`..${import_node_path6.sep}`) || (0, import_node_path6.isAbsolute)(rel)) {
+    throw new Error(`agent setup target escapes its install root: ${target}`);
   }
-  const skills = [...new Set(files.map((f) => f.split(/[\\/]/)[0]))].sort();
-  out.log(`skills: ${skills.join(", ")}`);
-  out.log(`installed ${written.length} file(s) to ${targetDir}${unchanged.length ? ` (${unchanged.length} unchanged)` : ""}`);
-  return { targetDir, written, unchanged };
+  let current = boundary;
+  for (const part of rel.split(import_node_path6.sep).filter(Boolean)) {
+    current = (0, import_node_path6.join)(current, part);
+    try {
+      if ((0, import_node_fs6.lstatSync)(current).isSymbolicLink()) return current;
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+  return void 0;
+}
+function skillNames(files) {
+  return [...new Set(files.filter((file) => /(^|[\\/])SKILL\.md$/.test(file)).map((file) => file.split(/[\\/]/)[0]))].sort();
 }
 function listFiles(dir) {
   if (!(0, import_node_fs6.existsSync)(dir)) return [];
   const results = [];
   const walk = (current) => {
     for (const entry of (0, import_node_fs6.readdirSync)(current, { withFileTypes: true })) {
-      const path = (0, import_node_path7.join)(current, entry.name);
+      const path = (0, import_node_path6.join)(current, entry.name);
       if (entry.isDirectory()) walk(path);
-      else results.push((0, import_node_path7.relative)(dir, path));
+      else results.push((0, import_node_path6.relative)(dir, path));
     }
   };
   walk(dir);
@@ -1004,7 +1443,7 @@ async function getJson(doFetch, url, bearer) {
   const res = await doFetch(url, {
     headers: bearer ? { authorization: `Bearer ${bearer}` } : void 0
   });
-  if (!res.ok) throw new Error(`${new URL(url).pathname} returned ${res.status}: ${await safeText2(res)}`);
+  if (!res.ok) throw new Error(`${new URL(url).pathname} returned ${res.status}: ${await safeText3(res)}`);
   return res.json();
 }
 async function postJson2(doFetch, url, bearer, body) {
@@ -1013,7 +1452,7 @@ async function postJson2(doFetch, url, bearer, body) {
     headers: { authorization: `Bearer ${bearer}`, "content-type": "application/json" },
     body: JSON.stringify(body)
   });
-  if (!res.ok) throw new Error(`${new URL(url).pathname} returned ${res.status}: ${await safeText2(res)}`);
+  if (!res.ok) throw new Error(`${new URL(url).pathname} returned ${res.status}: ${await safeText3(res)}`);
   return res.json();
 }
 function publicConfigUrl(platformUrl, appId, env) {
@@ -1021,7 +1460,7 @@ function publicConfigUrl(platformUrl, appId, env) {
   url.searchParams.set("env", env);
   return url.toString();
 }
-async function safeText2(res) {
+async function safeText3(res) {
   try {
     return (await res.text()).slice(0, 500);
   } catch {
@@ -1034,14 +1473,17 @@ async function runCli(argv = process.argv.slice(2)) {
   const parsed = parseArgv(argv);
   const command = parsed.positionals[0] ?? "help";
   if (command === "version" || command === "-v" || parsed.options.version === true) {
+    assertArgs(parsed, ["version"], 1);
     console.log(cliVersion());
     return;
   }
   if (command === "help" || command === "--help" || command === "-h") {
+    assertArgs(parsed, ["help"], 1);
     printHelp();
     return;
   }
   if (command === "init") {
+    assertArgs(parsed, ["app-id", "name", "config", "env", "services", "ai-provider", "force"], 1);
     initProject({
       appId: requiredString(parsed.options["app-id"], "--app-id"),
       name: requiredString(parsed.options.name, "--name"),
@@ -1054,15 +1496,39 @@ async function runCli(argv = process.argv.slice(2)) {
     return;
   }
   if (command === "doctor") {
+    assertArgs(parsed, ["config"], 1);
     await doctor({ configPath: stringOpt(parsed.options.config) ?? "odla.config.mjs" });
     return;
   }
+  if (command === "capabilities") {
+    assertArgs(parsed, ["json"], 1);
+    printCapabilities(parsed.options.json === true);
+    return;
+  }
   if (command === "provision") {
+    assertArgs(
+      parsed,
+      [
+        "config",
+        "dry-run",
+        "rotate-keys",
+        "rotate-o11y-token",
+        "push-secrets",
+        "write-credentials",
+        "write-dev-vars",
+        "token",
+        "open",
+        "yes"
+      ],
+      1
+    );
     const writeDevVars2 = parsed.options["write-dev-vars"];
     const opts = {
       configPath: stringOpt(parsed.options.config) ?? "odla.config.mjs",
       dryRun: parsed.options["dry-run"] === true,
       rotateKeys: parsed.options["rotate-keys"] === true,
+      rotateO11yToken: parsed.options["rotate-o11y-token"] === true,
+      pushSecrets: parsed.options["push-secrets"] === true,
       writeCredentials: parsed.options["write-credentials"] !== false,
       writeDevVars: typeof writeDevVars2 === "string" ? writeDevVars2 : writeDevVars2 === true,
       token: stringOpt(parsed.options.token),
@@ -1073,18 +1539,34 @@ async function runCli(argv = process.argv.slice(2)) {
     return;
   }
   if (command === "smoke") {
+    assertArgs(parsed, ["config", "env"], 1);
     await smoke({
       configPath: stringOpt(parsed.options.config) ?? "odla.config.mjs",
       env: stringOpt(parsed.options.env)
     });
     return;
   }
+  if (command === "setup") {
+    assertArgs(parsed, ["dir", "global", "force", "agent", "harness"], 1);
+    installSkill({
+      dir: stringOpt(parsed.options.dir),
+      global: parsed.options.global === true,
+      harnesses: harnessList(parsed),
+      force: parsed.options.force === true
+    });
+    console.log(
+      "\nOffline runbooks installed. Open this repo in your coding agent and ask it to set up odla.\nIts native adapter finds the local `odla` skill, chooses build or migration, and drives the CLI."
+    );
+    return;
+  }
   if (command === "skill") {
     const sub = parsed.positionals[1];
     if (sub !== "install") throw new Error(`unknown skill subcommand "${sub ?? ""}". Try "odla-ai skill install".`);
+    assertArgs(parsed, ["dir", "global", "force", "agent", "harness"], 2);
     installSkill({
       dir: stringOpt(parsed.options.dir),
       global: parsed.options.global === true,
+      harnesses: harnessList(parsed),
       force: parsed.options.force === true
     });
     return;
@@ -1092,6 +1574,7 @@ async function runCli(argv = process.argv.slice(2)) {
   if (command === "secrets") {
     const sub = parsed.positionals[1];
     if (sub !== "push") throw new Error(`unknown secrets subcommand "${sub ?? ""}". Try "odla-ai secrets push --env dev".`);
+    assertArgs(parsed, ["config", "env", "dry-run", "yes"], 2);
     await secretsPush({
       configPath: stringOpt(parsed.options.config) ?? "odla.config.mjs",
       env: requiredString(parsed.options.env, "--env"),
@@ -1102,6 +1585,17 @@ async function runCli(argv = process.argv.slice(2)) {
   }
   throw new Error(`unknown command "${command}". Run "odla-ai help".`);
 }
+function assertArgs(parsed, allowedOptions, maxPositionals) {
+  const allowed = new Set(allowedOptions);
+  for (const name of Object.keys(parsed.options)) {
+    if (!allowed.has(name)) {
+      throw new Error(`unknown option "--${name}"; run "odla-ai help" for supported options`);
+    }
+  }
+  if (parsed.positionals.length > maxPositionals) {
+    throw new Error(`unexpected argument "${parsed.positionals[maxPositionals]}"; run "odla-ai help"`);
+  }
+}
 function parseArgv(argv) {
   const positionals = [];
   const options = {};
@@ -1157,6 +1651,21 @@ function listOpt(value) {
   const values = Array.isArray(value) ? value : [value];
   return values.flatMap((item) => item.split(",")).map((item) => item.trim()).filter(Boolean);
 }
+function harnessList(parsed) {
+  const selected = [
+    ...harnessOption(parsed.options.agent, "--agent"),
+    ...harnessOption(parsed.options.harness, "--harness")
+  ];
+  return selected.length ? selected : ["all"];
+}
+function harnessOption(value, flag) {
+  if (value === void 0) return [];
+  if (typeof value === "boolean") throw new Error(`${flag} requires a harness name`);
+  const raw = Array.isArray(value) ? value : [value];
+  const parts = raw.flatMap((item) => item.split(","));
+  if (parts.some((item) => !item.trim())) throw new Error(`${flag} requires a harness name`);
+  return parts.map((item) => item.trim());
+}
 function cliVersion() {
   const pkg = JSON.parse((0, import_node_fs7.readFileSync)(new URL("../package.json", importMetaUrl), "utf8"));
   return pkg.version ?? "unknown";
@@ -1165,26 +1674,34 @@ function printHelp() {
   console.log(`odla-ai
 
 Usage:
-  odla-ai init --app-id <id> --name <name> [--services db,ai] [--env dev --env prod]
+  odla-ai setup [--dir <project>] [--agent <name>] [--global] [--force]
+  odla-ai init --app-id <id> --name <name> [--services db,ai,o11y] [--env dev --env prod]
   odla-ai doctor [--config odla.config.mjs]
-  odla-ai provision [--config odla.config.mjs] [--dry-run] [--open|--no-open] [--rotate-keys] [--write-dev-vars[=path]]
+  odla-ai capabilities [--json]
+  odla-ai provision [--config odla.config.mjs] [--dry-run] [--push-secrets] [--rotate-o11y-token] [--write-dev-vars[=path]] [--yes]
   odla-ai smoke [--config odla.config.mjs] [--env dev]
-  odla-ai skill install [--dir <project>] [--global] [--force]
+  odla-ai skill install [--dir <project>] [--agent <name>] [--global] [--force]
   odla-ai secrets push --env <env> [--config odla.config.mjs] [--dry-run] [--yes]
   odla-ai version
 
 Commands:
+  setup       Install offline odla runbooks for common coding-agent harnesses.
   init        Create a generic odla.config.mjs plus starter schema/rules files.
   doctor      Validate and summarize the project config without network calls.
-  provision   Register the app, enable services, push schema/rules, configure AI/auth.
+  capabilities Show what the CLI automates vs agent edits and human checkpoints.
+  provision   Register services, configure them, persist credentials, optionally push secrets.
   smoke       Verify local credentials, public-config, live schema, and db aggregate.
-  skill       Install the bundled Claude Code skills into .claude/skills/.
-  secrets     Push the env's db key into the Worker via wrangler, stdin-piped.
+  skill       Same installer; --agent accepts all, claude, codex, cursor,
+              copilot, gemini, or agents (repeatable or comma-separated).
+  secrets     Push configured db/o11y secrets into the Worker via wrangler stdin.
   version     Print the CLI version.
 
 Safety:
-  Provision caches the approved developer token and local db keys under .odla/
-  with mode 0600, and init adds those paths to .gitignore.
+  New projects target dev only. Add prod explicitly to odla.config.mjs and pass
+  --yes to provision it; use --dry-run first to inspect the resolved plan.
+  Provision caches the approved developer token and service credentials under
+  .odla/ with mode 0600, and init adds those paths to .gitignore. Secret push
+  preflights Wrangler before any shown-once issuance or destructive rotation.
   Provision opens the approval page automatically in interactive terminals;
   use --open to force browser launch or --no-open to suppress it.
 `);