@cybernetyx1/atlasflow-cli 0.1.0 → 0.1.2

package/README.md

@@ -5,7 +5,7 @@ The `atlasflow` command-line tool for scaffolding, running, building, testing, a
 ## Install
 
 ```sh
-pnpm add @cybernetyx1/atlasflow-cli
+npm install @cybernetyx1/atlasflow-cli
 ```
 
 Part of the AtlasFlow monorepo. Proprietary.
@@ -15,9 +15,9 @@ Part of the AtlasFlow monorepo. Proprietary.
 Scaffold a workspace and run it locally:
 
 ```sh
-atlasflow init          # scaffold a new agent workspace
-pnpm install
-atlasflow dev --console # watch + serve locally with an operator console
+npx atlasflow init      # scaffold a new agent workspace
+npm install
+npx atlasflow dev --console # watch + serve locally with an operator console
 ```
 
 Commands:

package/dist/index.d.ts

@@ -12,5 +12,6 @@ declare function defineConfig(config: UserAtlasFlowConfig): UserAtlasFlowConfig;
 /** @cybernetyx1/atlasflow-cli — entrypoint and arg parsing. */
 
 declare function main(argv: string[]): Promise<void>;
+declare function assertSupportedNode(version: string): void;
 
-export { type UserAtlasFlowConfig, defineConfig, main };
+export { type UserAtlasFlowConfig, assertSupportedNode, defineConfig, main };

package/dist/index.js

@@ -1942,7 +1942,7 @@ async function bundle(opts) {
     platform: "node",
     target: "node22",
     packages: "external",
-    sourcemap: true,
+    sourcemap: false,
     logLevel: "silent",
     plugins: [skillPlugin(opts.projectRoot ?? opts.resolveDir)],
     ...opts.cjsPathPolyfill ? { banner: { js: 'var __filename = "/worker.mjs"; var __dirname = "/";' } } : {}
@@ -3072,7 +3072,11 @@ async function infoCommand(args) {
       } else {
         process.stdout.write(formatAgentFolderCheck(ws.agentFolder, check, { diff: includeDiff }));
       }
-      if (!check.ok) throw new Error(`atlasflow info --check failed: ${check.items.filter((item) => item.status !== "current").map((item) => `${item.name} ${item.status}`).join(", ")}`);
+      if (!check.ok) {
+        throw new Error(
+          `atlasflow info --check failed: ${check.items.filter((item) => item.status !== "current").map((item) => `${item.name} ${item.status}`).join(", ")}. Next: run atlasflow info to regenerate .atlasflow artifacts, then rerun atlasflow info --check.`
+        );
+      }
       return;
     }
     const artifacts = writeAgentFolderArtifacts(ws.agentFolder);
@@ -3085,6 +3089,82 @@ async function infoCommand(args) {
   }
   requireAgentFolderWorkspace(ws, root);
 }
+async function doctorCommand(args) {
+  const config = await resolveCliConfig(args);
+  const root = config.root;
+  loadEnv(root);
+  const checks = [];
+  const pkg = readProjectPackageJson(root);
+  const packageManager = detectPackageManager(root, pkg.manifest);
+  checks.push({
+    name: "Node.js",
+    ok: nodeMajor(process.versions.node) >= 22,
+    detail: `current ${process.versions.node}`,
+    next: "Install Node.js 22 or newer, then rerun atlasflow doctor."
+  });
+  checks.push({
+    name: "Project package.json",
+    ok: Boolean(pkg.manifest),
+    detail: pkg.error ?? (pkg.manifest ? "found" : "missing"),
+    next: "Run atlasflow init, or run atlasflow doctor from the project root."
+  });
+  checks.push({
+    name: "Package manager",
+    ok: Boolean(packageManager.kind),
+    detail: packageManager.detail,
+    next: "Run npm install to create package-lock.json, or use the package manager already chosen by this project."
+  });
+  const dependencyCheck = checkAtlasFlowDependencies(root, pkg.manifest);
+  checks.push(dependencyCheck);
+  let agent;
+  try {
+    const ws = loadWorkspace(root);
+    agent = ws.agentFolder;
+    checks.push({
+      name: "Agent folder",
+      ok: Boolean(agent),
+      detail: agent ? `found agent/${path5.basename(agent.configFile ?? "agent.jsonc")} (${agent.name})` : "missing agent/agent.jsonc",
+      next: "Run atlasflow init, or add agent/agent.jsonc plus agent/identity/profile.md."
+    });
+  } catch (err) {
+    checks.push({
+      name: "Agent folder",
+      ok: false,
+      detail: err instanceof Error ? err.message : String(err),
+      next: "Fix agent/agent.jsonc and agent/identity/, then rerun atlasflow doctor."
+    });
+  }
+  if (agent) {
+    const modelKey = modelSecretEnvName(agent.manifest.model);
+    checks.push({
+      name: "Model key",
+      ok: !modelKey || Boolean(process.env[modelKey]),
+      detail: modelKey ? `${modelKey}${process.env[modelKey] ? " is set" : " is not set"}` : `model ${agent.manifest.model} does not require a local provider key`,
+      next: modelKey ? `Set ${modelKey} in .env or the deployment secret store.` : ""
+    });
+    const artifactCheck = checkAgentFolderArtifacts(agent);
+    checks.push({
+      name: "Generated artifacts",
+      ok: artifactCheck.ok,
+      detail: artifactCheck.ok ? ".atlasflow artifacts are current" : artifactCheck.items.filter((item) => item.status !== "current").map((item) => `${item.name} ${item.status}`).join(", "),
+      next: "Run atlasflow info to generate .atlasflow artifacts, then rerun atlasflow doctor."
+    });
+  }
+  const failed = checks.filter((check) => !check.ok);
+  if (args.json === true) {
+    console.log(JSON.stringify({ ok: failed.length === 0, root, checks }, null, 2));
+    if (failed.length) process.exitCode = 1;
+    return;
+  }
+  const lines = [`AtlasFlow doctor (${root})`];
+  for (const check of checks) {
+    lines.push(`${check.ok ? "PASS" : "FAIL"} ${check.name}: ${check.detail}`);
+    if (!check.ok) lines.push(`  Next: ${check.next}`);
+  }
+  lines.push(failed.length ? `Status: ${failed.length} issue${failed.length === 1 ? "" : "s"} found.` : "Status: all checks passed.");
+  console.log(lines.join("\n"));
+  if (failed.length) process.exitCode = 1;
+}
 function agentFolderInfoJson(agent, artifacts, target) {
   return {
     atlasflow: 1,
@@ -3195,6 +3275,78 @@ function stableLines(value) {
   const trimmed = normalized.endsWith("\n") ? normalized.slice(0, -1) : normalized;
   return trimmed ? trimmed.split("\n") : [];
 }
+function nodeMajor(version) {
+  const major = Number(version.split(".")[0]);
+  return Number.isFinite(major) ? major : 0;
+}
+function readProjectPackageJson(root) {
+  const file = path5.join(root, "package.json");
+  if (!fs5.existsSync(file)) return {};
+  try {
+    const parsed = JSON.parse(fs5.readFileSync(file, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { error: "package.json must contain an object" };
+    return { manifest: parsed };
+  } catch (err) {
+    return { error: `invalid package.json (${err instanceof Error ? err.message : String(err)})` };
+  }
+}
+function detectPackageManager(root, manifest) {
+  if (fs5.existsSync(path5.join(root, "pnpm-lock.yaml"))) return { kind: "pnpm", detail: "pnpm-lock.yaml found" };
+  if (fs5.existsSync(path5.join(root, "package-lock.json"))) return { kind: "npm", detail: "package-lock.json found" };
+  if (fs5.existsSync(path5.join(root, "yarn.lock"))) return { kind: "yarn", detail: "yarn.lock found" };
+  const packageManager = typeof manifest?.packageManager === "string" ? manifest.packageManager : void 0;
+  if (packageManager?.startsWith("pnpm@")) return { kind: "pnpm", detail: `packageManager=${packageManager}; lockfile missing` };
+  if (packageManager?.startsWith("npm@")) return { kind: "npm", detail: `packageManager=${packageManager}; lockfile missing` };
+  if (packageManager?.startsWith("yarn@")) return { kind: "yarn", detail: `packageManager=${packageManager}; lockfile missing` };
+  return { detail: "no package lockfile found" };
+}
+function checkAtlasFlowDependencies(root, manifest) {
+  if (!manifest) {
+    return {
+      name: "AtlasFlow dependencies",
+      ok: false,
+      detail: "package.json missing",
+      next: "Run atlasflow init."
+    };
+  }
+  const deps = projectDependencyMap(manifest);
+  const required = [atlasflowPackageName("cli"), atlasflowPackageName("runtime")];
+  const missing = required.filter((name) => !deps.has(name));
+  if (missing.length) {
+    return {
+      name: "AtlasFlow dependencies",
+      ok: false,
+      detail: `missing ${missing.join(", ")}`,
+      next: "Run atlasflow init to merge the missing dependencies into package.json, then run npm install."
+    };
+  }
+  const unlinked = required.filter((name) => !fs5.existsSync(path5.join(root, "node_modules", ...name.split("/"))));
+  if (unlinked.length) {
+    return {
+      name: "AtlasFlow dependencies",
+      ok: false,
+      detail: `not installed ${unlinked.join(", ")}`,
+      next: "Run npm install, then rerun atlasflow doctor."
+    };
+  }
+  return {
+    name: "AtlasFlow dependencies",
+    ok: true,
+    detail: `${required.join(", ")} installed`,
+    next: ""
+  };
+}
+function projectDependencyMap(manifest) {
+  const out = /* @__PURE__ */ new Map();
+  for (const section of ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"]) {
+    const deps = manifest[section];
+    if (!deps || typeof deps !== "object" || Array.isArray(deps)) continue;
+    for (const [name, range] of Object.entries(deps)) {
+      if (typeof range === "string") out.set(name, range);
+    }
+  }
+  return out;
+}
 var AGENT_BUNDLE_ROOT = "agent";
 var AGENT_BUNDLE_EXCLUDED_DIRECTORIES = /* @__PURE__ */ new Set([".cache", ".git", ".turbo", ".wrangler", "dist", "node_modules"]);
 var AGENT_BUNDLE_EXCLUDED_FILES = /* @__PURE__ */ new Set([".ds_store"]);
@@ -3443,7 +3595,7 @@ function runProcess(command, args, cwd, label) {
     child.on("error", (err) => {
       const code = err.code;
       if (code === "ENOENT") {
-        reject(new Error(`Could not find ${command}. Run pnpm install in this workspace, install Wrangler, or pass --wrangler <path>.`));
+        reject(new Error(`Could not find ${command}. Run ${suggestedInstallCommand(cwd)}, install Wrangler, or pass --wrangler <path>.`));
         return;
       }
       reject(err);
@@ -4725,15 +4877,17 @@ async function connectCommand(args) {
 var DOCS = {
   quickstart: `Quickstart
 
-  atlasflow init
-  pnpm install
+  npm exec --yes --package @cybernetyx1/atlasflow-cli -- atlasflow init
+  npm install
   cp .env.example .env
   # set ANTHROPIC_API_KEY in .env
-  atlasflow info
-  atlasflow run --message "hi"
-  atlasflow connect
-  atlasflow dev --console
-  curl -X POST localhost:4577/runs/hello -H 'content-type: application/json' -d '{"message":"hi"}'`,
+  npx atlasflow info
+  npx atlasflow run --message "hi"
+  npx atlasflow connect
+  npx atlasflow dev --console
+  curl -X POST localhost:4577/runs/hello -H 'content-type: application/json' -d '{"message":"hi"}'
+
+Contributors working inside the monorepo use pnpm. New app projects should not need a monorepo checkout or build.`,
   agents: `Authoring agents
 
 The default project has one visible agent/ folder. agent/agent.jsonc stores model
@@ -4762,6 +4916,29 @@ slot path diagnostics, and a prompt preview. Use atlasflow info --json for the
 machine-readable compiled graph, atlasflow info --check in CI to fail when
 generated artifacts are stale, and atlasflow info --check --diff to print a compact
 stale-artifact diff.`,
+  tools: `Custom tools
+
+Put custom tool modules in agent/tools/*.ts. Each module can export one default
+tool, an array of tools, { tools }, or named tool exports. Define the argument
+schema with Valibot so the runtime can validate model-provided inputs before
+execute runs.
+
+agent/tools/add.ts
+
+  import { defineTool } from "@cybernetyx1/atlasflow-runtime";
+  import * as v from "valibot";
+
+  export default defineTool({
+    name: "add",
+    description: "Add two numbers and return their sum.",
+    parameters: v.object({ a: v.number(), b: v.number() }),
+    execute: async ({ a, b }) => String(a + b),
+  });
+
+Keep side effects inside execute and keep credentials outside agent/. For external
+APIs, prefer a connection module plus an allowlist in agent/agent.jsonc so deploy-time
+secrets bind outside the agent source folder. Run atlasflow info to confirm the tool
+was discovered and atlasflow build to prove the module bundles.`,
   browser: `Browser integration
 
 Never put ATLASFLOW_API_KEY in browser code. Keep the master key on your server,
@@ -4863,13 +5040,14 @@ connections fail fast at run time. Never put credentials inside agent/.`,
   channels: `Channels
 
 Put inbound webhook/session adapters in agent/channels/<name>.ts. Channels are
-for ingress: they parse platform webhooks, verify request auth, choose the stable
-continuationToken, and return a dispatch for the deployed agent. Tools and
-connections remain outbound capabilities the model can call. Run atlasflow add
-channel <name> for a bearer-token HTTP channel, or pass --provider github|slack
-for signed webhook templates. Generated templates fail closed in deployed mode
-unless the required token or signing secret is configured; ATLASFLOW_MODE=local
-keeps local development easy.`,
+public ingress routes by design: platform webhooks and app clients call them
+without the server master key. Every deployed channel must verify its own bearer
+token, signature, or provider secret before it dispatches to the agent, otherwise
+anyone can spend your model budget. Tools and connections remain outbound
+capabilities the model can call. Run atlasflow add channel <name> for a bearer-token
+HTTP channel, or pass --provider github|slack for signed webhook templates.
+Generated templates fail closed in deployed mode unless the required token or
+signing secret is configured; ATLASFLOW_MODE=local keeps local development easy.`,
   "rate-limit": `Rate limiting
 
 Built Node and Cloudflare servers enable an in-process rate limit by default for
@@ -4908,10 +5086,34 @@ Use connectMcpServer() for stdio or HTTP MCP servers. In Worker deployments, ope
 MCP connections lazily inside a toolSlots factory and return { tools, cleanup } so
 connections are created per request and closed after the run settles. Use
 atlasflow add mcp <name> to scaffold a lazy connector and bindings stub.`,
+  prompt: `Prompt recipe
+
+agent/agent.jsonc can include prompt.recipe and prompt.contextBudget. The standard
+folder scaffold uses "atlas-brain-default", which assembles identity markdown,
+principles, boundaries, skills, context, memory slots, tools, channels, and other
+folder-discovered loadout into the compiled system prompt. Use contextBudget to
+cap how much discovered context can be included eagerly. Run atlasflow info to
+inspect .atlasflow/compiled-system-prompt.md and use atlasflow info --check in CI
+to catch stale prompt artifacts.`,
   "structured-output": `Structured output
 
-Declare a Valibot result schema in agent/agent.ts to validate model output. For
-schema agents, data is the raw final model text and result is the parsed,
+Declare a Valibot result schema in agent/agent.ts to validate model output.
+
+agent/agent.ts
+
+  import { defineAgent } from "@cybernetyx1/atlasflow-runtime";
+  import * as v from "valibot";
+
+  const Result = v.object({
+    status: v.picklist(["ok", "needs-info"]),
+    answer: v.string(),
+  });
+
+  export default defineAgent({
+    result: Result,
+  });
+
+For schema agents, data is the raw final model text and result is the parsed,
 validated object. Use result for application logic; use data only when you want
 to inspect the original text. atlasflow run --json prints { ok, runId, data,
 result, usage } for piping into tests or automation.`,
@@ -4957,7 +5159,13 @@ Agents and workflows are plain HTTP, so any CI can call a deployed AtlasFlow:
     -H "authorization: Bearer $ATLASFLOW_API_KEY" \\
     -H "content-type: application/json" \\
     -d '{"payload": {"issue": 123}, "wait": true}'
-Use requireApiKey() (ATLASFLOW_API_KEY) to protect the endpoints.`
+Use requireApiKey() (ATLASFLOW_API_KEY) to protect the endpoints.`,
+  skill: `AtlasFlow assistant skill
+
+This repository ships an assistant skill for coding agents working on AtlasFlow apps:
+  npx skills add <repo>/skills/atlasflow
+
+The skill tells the coding agent to read local AtlasFlow docs first, inspect the visible agent/ folder, run atlasflow info before guessing about discovery, and verify package/release work with real install and tarball evidence.`
 };
 async function docsCommand(args) {
   const sub = args._[0];
@@ -6511,6 +6719,8 @@ function uniqueOperationName(base, usedNames) {
 async function initCommand(args) {
   const root = rootOf(args);
   const force = args.force === true;
+  const dryRun = args["dry-run"] === true;
+  const noMerge = args["no-merge"] === true;
   const target = initTargetOf(str2(args, "target") ?? "node");
   const cloudflareRuntime = initCloudflareRuntimeOf(str2(args, "cloudflare-runtime") ?? "worker");
   const configPath = path5.join(root, "atlasflow.config.ts");
@@ -6521,44 +6731,175 @@ async function initCommand(args) {
   const identityDir = path5.join(agentDir, "identity");
   const agentConfigPath = path5.join(agentDir, "agent.jsonc");
   const identityPath = path5.join(identityDir, "profile.md");
-  if (fs5.existsSync(configPath) && !force) throw new Error("atlasflow.config.ts already exists (use --force to overwrite)");
-  if (fs5.existsSync(agentConfigPath) && !force) throw new Error("agent/agent.jsonc already exists (use --force to overwrite)");
-  fs5.mkdirSync(identityDir, { recursive: true });
-  fs5.writeFileSync(
-    configPath,
-    initConfigSource(target, cloudflareRuntime)
-  );
-  fs5.writeFileSync(
-    agentConfigPath,
-    `${JSON.stringify(
-      {
-        $schema: agentConfigSchemaRef(),
-        name: "hello",
-        model: { default: "anthropic/claude-haiku-4-5-20251001" },
-        skills: { loading: "lazy" },
-        prompt: { recipe: "atlas-brain-default" }
-      },
-      null,
-      2
-    )}
-`
-  );
-  fs5.writeFileSync(identityPath, "You are a helpful assistant. Answer concisely.\n");
-  const created = [configPath, agentConfigPath, identityPath];
-  for (const file of [
-    { path: packagePath, contents: initPackageJson(target) },
-    { path: envExamplePath, contents: INIT_ENV_EXAMPLE },
-    { path: gitignorePath, contents: INIT_GITIGNORE }
-  ]) {
-    if (fs5.existsSync(file.path)) continue;
-    fs5.writeFileSync(file.path, file.contents);
-    created.push(file.path);
-  }
-  console.log("Scaffolded:");
-  for (const file of created) console.log(`  ${path5.relative(root, file)}`);
-  console.log("\nNext: copy .env.example to .env, set ANTHROPIC_API_KEY, then `pnpm install && pnpm dev`.");
+  const writes = [];
+  writes.push(planScaffoldWrite(configPath, initConfigSource(target, cloudflareRuntime), force));
+  writes.push({
+    ...planScaffoldWrite(
+      agentConfigPath,
+      `${JSON.stringify(
+        {
+          $schema: agentConfigSchemaRef(),
+          name: "hello",
+          model: { default: "anthropic/claude-haiku-4-5-20251001" },
+          skills: { loading: "lazy" },
+          prompt: { recipe: "atlas-brain-default" }
+        },
+        null,
+        2
+      )}
+`,
+      force
+    )
+  });
+  writes.push(planScaffoldWrite(identityPath, "You are a helpful assistant. Answer concisely.\n", force));
+  writes.push(planPackageJsonWrite(packagePath, target, noMerge));
+  writes.push(planTextBlockWrite(envExamplePath, INIT_ENV_EXAMPLE, "AtlasFlow", initEnvExampleLines(), initEnvKey, noMerge));
+  writes.push(planTextBlockWrite(gitignorePath, INIT_GITIGNORE, "AtlasFlow", INIT_GITIGNORE.split("\n").filter(Boolean), void 0, noMerge));
+  if (!dryRun) {
+    fs5.mkdirSync(identityDir, { recursive: true });
+    for (const write of writes) {
+      if (write.action === "skip") continue;
+      fs5.mkdirSync(path5.dirname(write.file), { recursive: true });
+      fs5.writeFileSync(write.file, write.contents);
+    }
+  }
+  console.log(dryRun ? "Dry run: planned scaffold changes:" : "Scaffolded:");
+  for (const write of writes) {
+    const suffix = write.note ? ` - ${write.note}` : "";
+    console.log(`  ${write.action.padEnd(9)} ${path5.relative(root, write.file)}${suffix}`);
+  }
+  const install = suggestedInstallCommand(root);
+  console.log(`
+Next: copy .env.example to .env, set ANTHROPIC_API_KEY, then \`${install} && atlasflow dev\`.`);
   console.log("Inspect: atlasflow info");
 }
+function planScaffoldWrite(file, contents, force) {
+  if (!fs5.existsSync(file)) return { file, action: "create", contents };
+  if (force) return { file, action: "overwrite", contents };
+  return { file, action: "skip", contents: fs5.readFileSync(file, "utf8"), note: "exists; use --force to overwrite" };
+}
+function planPackageJsonWrite(file, target, noMerge) {
+  const generated = initPackageJsonObject(target);
+  if (!fs5.existsSync(file)) return { file, action: "create", contents: `${JSON.stringify(generated, null, 2)}
+` };
+  if (noMerge) return { file, action: "skip", contents: fs5.readFileSync(file, "utf8"), note: "--no-merge" };
+  const raw = fs5.readFileSync(file, "utf8");
+  const current = parseJsonObject(raw, file);
+  const { manifest, changed, note } = mergeInitPackageJson(current, generated);
+  return { file, action: changed ? "merge" : "skip", contents: `${JSON.stringify(manifest, null, 2)}
+`, note };
+}
+function mergeInitPackageJson(current, generated) {
+  const manifest = { ...current };
+  let changed = false;
+  const preserved = [];
+  for (const [key, value] of Object.entries(generated)) {
+    if (key === "scripts" || key === "dependencies" || key === "devDependencies") continue;
+    if (manifest[key] === void 0) {
+      manifest[key] = value;
+      changed = true;
+    }
+  }
+  const scripts = ensurePlainObject(manifest, "scripts");
+  const generatedScripts = objectEntriesOfStrings(generated.scripts);
+  for (const [name, command] of generatedScripts) {
+    const existing = scripts[name];
+    if (existing === void 0) {
+      scripts[name] = command;
+      changed = true;
+    } else if (existing !== command) {
+      const atlasName = `atlasflow:${name}`;
+      if (scripts[atlasName] === void 0) {
+        scripts[atlasName] = command;
+        changed = true;
+      } else if (scripts[atlasName] !== command) {
+        preserved.push(`scripts.${atlasName}`);
+      }
+    }
+  }
+  const existingDeps = dependencyLocations(manifest);
+  for (const section of ["dependencies", "devDependencies"]) {
+    const target = ensurePlainObject(manifest, section);
+    for (const [name, range] of objectEntriesOfStrings(generated[section])) {
+      if (existingDeps.has(name)) {
+        preserved.push(`${existingDeps.get(name).section}.${name}`);
+        continue;
+      }
+      target[name] = range;
+      existingDeps.set(name, { section, range });
+      changed = true;
+    }
+  }
+  return {
+    manifest,
+    changed,
+    note: preserved.length ? `preserved existing ${[...new Set(preserved)].join(", ")}` : void 0
+  };
+}
+function ensurePlainObject(parent, key) {
+  const current = parent[key];
+  if (current && typeof current === "object" && !Array.isArray(current)) return current;
+  const next = {};
+  parent[key] = next;
+  return next;
+}
+function objectEntriesOfStrings(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return [];
+  return Object.entries(value).filter((entry) => typeof entry[1] === "string");
+}
+function dependencyLocations(manifest) {
+  const out = /* @__PURE__ */ new Map();
+  for (const section of ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"]) {
+    for (const [name, range] of objectEntriesOfStrings(manifest[section])) out.set(name, { section, range });
+  }
+  return out;
+}
+function planTextBlockWrite(file, createContents, label, desiredLines, keyOf, noMerge = false) {
+  if (!fs5.existsSync(file)) return { file, action: "create", contents: createContents };
+  const raw = fs5.readFileSync(file, "utf8");
+  if (noMerge) return { file, action: "skip", contents: raw, note: "--no-merge" };
+  const merged = mergeTextBlock(raw, label, desiredLines, keyOf);
+  return {
+    file,
+    action: merged.changed ? "merge" : "skip",
+    contents: merged.contents,
+    note: merged.added.length ? `added ${merged.added.join(", ")}` : void 0
+  };
+}
+function mergeTextBlock(raw, label, desiredLines, keyOf) {
+  const normalized = raw.replace(/\r\n/g, "\n");
+  const existingLines = new Set(normalized.split("\n").map((line) => line.trim()));
+  const existingKeys = new Set(normalized.split("\n").map((line) => keyOf?.(line.trim())).filter((key) => Boolean(key)));
+  const missing = desiredLines.filter((line) => {
+    const key = keyOf?.(line);
+    if (key) return !existingKeys.has(key);
+    return line.trim() && !existingLines.has(line.trim());
+  });
+  if (!missing.length) return { contents: raw, changed: false, added: [] };
+  const prefix = normalized.endsWith("\n") || normalized.length === 0 ? "" : "\n";
+  const block = [`# ${label}`, ...missing, ""].join("\n");
+  return { contents: `${normalized}${prefix}${block}`, changed: true, added: missing.map((line) => keyOf?.(line) ?? line) };
+}
+function initEnvExampleLines() {
+  return INIT_ENV_EXAMPLE.split("\n").filter((line) => {
+    const trimmed = line.trim();
+    return trimmed && trimmed !== "# Copy this file to .env for local development.";
+  });
+}
+function initEnvKey(line) {
+  const match = line.match(/^\s*#?\s*([A-Z][A-Z0-9_]+)=/);
+  return match?.[1];
+}
+function parseJsonObject(raw, file) {
+  const parsed = JSON.parse(raw);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`Invalid JSON object: ${file}`);
+  return parsed;
+}
+function suggestedInstallCommand(root) {
+  if (fs5.existsSync(path5.join(root, "pnpm-lock.yaml"))) return "pnpm install";
+  if (fs5.existsSync(path5.join(root, "yarn.lock"))) return "yarn install";
+  return "npm install";
+}
 function initTargetOf(value) {
   if (value === "node" || value === "cloudflare") return value;
   throw new Error('atlasflow init target must be "node" or "cloudflare"');
@@ -6578,9 +6919,9 @@ function initConfigSource(target, cloudflareRuntime) {
   lines.push("});", "");
   return lines.join("\n");
 }
-function initPackageJson(target) {
+function initPackageJsonObject(target) {
   const version = atlasflowPackageVersion();
-  const json = {
+  return {
     name: "atlasflow-app",
     private: true,
     type: "module",
@@ -6600,8 +6941,6 @@ function initPackageJson(target) {
       ...target === "cloudflare" ? { wrangler: "^4.87.0" } : {}
     }
   };
-  return `${JSON.stringify(json, null, 2)}
-`;
 }
 var INIT_ENV_EXAMPLE = [
   "# Copy this file to .env for local development.",
@@ -6645,6 +6984,7 @@ Usage:
   atlasflow dev [--port <n>] [--console]   watch + serve locally; optional operator console
   atlasflow build [--output <dir>]         bundle a deployable Node server
   atlasflow deploy [--dry-run]             build and deploy one Worker via Wrangler
+  atlasflow doctor                         diagnose setup and print the next fix
   atlasflow info [--json|--check]          inspect or verify the discovered agent graph
   atlasflow run [agent] [--message <t>]    invoke an agent once (CI-style)
                         [--payload <json>]
@@ -6664,6 +7004,7 @@ Usage:
 Common flags: --root <dir>, --target node|cloudflare, --cloudflare-runtime worker|agents
 `;
 async function main(argv) {
+  assertSupportedNode(process.versions.node);
   const [command, ...rest] = argv;
   const args = parseArgs(rest);
   switch (command) {
@@ -6675,6 +7016,8 @@ async function main(argv) {
       return buildCommand(args);
     case "deploy":
       return deployCommand(args);
+    case "doctor":
+      return doctorCommand(args);
     case "info":
       return infoCommand(args);
     case "run":
@@ -6700,10 +7043,17 @@ async function main(argv) {
       process.stdout.write(HELP);
       return;
     default:
-      throw new Error(`Unknown command "${command}". Try: init, dev, build, deploy, info, run, connect, eval, logs, add, export, import, docs`);
+      throw new Error(`Unknown command "${command}". Try: init, dev, build, deploy, doctor, info, run, connect, eval, logs, add, export, import, docs`);
+  }
+}
+function assertSupportedNode(version) {
+  const major = Number(version.split(".")[0]);
+  if (!Number.isFinite(major) || major < 22) {
+    throw new Error(`AtlasFlow requires Node.js 22 or newer. Current Node.js: ${version}. Next: install Node 22+ and rerun the command.`);
   }
 }
 export {
+  assertSupportedNode,
   defineConfig,
   main
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cybernetyx1/atlasflow-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Command-line tool for authoring, inspecting, building, and deploying AtlasFlow agents.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -27,7 +27,7 @@
   "dependencies": {
     "esbuild": "^0.24.0",
     "yaml": "^2.9.0",
-    "@cybernetyx1/atlasflow-runtime": "0.1.0"
+    "@cybernetyx1/atlasflow-runtime": "0.1.2"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",