autotel-cli 0.8.7 → 0.8.8

package/dist/index.js

@@ -4,7 +4,8 @@
 import { Command } from "commander";
 
 // src/commands/init.ts
-import * as path6 from "path";
+import * as fs4 from "fs";
+import * as path9 from "path";
 import { execSync } from "child_process";
 
 // src/lib/project.ts
@@ -330,11 +331,25 @@ function createCodeFile() {
     backendImports: [],
     pluginImports: [],
     subscriberImports: [],
+    loggerImports: [],
+    loggerSetup: null,
+    loggerExpr: null,
+    autoInstrumentations: [],
     backendConfig: null,
     subscribersConfig: [],
     pluginInit: []
   };
 }
+function setPinoLogger(file) {
+  file.loggerImports.push({ source: "pino", default: "pino" });
+  file.loggerSetup = `const logger = pino({ name: 'app', level: process.env.LOG_LEVEL ?? 'info' });`;
+  file.loggerExpr = "logger";
+}
+function addAutoInstrumentationLogger(file, name) {
+  if (!file.autoInstrumentations.includes(name)) {
+    file.autoInstrumentations.push(name);
+  }
+}
 function addImport(file, imp, section) {
   switch (section) {
     case "backend":
@@ -362,7 +377,7 @@ function addPluginInit(file, init) {
 function sortImports(imports) {
   const sideEffect = [];
   const external = [];
-  const relative5 = [];
+  const relative6 = [];
   for (const imp of imports) {
     if (imp.sideEffect) {
       if (imp.source === "autotel/register") {
@@ -371,15 +386,15 @@ function sortImports(imports) {
         sideEffect.push(imp);
       }
     } else if (imp.source.startsWith(".") || imp.source.startsWith("/")) {
-      relative5.push(imp);
+      relative6.push(imp);
     } else {
       external.push(imp);
     }
   }
   const sortBySource = (a, b) => a.source.localeCompare(b.source);
   external.sort(sortBySource);
-  relative5.sort(sortBySource);
-  return [...sideEffect, ...external, ...relative5];
+  relative6.sort(sortBySource);
+  return [...sideEffect, ...external, ...relative6];
 }
 function renderImport(imp) {
   if (imp.sideEffect) {
@@ -427,7 +442,23 @@ function renderCodeFile(file) {
     lines.push(renderImports(file.subscriberImports));
     lines.push("");
   }
+  if (file.loggerImports.length > 0) {
+    lines.push(SECTION_MARKER("LOGGER"));
+    lines.push(renderImports(file.loggerImports));
+    lines.push("");
+  }
+  if (file.loggerSetup !== null) {
+    lines.push(file.loggerSetup);
+    lines.push("");
+  }
   lines.push("init({");
+  if (file.loggerExpr !== null) {
+    lines.push(`  logger: ${file.loggerExpr},`);
+  }
+  if (file.autoInstrumentations.length > 0) {
+    const list = file.autoInstrumentations.map((n) => `'${n}'`).join(", ");
+    lines.push(`  autoInstrumentations: [${list}],`);
+  }
   if (file.backendConfig) {
     lines.push("  " + SECTION_MARKER("BACKEND_CONFIG"));
     lines.push(`  ${file.backendConfig}`);
@@ -638,60 +669,192 @@ async function checkEnvVarsPresent(packageRoot, varNames, specificFile) {
   return results;
 }
 
-// src/lib/dependency-planner.ts
-function createDependencyPlan() {
-  return {
-    required: [],
-    optional: [],
-    devOnly: []
-  };
-}
-function mergePackages(target, source) {
-  for (const pkg of source) {
-    if (!target.includes(pkg)) {
-      target.push(pkg);
+// src/lib/dep-detector.ts
+import * as fs2 from "fs";
+import * as path6 from "path";
+var DEP_TO_PRESET = {
+  // First-party autotel wrappers
+  "@sentry/node": "sentry",
+  "@sentry/bun": "sentry",
+  hono: "hono",
+  "@modelcontextprotocol/sdk": "mcp",
+  "@tanstack/start": "tanstack",
+  "@tanstack/start-server": "tanstack",
+  "@tanstack/start-client": "tanstack",
+  // Subscribers
+  "posthog-node": "posthog",
+  "@posthog/node": "posthog",
+  mixpanel: "mixpanel",
+  "@amplitude/analytics-node": "amplitude",
+  "@segment/analytics-node": "segment",
+  "@slack/web-api": "slack",
+  "@slack/webhook": "slack",
+  // Plugins (existing presets)
+  mongoose: "mongoose",
+  "drizzle-orm": "drizzle",
+  // Auto-instrumented (no first-party preset needed)
+  express: "auto-instr",
+  fastify: "auto-instr",
+  "@nestjs/core": "auto-instr",
+  next: "auto-instr",
+  pg: "auto-instr",
+  mysql: "auto-instr",
+  mysql2: "auto-instr",
+  redis: "auto-instr",
+  ioredis: "auto-instr",
+  "@aws-sdk/client-s3": "auto-instr",
+  graphql: "auto-instr"
+};
+var LOGGER_DEPS = {
+  pino: "pino",
+  winston: "winston",
+  bunyan: "bunyan"
+};
+var ENV_KEY_TO_BACKEND = [
+  { key: "DD_API_KEY", slug: "datadog" },
+  { key: "DATADOG_API_KEY", slug: "datadog" },
+  { key: "HONEYCOMB_API_KEY", slug: "honeycomb" },
+  { key: "HONEYCOMB_WRITE_KEY", slug: "honeycomb" },
+  { key: "GOOGLE_CLOUD_PROJECT", slug: "google-cloud" },
+  // OTEL endpoint is generic enough that we pick otlp-http
+  { key: "OTEL_EXPORTER_OTLP_ENDPOINT", slug: "otlp-http" }
+];
+function mergeDeps(target, root) {
+  const out = /* @__PURE__ */ new Map();
+  if (root) {
+    for (const [name, version] of Object.entries({
+      ...root.dependencies,
+      ...root.devDependencies
+    })) {
+      out.set(name, { version, resolution: "workspace-root" });
     }
   }
+  for (const [name, version] of Object.entries({
+    ...target.dependencies,
+    ...target.devDependencies
+  })) {
+    out.set(name, { version, resolution: "target" });
+  }
+  return out;
 }
-function addPresetToPlan(plan, preset) {
-  mergePackages(plan.required, preset.packages.required);
-  mergePackages(plan.optional, preset.packages.optional);
-  mergePackages(plan.devOnly, preset.packages.devOnly);
-}
-function addPresetsToPlan(plan, presets) {
-  for (const preset of presets) {
-    addPresetToPlan(plan, preset);
+function detectLoggers(deps) {
+  const present = [];
+  for (const [name, kind] of Object.entries(LOGGER_DEPS)) {
+    if (deps.has(name)) present.push(kind);
+  }
+  if (present.length === 0) return { primary: null, autoInstrument: [] };
+  if (present.includes("pino")) {
+    return {
+      primary: "pino",
+      autoInstrument: present.filter((l) => l !== "pino")
+    };
   }
+  return {
+    primary: present[0] ?? null,
+    autoInstrument: present.slice(1)
+  };
 }
-function getProdPackages(plan) {
-  return [...plan.required, ...plan.optional];
+function parseEnvKeys(content) {
+  const out = /* @__PURE__ */ new Set();
+  for (const rawLine of content.split("\n")) {
+    const line = rawLine.trim();
+    if (line.length === 0 || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    if (key.length > 0) out.add(key);
+  }
+  return out;
 }
-function getDevPackages(plan) {
-  return [...plan.devOnly];
+function collectEnvKeys(opts) {
+  const keys = /* @__PURE__ */ new Set();
+  const sources = [];
+  const tryRead = (name, requiresConsent) => {
+    if (requiresConsent && !opts.envConsent) return;
+    const p = path6.join(opts.packageRoot, name);
+    const content = readFileSafe(p);
+    if (content === null) return;
+    sources.push(name);
+    for (const k of parseEnvKeys(content)) keys.add(k);
+  };
+  tryRead(".env.example", false);
+  tryRead(".env.sample", false);
+  tryRead(".env", true);
+  tryRead(".env.local", true);
+  return { keys, sources };
 }
-function addCorePackages(plan) {
-  mergePackages(plan.required, ["autotel"]);
+function detectBackend(opts) {
+  for (const { key, slug } of ENV_KEY_TO_BACKEND) {
+    if (opts.envKeys.has(key)) {
+      return { slug, source: "env", detail: key };
+    }
+  }
+  if (opts.deps.has("dd-trace")) {
+    return { slug: "datadog", source: "deps", detail: "dd-trace" };
+  }
+  return { slug: "local", source: "default" };
 }
-function addAutoInstrumentationPackages(plan, selection) {
-  if (selection === "none") {
-    return;
+function detectPlatform(packageRoot) {
+  if (fileExists(path6.join(packageRoot, "wrangler.toml")) || fileExists(path6.join(packageRoot, "wrangler.jsonc")) || fileExists(path6.join(packageRoot, "wrangler.json"))) {
+    return "cloudflare";
   }
-  if (selection === "all") {
-    mergePackages(plan.required, ["@opentelemetry/auto-instrumentations-node"]);
-    return;
+  return null;
+}
+function detectInProject(opts) {
+  const { project } = opts;
+  let rootPkg = null;
+  if (project.workspace.workspaceRoot !== null && project.workspace.workspaceRoot !== project.packageRoot) {
+    rootPkg = readJsonSafe(
+      path6.join(project.workspace.workspaceRoot, "package.json")
+    );
   }
-  for (const name of selection) {
-    mergePackages(plan.required, [`@opentelemetry/instrumentation-${name}`]);
+  const deps = mergeDeps(project.packageJson, rootPkg);
+  const detectedPackages = [];
+  const presetSet = /* @__PURE__ */ new Set();
+  const autoInstrDeps = [];
+  for (const [name, info2] of deps.entries()) {
+    const mapping = DEP_TO_PRESET[name];
+    if (mapping === void 0 && LOGGER_DEPS[name] === void 0) continue;
+    detectedPackages.push({
+      name,
+      version: info2.version,
+      resolution: info2.resolution
+    });
+    if (mapping === "auto-instr") {
+      autoInstrDeps.push(name);
+    } else if (mapping !== void 0) {
+      presetSet.add(mapping);
+    }
   }
+  const loggers = detectLoggers(deps);
+  const platform = detectPlatform(project.packageRoot);
+  if (platform !== null) presetSet.add(platform);
+  const { keys: envKeys } = collectEnvKeys({
+    packageRoot: project.packageRoot,
+    envConsent: opts.envConsent
+  });
+  const backend = detectBackend({
+    envKeys,
+    packageRoot: project.packageRoot,
+    deps
+  });
+  return {
+    packages: detectedPackages,
+    presets: [...presetSet],
+    primaryLogger: loggers.primary,
+    autoInstrumentLoggers: loggers.autoInstrument,
+    autoInstrumentedDeps: autoInstrDeps,
+    backend,
+    platform
+  };
 }
-function buildDependencyPlan(options) {
-  const plan = createDependencyPlan();
-  addCorePackages(plan);
-  addPresetsToPlan(plan, options.presets);
-  addAutoInstrumentationPackages(plan, options.autoInstrumentations);
-  return plan;
+function envFilesRequireConsent(packageRoot) {
+  return fileExists(path6.join(packageRoot, ".env")) || fileExists(path6.join(packageRoot, ".env.local"));
 }
 
+// src/lib/plan-builder.ts
+import * as path7 from "path";
+
 // src/presets/backends/datadog.ts
 var datadogDirect = {
   name: "Datadog (Direct)",
@@ -1475,6 +1638,183 @@ var drizzle = {
   ]
 };
 
+// src/presets/plugins/sentry.ts
+var sentry = {
+  name: "Sentry",
+  slug: "sentry",
+  type: "plugin",
+  description: "Send traces to Sentry via OTLP and link captured errors to active traces",
+  packages: {
+    required: ["autotel-sentry", "@sentry/node"],
+    optional: [],
+    devOnly: []
+  },
+  env: {
+    required: [
+      {
+        name: "SENTRY_DSN",
+        description: "Sentry Data Source Name (project ingest URL)",
+        example: "https://<key>@o<org>.ingest.sentry.io/<project>",
+        sensitive: true
+      }
+    ],
+    optional: []
+  },
+  imports: [
+    {
+      source: "@sentry/node",
+      specifiers: ["*"],
+      default: "* as Sentry"
+    },
+    {
+      source: "autotel-sentry",
+      specifiers: ["sentryOtlpConfig", "linkSentryErrors"]
+    }
+  ],
+  configBlock: {
+    type: "plugin",
+    code: `// Sentry OTLP setup
+const sentryConfig = sentryOtlpConfig(process.env.SENTRY_DSN!);
+Sentry.init({ dsn: sentryConfig.dsn, skipOpenTelemetrySetup: true });
+linkSentryErrors(Sentry);`,
+    section: "PLUGIN_INIT"
+  },
+  nextSteps: [
+    "Set SENTRY_DSN in .env (from Sentry \u2192 Settings \u2192 Projects \u2192 Client Keys)",
+    "Captured Sentry errors will now be linked to active OTel traces",
+    "Pass sentryConfig.endpoint and sentryConfig.headers to init() if you want Sentry as the trace backend"
+  ]
+};
+
+// src/presets/plugins/hono.ts
+var hono = {
+  name: "Hono",
+  slug: "hono",
+  type: "plugin",
+  description: "HTTP tracing + metrics middleware for Hono apps",
+  packages: {
+    required: ["autotel-hono"],
+    optional: ["autotel-adapters"],
+    devOnly: []
+  },
+  env: {
+    required: [],
+    optional: []
+  },
+  imports: [
+    {
+      source: "autotel-hono",
+      specifiers: ["otel"]
+    }
+  ],
+  configBlock: {
+    type: "plugin",
+    code: `// Register the otel() middleware on your Hono app:
+//   app.use('*', otel({
+//     serviceName: 'my-service',
+//     captureRequestHeaders: ['user-agent'],
+//     captureResponseHeaders: ['content-type'],
+//   }));`,
+    section: "PLUGIN_INIT"
+  },
+  nextSteps: [
+    "Add otel() middleware to your Hono app: app.use('*', otel({ serviceName: '<name>' }))",
+    "Optionally install autotel-adapters and use useLogger() to thread the request logger",
+    "See packages/autotel-hono README for header/metric configuration"
+  ]
+};
+
+// src/presets/plugins/mcp.ts
+var mcp = {
+  name: "MCP (Model Context Protocol)",
+  slug: "mcp",
+  type: "plugin",
+  description: "Distributed tracing for MCP servers and clients (W3C trace context via _meta)",
+  packages: {
+    required: ["autotel-mcp-instrumentation"],
+    optional: [],
+    devOnly: []
+  },
+  env: {
+    required: [],
+    optional: []
+  },
+  imports: [
+    {
+      source: "autotel-mcp-instrumentation",
+      specifiers: ["instrumentMcpServer"]
+    }
+  ],
+  configBlock: {
+    type: "plugin",
+    code: `// Wrap your MCP server after constructing it:
+//   const instrumented = instrumentMcpServer(server, {
+//     networkTransport: 'pipe',
+//     captureToolArgs: true,
+//     captureToolResults: false,
+//     captureErrors: true,
+//   });
+//
+// For clients, import { instrumentMcpClient } and wrap the client.`,
+    section: "PLUGIN_INIT"
+  },
+  nextSteps: [
+    "Wrap your MCP server with instrumentMcpServer(server, { ... })",
+    "For clients, use instrumentMcpClient from autotel-mcp-instrumentation",
+    "Traces follow OTel MCP semantic conventions and propagate via the _meta field"
+  ]
+};
+
+// src/presets/plugins/tanstack.ts
+var tanstack = {
+  name: "TanStack Start",
+  slug: "tanstack",
+  type: "plugin",
+  description: "Tracing middleware for TanStack Start (SSR requests + server functions)",
+  packages: {
+    required: ["autotel-tanstack"],
+    optional: [],
+    devOnly: []
+  },
+  env: {
+    required: [],
+    optional: []
+  },
+  imports: [
+    {
+      source: "autotel-tanstack/middleware",
+      specifiers: ["createTracingServerHandler"]
+    }
+  ],
+  configBlock: {
+    type: "plugin",
+    code: `// In your start.ts, register tracing middleware on createStart():
+//   import { createMiddleware, createStart } from '@tanstack/react-start';
+//
+//   const requestTracing = createMiddleware().server(
+//     createTracingServerHandler({
+//       captureHeaders: ['x-request-id', 'user-agent'],
+//       excludePaths: ['/health', '/metrics'],
+//     }),
+//   );
+//
+//   const functionTracing = createMiddleware({ type: 'function' }).server(
+//     createTracingServerHandler({ type: 'function', captureArgs: true }),
+//   );
+//
+//   export const startInstance = createStart(() => ({
+//     requestMiddleware: [requestTracing],
+//     functionMiddleware: [functionTracing],
+//   }));`,
+    section: "PLUGIN_INIT"
+  },
+  nextSteps: [
+    "Add tracing middleware to your createStart() call in src/start.ts",
+    'Alternative: import "autotel-tanstack/auto" for zero-config init via OTEL_* env vars',
+    "See packages/autotel-tanstack README for loader/server-function tracing helpers"
+  ]
+};
+
 // src/presets/platforms/aws.ts
 var awsLambda = {
   name: "AWS Lambda",
@@ -1601,7 +1941,11 @@ var subscribers = /* @__PURE__ */ new Map([
 ]);
 var plugins = /* @__PURE__ */ new Map([
   ["mongoose", mongoose],
-  ["drizzle", drizzle]
+  ["drizzle", drizzle],
+  ["sentry", sentry],
+  ["hono", hono],
+  ["mcp", mcp],
+  ["tanstack", tanstack]
 ]);
 var platforms = /* @__PURE__ */ new Map([
   ["aws-lambda", awsLambda],
@@ -1693,120 +2037,399 @@ function listPresetSlugs(type) {
   return [...getPresetsByType(type).keys()];
 }
 
-// src/ui/prompts.ts
-import { select, checkbox, confirm, input } from "@inquirer/prompts";
-async function promptRuntime() {
-  return await select({
-    message: "What runtime are you using?",
-    choices: [
-      { value: "node", name: "Node.js" },
-      { value: "lambda", name: "AWS Lambda" },
-      { value: "cloudflare", name: "Cloudflare Workers" },
-      { value: "edge", name: "Edge Runtime (Vercel Edge, etc.)" }
-    ],
-    default: "node"
-  });
-}
-async function promptBackend(backends2) {
-  const choices = [
-    { value: "local", name: "Local/Console (development only)" },
-    ...[...backends2.entries()].map(([slug, preset]) => ({
-      value: slug,
-      name: `${preset.name} - ${preset.description}`
-    }))
+// src/lib/plan-builder.ts
+function buildPlanFromDetection(opts) {
+  const { project, detection } = opts;
+  const presets = [];
+  const presetSlugs = [];
+  const backendPreset = findPreset(detection.backend.slug);
+  if (backendPreset !== null) {
+    presets.push(backendPreset);
+    presetSlugs.push(detection.backend.slug);
+  }
+  for (const slug of detection.presets) {
+    if (slug === detection.backend.slug) continue;
+    const p = findPreset(slug);
+    if (p !== null) {
+      presets.push(p);
+      presetSlugs.push(slug);
+    }
+  }
+  const prod = /* @__PURE__ */ new Set(["autotel"]);
+  const dev = /* @__PURE__ */ new Set();
+  for (const p of presets) {
+    for (const pkg of p.packages.required) prod.add(pkg);
+    for (const pkg of p.packages.optional) prod.add(pkg);
+    for (const pkg of p.packages.devOnly) dev.add(pkg);
+  }
+  if (detection.primaryLogger === "pino") prod.add("pino");
+  if (detection.autoInstrumentedDeps.length > 0 || detection.autoInstrumentLoggers.length > 0 || detection.primaryLogger === "winston" || detection.primaryLogger === "bunyan") {
+    prod.add("@opentelemetry/auto-instrumentations-node");
+  }
+  const envVars = [];
+  const seenEnv = /* @__PURE__ */ new Set();
+  for (const p of presets) {
+    for (const ev of [...p.env.required, ...p.env.optional]) {
+      if (seenEnv.has(ev.name)) continue;
+      seenEnv.add(ev.name);
+      envVars.push({
+        name: ev.name,
+        sensitive: ev.sensitive,
+        action: "add-to-.env.example"
+      });
+    }
+  }
+  const instrumentationPath = getInstrumentationPath(
+    project.packageRoot,
+    project.hasTypeScript
+  );
+  const filesToWrite = [
+    {
+      path: path7.relative(project.cwd, instrumentationPath),
+      action: fileExists(instrumentationPath) ? "merge" : "create"
+    }
   ];
-  return await select({
-    message: "Where do you want to send telemetry?",
-    choices,
-    default: "local"
-  });
+  const envExamplePath = path7.join(project.packageRoot, ".env.example");
+  if (envVars.length > 0 && !fileExists(envExamplePath)) {
+    filesToWrite.push({
+      path: path7.relative(project.cwd, envExamplePath),
+      action: "create"
+    });
+  }
+  const nextSteps = presets.flatMap((p) => p.nextSteps);
+  const plan = {
+    v: 1,
+    presets: presetSlugs,
+    packagesToInstall: { prod: [...prod], dev: [...dev] },
+    filesToWrite,
+    envVars,
+    nextSteps,
+    detected: {
+      packages: detection.packages,
+      primaryLogger: detection.primaryLogger,
+      autoInstrumentLoggers: detection.autoInstrumentLoggers,
+      autoInstrumentedDeps: detection.autoInstrumentedDeps,
+      backend: detection.backend,
+      platform: detection.platform
+    }
+  };
+  return { plan, presets, instrumentationPath };
 }
-async function promptLogging() {
-  return await select({
-    message: "Which logging framework do you use?",
-    choices: [
-      { value: null, name: "None / Not sure" },
-      { value: "pino", name: "Pino" },
-      { value: "winston", name: "Winston" }
-    ],
-    default: null
-  });
+function findPreset(slug) {
+  for (const type of ["backend", "subscriber", "plugin", "platform"]) {
+    const p = getPreset(type, slug);
+    if (p !== void 0) return p;
+  }
+  return null;
 }
-async function promptDatabases(plugins2) {
-  const choices = [...plugins2.entries()].filter(([, preset]) => preset.type === "plugin").map(([slug, preset]) => ({
-    value: slug,
-    name: `${preset.name} - ${preset.description}`
-  }));
-  if (choices.length === 0) {
-    return [];
+
+// src/lib/errors.ts
+var AutotelErrorCodes = {
+  // validation
+  E_NO_PACKAGE_JSON: "AUTOTEL_E_NO_PACKAGE_JSON",
+  E_UNKNOWN_PRESET: "AUTOTEL_E_UNKNOWN_PRESET",
+  E_INVALID_PLAN: "AUTOTEL_E_INVALID_PLAN",
+  E_INVALID_INPUT: "AUTOTEL_E_INVALID_INPUT",
+  E_INVALID_FLAG: "AUTOTEL_E_INVALID_FLAG",
+  // environment
+  E_NO_WORKSPACE_PACKAGES: "AUTOTEL_E_NO_WORKSPACE_PACKAGES",
+  E_ENV_CONSENT_REQUIRED: "AUTOTEL_E_ENV_CONSENT_REQUIRED",
+  // conflict
+  E_EXISTING_CONFIG: "AUTOTEL_E_EXISTING_CONFIG",
+  E_AMBIGUOUS_LOGGER: "AUTOTEL_E_AMBIGUOUS_LOGGER",
+  // install
+  E_INSTALL_FAILED: "AUTOTEL_E_INSTALL_FAILED",
+  // io
+  E_WRITE_FAILED: "AUTOTEL_E_WRITE_FAILED",
+  E_READ_FAILED: "AUTOTEL_E_READ_FAILED",
+  // runtime
+  E_UNKNOWN: "AUTOTEL_E_UNKNOWN"
+};
+var AutotelError = class extends Error {
+  type;
+  code;
+  retryable;
+  fix;
+  expected;
+  suggestions;
+  constructor(opts) {
+    super(opts.message);
+    this.name = "AutotelError";
+    this.type = opts.type;
+    this.code = opts.code;
+    this.retryable = opts.retryable ?? false;
+    this.fix = opts.fix;
+    this.expected = opts.expected;
+    this.suggestions = opts.suggestions;
+  }
+  toEnvelope(command) {
+    return {
+      ok: false,
+      ...command !== void 0 ? { command } : {},
+      error: {
+        type: this.type,
+        code: this.code,
+        message: this.message,
+        retryable: this.retryable,
+        ...this.fix !== void 0 ? { fix: this.fix } : {},
+        ...this.expected !== void 0 ? { expected: this.expected } : {},
+        ...this.suggestions !== void 0 ? { suggestions: this.suggestions } : {}
+      }
+    };
   }
-  return await checkbox({
-    message: "Which databases/ORMs do you use? (space to select, enter to continue)",
-    choices
+};
+function exitCodeForError(err) {
+  if (err.type === "validation" || err.type === "conflict") {
+    return 2;
+  }
+  return 1;
+}
+function toAutotelError(value) {
+  if (value instanceof AutotelError) return value;
+  const message = value instanceof Error ? value.message : String(value);
+  return new AutotelError({
+    type: "runtime",
+    code: AutotelErrorCodes.E_UNKNOWN,
+    message
   });
 }
-async function promptSubscribers(subscribers2) {
-  const choices = [...subscribers2.entries()].map(([slug, preset]) => ({
-    value: slug,
-    name: `${preset.name} - ${preset.description}`
-  }));
-  if (choices.length === 0) {
-    return [];
+
+// src/lib/plan.ts
+function parsePlan(input2) {
+  if (typeof input2 !== "object" || input2 === null || Array.isArray(input2)) {
+    throw new AutotelError({
+      type: "validation",
+      code: AutotelErrorCodes.E_INVALID_PLAN,
+      message: "Plan must be a JSON object",
+      expected: { v: 1, presets: "string[]" }
+    });
   }
-  return await checkbox({
-    message: "Which event destinations? (space to select, enter to continue)",
-    choices
-  });
+  const obj = input2;
+  if (obj["v"] !== 1) {
+    throw new AutotelError({
+      type: "validation",
+      code: AutotelErrorCodes.E_INVALID_PLAN,
+      message: `Unsupported plan version: ${String(obj["v"])}`,
+      fix: "Regenerate the plan with `autotel init --json --dry-run`",
+      expected: { v: 1 }
+    });
+  }
+  if (!Array.isArray(obj["presets"])) {
+    throw new AutotelError({
+      type: "validation",
+      code: AutotelErrorCodes.E_INVALID_PLAN,
+      message: "plan.presets must be an array of preset slugs"
+    });
+  }
+  const pkgs = obj["packagesToInstall"];
+  if (typeof pkgs !== "object" || pkgs === null || !Array.isArray(pkgs["prod"]) || !Array.isArray(pkgs["dev"])) {
+    throw new AutotelError({
+      type: "validation",
+      code: AutotelErrorCodes.E_INVALID_PLAN,
+      message: "plan.packagesToInstall must be { prod: string[], dev: string[] }"
+    });
+  }
+  return obj;
 }
-async function promptAutoInstrumentation() {
-  return await select({
-    message: "Auto-instrument common libraries?",
-    choices: [
-      { value: "all", name: "All (recommended) - http, express, pg, redis, etc." },
-      { value: "specific", name: "Let me choose specific ones" },
-      { value: "none", name: "None - I'll handle it manually" }
-    ],
-    default: "all"
-  });
+
+// src/lib/instrumentation-parser.ts
+function parseInstrumentation(content) {
+  const cliOwned = hasCliOwnershipHeader(content);
+  const importedSources = collectImportSources(content);
+  const detectedLogger = pickLogger(importedSources);
+  const autoInstrumentations = parseAutoInstrumentations(content);
+  return { cliOwned, importedSources, detectedLogger, autoInstrumentations };
+}
+function collectImportSources(content) {
+  const out = /* @__PURE__ */ new Set();
+  const re = /import\s+(?:[^'"]*\s+from\s+)?['"]([^'"]+)['"]/g;
+  let match;
+  while ((match = re.exec(content)) !== null) {
+    if (match[1] !== void 0) out.add(match[1]);
+  }
+  return out;
+}
+function pickLogger(imports) {
+  if (imports.has("pino")) return "pino";
+  if (imports.has("winston")) return "winston";
+  if (imports.has("bunyan")) return "bunyan";
+  return null;
+}
+function parseAutoInstrumentations(content) {
+  const re = /autoInstrumentations\s*:\s*\[([^\]]*)\]/;
+  const match = re.exec(content);
+  if (!match || match[1] === void 0) return [];
+  return [...match[1].matchAll(/['"]([^'"]+)['"]/g)].map((m) => m[1]).filter((s) => s !== void 0);
+}
+function diffImportSources(existing, planImportSources) {
+  return planImportSources.filter((s) => !existing.importedSources.has(s));
 }
-async function promptStartupStyle(hasTypeScript) {
-  const choices = hasTypeScript ? [
-    { value: "node-esm", name: "Node ESM (node --import) - Recommended" },
-    { value: "tsx", name: "tsx (tsx --import) - For development" },
-    { value: "ts-node", name: "ts-node" },
-    { value: "nextjs", name: "Next.js" },
-    { value: "other", name: "Other / Manual" }
-  ] : [
-    { value: "node-esm", name: "Node ESM (node --import) - Recommended" },
-    { value: "nextjs", name: "Next.js" },
-    { value: "other", name: "Other / Manual" }
+function diffAutoInstrumentations(existing, planEntries) {
+  return planEntries.filter((e) => !existing.autoInstrumentations.includes(e));
+}
+
+// src/ui/preview.ts
+import chalk from "chalk";
+import { checkbox, select } from "@inquirer/prompts";
+function renderPlanPreview(plan) {
+  const lines = [
+    chalk.bold("autotel init \u2014 proposed plan"),
+    ""
   ];
-  return await select({
-    message: "How do you start your app?",
-    choices,
-    default: "node-esm"
-  });
+  if (plan.detected) {
+    const det = plan.detected;
+    const pkgList = det.packages.map((p) => `${p.name}@${p.version}`).join(", ");
+    lines.push(
+      `${chalk.dim("Detected packages:")} ${pkgList || chalk.dim("(none)")}`
+    );
+    if (det.primaryLogger !== null) {
+      lines.push(
+        `${chalk.dim("Logger:")} ${chalk.bold(det.primaryLogger)} ${chalk.dim("(first-class)")}` + (det.autoInstrumentLoggers.length > 0 ? `, ${chalk.dim("+ auto-instrumented:")} ${det.autoInstrumentLoggers.join(", ")}` : "")
+      );
+    }
+    if (det.autoInstrumentedDeps.length > 0) {
+      lines.push(
+        `${chalk.dim("Covered by auto-instrumentations-node:")} ${det.autoInstrumentedDeps.join(", ")}`
+      );
+    }
+    lines.push(
+      `${chalk.dim("Backend:")} ${chalk.bold(det.backend.slug)} ${chalk.dim(`(${det.backend.source}${det.backend.detail ? `: ${det.backend.detail}` : ""})`)}`
+    );
+    if (det.platform !== null) {
+      lines.push(`${chalk.dim("Platform:")} ${chalk.bold(det.platform)}`);
+    }
+  }
+  lines.push("");
+  lines.push(chalk.bold("Will wire:"));
+  for (const slug of plan.presets) {
+    lines.push(`  ${chalk.green("+")} ${slug}`);
+  }
+  lines.push("");
+  if (plan.packagesToInstall.prod.length > 0) {
+    lines.push(
+      `${chalk.bold("Install:")} ${plan.packagesToInstall.prod.join(", ")}`
+    );
+  }
+  if (plan.packagesToInstall.dev.length > 0) {
+    lines.push(
+      `${chalk.bold("Install (dev):")} ${plan.packagesToInstall.dev.join(", ")}`
+    );
+  }
+  if (plan.envVars.length > 0) {
+    lines.push("");
+    lines.push(chalk.bold("Env vars:"));
+    for (const ev of plan.envVars) {
+      const marker = ev.sensitive ? chalk.yellow("[sensitive]") : "";
+      lines.push(`  ${ev.name} ${marker}`);
+    }
+  }
+  if (plan.filesToWrite.length > 0) {
+    lines.push("");
+    lines.push(chalk.bold("Files:"));
+    for (const f of plan.filesToWrite) {
+      lines.push(`  ${chalk.dim(f.action)}  ${f.path}`);
+    }
+  }
+  return lines.join("\n");
 }
-async function promptExistingConfigAction() {
-  return await select({
-    message: "Existing instrumentation detected. What would you like to do?",
+async function confirmOrEditPlan(plan) {
+  console.log(renderPlanPreview(plan));
+  console.log("");
+  const choice = await select({
+    message: "Proceed?",
     choices: [
-      { value: "update", name: "Update existing file (recommended)" },
-      { value: "new", name: "Create new file (src/autotel-config.mts)" },
-      { value: "abort", name: "Abort" }
+      { value: "apply", name: "Apply the plan above" },
+      { value: "edit", name: "Edit \u2014 deselect items I do not want" },
+      { value: "abort", name: "Abort, write nothing" }
     ],
-    default: "update"
+    default: "apply"
+  });
+  if (choice === "abort") return null;
+  if (choice === "apply") return plan;
+  const kept = await checkbox({
+    message: "Keep which presets?",
+    choices: plan.presets.map((slug) => ({
+      value: slug,
+      name: slug,
+      checked: true
+    }))
+  });
+  return { ...plan, presets: kept };
+}
+
+// src/lib/json-output.ts
+import * as fs3 from "fs";
+import * as path8 from "path";
+var outputFilePath = null;
+var outputFileWritten = false;
+var outputRoot = null;
+var redactSecrets = false;
+function configureJsonOutput(opts) {
+  outputFilePath = opts.outputFile ?? null;
+  outputFileWritten = false;
+  outputRoot = opts.outputRoot ?? null;
+  redactSecrets = opts.noSecrets === true || process.env["AUTOTEL_NO_SECRETS"] === "1" || process.env["AGENT_SANDBOX"] === "1";
+}
+var SECRET_KEY_PATTERN = /SECRET|TOKEN|PASSWORD|API[_-]?KEY|DSN/i;
+var SECRET_VALUE_PATTERN = /^[A-Za-z0-9_\-+/=]{40,}$/;
+var REDACTED = "[REDACTED]";
+function redact(value) {
+  if (value === null || value === void 0) return value;
+  if (Array.isArray(value)) {
+    return value.map((v) => redact(v));
+  }
+  if (typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (typeof v === "string" && SECRET_KEY_PATTERN.test(k)) {
+        out[k] = REDACTED;
+      } else {
+        out[k] = redact(v);
+      }
+    }
+    return out;
+  }
+  if (typeof value === "string" && SECRET_VALUE_PATTERN.test(value)) {
+    return REDACTED;
+  }
+  return value;
+}
+function printJson(data) {
+  const payload = redactSecrets ? redact(data) : data;
+  const serialised = JSON.stringify(payload, null, 2);
+  process.stdout.write(serialised + "\n");
+  if (outputFilePath !== null && !outputFileWritten) {
+    writeArtifactFile(outputFilePath, serialised);
+    outputFileWritten = true;
+  }
+}
+function writeArtifactFile(filePath, content) {
+  const resolved = path8.resolve(filePath);
+  if (outputRoot !== null) {
+    atomicWrite(resolved, content, { root: outputRoot });
+  } else {
+    fs3.mkdirSync(path8.dirname(resolved), { recursive: true });
+    fs3.writeFileSync(resolved, content, "utf8");
+  }
+}
+
+// src/ui/prompts.ts
+import { select as select2, checkbox as checkbox2, confirm, input } from "@inquirer/prompts";
+async function promptConfirm(message, defaultValue = true) {
+  return await confirm({
+    message,
+    default: defaultValue
   });
 }
 
 // src/ui/output.ts
-import chalk from "chalk";
+import chalk2 from "chalk";
 var STATUS = {
-  ok: chalk.green("[OK]"),
-  warn: chalk.yellow("[WARN]"),
-  error: chalk.red("[ERROR]"),
-  info: chalk.blue("[INFO]"),
-  skip: chalk.gray("[SKIP]")
+  ok: chalk2.green("[OK]"),
+  warn: chalk2.yellow("[WARN]"),
+  error: chalk2.red("[ERROR]"),
+  info: chalk2.blue("[INFO]"),
+  skip: chalk2.gray("[SKIP]")
 };
 function formatCheck(check) {
   const lines = [];
@@ -1814,68 +2437,66 @@ function formatCheck(check) {
   lines.push(`  ${statusToken} ${check.message}`);
   if (check.details && check.details.length > 0) {
     for (const detail of check.details) {
-      lines.push(`         ${chalk.dim(detail)}`);
+      lines.push(`         ${chalk2.dim(detail)}`);
     }
   }
   if (check.fix) {
-    lines.push(`         ${chalk.cyan("Fix:")} ${check.fix.cmd}`);
+    lines.push(`         ${chalk2.cyan("Fix:")} ${check.fix.cmd}`);
   }
   return lines;
 }
 function formatSummary(summary) {
   const parts = [];
   if (summary.ok > 0) {
-    parts.push(chalk.green(`${summary.ok} passed`));
+    parts.push(chalk2.green(`${summary.ok} passed`));
   }
   if (summary.warnings > 0) {
-    parts.push(chalk.yellow(`${summary.warnings} warning${summary.warnings > 1 ? "s" : ""}`));
+    parts.push(chalk2.yellow(`${summary.warnings} warning${summary.warnings > 1 ? "s" : ""}`));
   }
   if (summary.errors > 0) {
-    parts.push(chalk.red(`${summary.errors} error${summary.errors > 1 ? "s" : ""}`));
+    parts.push(chalk2.red(`${summary.errors} error${summary.errors > 1 ? "s" : ""}`));
   }
   if (summary.skipped > 0) {
-    parts.push(chalk.gray(`${summary.skipped} skipped`));
+    parts.push(chalk2.gray(`${summary.skipped} skipped`));
   }
   return `Summary: ${parts.join(", ")}`;
 }
 function formatFooter(options) {
   const lines = [""];
   if (options.detected) {
-    lines.push(chalk.dim(`Detected: ${options.detected}`));
+    lines.push(chalk2.dim(`Detected: ${options.detected}`));
   }
   if (options.wrote && options.wrote.length > 0) {
-    lines.push(chalk.dim(`Wrote: ${options.wrote.join(", ")}`));
+    lines.push(chalk2.dim(`Wrote: ${options.wrote.join(", ")}`));
   }
   if (options.next) {
-    lines.push(chalk.cyan(`Next: ${options.next}`));
+    lines.push(chalk2.cyan(`Next: ${options.next}`));
   }
   return lines.join("\n");
 }
+function formatPackageManagerInfo(pm, lockfilePath) {
+  if (lockfilePath) {
+    return `${pm} (via ${chalk2.dim(lockfilePath)})`;
+  }
+  return `${pm} (default, no lockfile found)`;
+}
 function heading(text) {
-  console.log(chalk.bold(text));
+  console.log(chalk2.bold(text));
 }
 function info(text) {
-  console.log(chalk.blue(text));
+  console.log(chalk2.blue(text));
 }
 function success(text) {
-  console.log(chalk.green(text));
+  console.log(chalk2.green(text));
 }
 function warn(text) {
-  console.log(chalk.yellow(text));
+  console.log(chalk2.yellow(text));
 }
 function error(text) {
-  console.log(chalk.red(text));
+  console.log(chalk2.red(text));
 }
 function dim(text) {
-  console.log(chalk.dim(text));
-}
-function isVerbose() {
-  return process.env["AUTOTEL_VERBOSE"] === "true";
-}
-function verbose(text) {
-  if (isVerbose()) {
-    console.log(chalk.gray(`[verbose] ${text}`));
-  }
+  console.log(chalk2.dim(text));
 }
 
 // src/ui/spinner.ts
@@ -1906,104 +2527,200 @@ function isCI() {
 
 // src/commands/init.ts
 async function runInit(options) {
-  const spinner = createSpinner();
-  if (options.verbose) {
-    process.env["AUTOTEL_VERBOSE"] = "true";
-  }
-  if (options.quiet) {
-    process.env["AUTOTEL_QUIET"] = "true";
+  if (options.json) {
+    configureJsonOutput({
+      outputFile: options.outputFile,
+      noSecrets: options.noSecrets
+    });
   }
-  spinner.start("Discovering project...");
+  if (options.verbose) process.env["AUTOTEL_VERBOSE"] = "true";
+  if (options.quiet) process.env["AUTOTEL_QUIET"] = "true";
   const project = discoverProject(options.cwd);
-  if (!project) {
-    spinner.fail("No package.json found");
-    error("Run this command in a directory with a package.json, or use --cwd");
-    process.exit(1);
+  if (project === null) {
+    throw new AutotelError({
+      type: "environment",
+      code: AutotelErrorCodes.E_NO_PACKAGE_JSON,
+      message: `No package.json found at or above ${options.cwd}`,
+      fix: "cd into a directory with a package.json, or pass --cwd <path>",
+      expected: { file: "package.json" }
+    });
   }
-  spinner.succeed(`Found ${project.packageJson.name ?? "project"}`);
-  verbose(`Package root: ${project.packageRoot}`);
-  verbose(`Package manager: ${project.packageManager}`);
-  const existingConfig = detectConfig(project.packageRoot);
-  if (existingConfig.found && !options.force) {
-    info(`Existing instrumentation detected at ${existingConfig.path}`);
-    if (options.yes || isCI()) {
-      warn("Use --force to overwrite existing config");
-      process.exit(0);
-    }
-    const action = await promptExistingConfigAction();
-    if (action === "abort") {
+  if (options.json && options.outputFile !== void 0) {
+    configureJsonOutput({
+      outputFile: options.outputFile,
+      outputRoot: project.packageRoot,
+      noSecrets: options.noSecrets
+    });
+  }
+  let plan = null;
+  if (options.plan !== void 0) {
+    plan = readPlanFromFile(options.plan);
+  } else if (options.input !== void 0) {
+    plan = await readPlanFromInput(options.input);
+  } else if (options.preset !== void 0) {
+    plan = planFromQuickPreset(options.preset, project);
+  } else if (!options.noDetect) {
+    plan = await planFromDetection(project, options);
+  }
+  if (plan === null) {
+    throw new AutotelError({
+      type: "validation",
+      code: AutotelErrorCodes.E_INVALID_FLAG,
+      message: "No plan source available (--no-detect disables detection)",
+      fix: "Drop --no-detect or pass --plan / --input / --preset"
+    });
+  }
+  const interactive = !options.yes && !options.noInteractive && !options.json && !isCI();
+  if (interactive && options.plan === void 0 && options.input === void 0 && options.preset === void 0) {
+    const confirmed = await confirmOrEditPlan(plan);
+    if (confirmed === null) {
       info("Aborted");
-      process.exit(0);
-    }
-  }
-  const selectedPresets = [];
-  let autoInstrumentations = "all";
-  let startupStyle = "node-esm";
-  if (options.preset) {
-    const quickPreset = getQuickPreset(options.preset);
-    if (quickPreset) {
-      info(`Using quick preset: ${quickPreset.name}`);
-      const backendPreset = getPreset("backend", quickPreset.backend);
-      if (backendPreset) {
-        selectedPresets.push(backendPreset);
-      }
-      if (quickPreset.subscribers) {
-        for (const sub of quickPreset.subscribers) {
-          const subPreset = getPreset("subscriber", sub);
-          if (subPreset) selectedPresets.push(subPreset);
-        }
-      }
-      if (quickPreset.plugins) {
-        for (const plug of quickPreset.plugins) {
-          const plugPreset = getPreset("plugin", plug);
-          if (plugPreset) selectedPresets.push(plugPreset);
-        }
-      }
-      autoInstrumentations = quickPreset.autoInstrumentations;
+      return;
+    }
+    plan = confirmed;
+  }
+  if (options.detectOnly) {
+    if (options.json) {
+      printJson({ ok: true, command: "autotel init", plan });
     } else {
-      error(`Unknown preset: ${options.preset}`);
-      info("Available presets: node-datadog-pino, node-datadog-agent, node-honeycomb, node-otlp");
-      process.exit(1);
+      info("Detection-only mode \u2014 no files written");
+      console.log(JSON.stringify(plan, null, 2));
     }
-  } else if (options.yes || isCI()) {
-    info("Using defaults (local backend, all auto-instrumentations)");
-    const localPreset = getPreset("backend", "local");
-    if (localPreset) {
-      selectedPresets.push(localPreset);
+    return;
+  }
+  if (options.json && options.dryRun) {
+    printJson({ ok: true, command: "autotel init", plan, dryRun: true });
+    return;
+  }
+  if (options.json && !options.dryRun) {
+    const applied2 = applyPlan({ plan, project, options });
+    printJson({ ok: true, command: "autotel init", plan, applied: applied2 });
+    return;
+  }
+  if (options.dryRun) {
+    heading("\nDry run \u2014 no files will be written\n");
+    console.log(JSON.stringify(plan, null, 2));
+    return;
+  }
+  const applied = applyPlan({ plan, project, options });
+  printApplySummary({ plan, applied, project, options });
+}
+function readPlanFromFile(filePath) {
+  const content = readFileSafe(filePath);
+  if (content === null) {
+    throw new AutotelError({
+      type: "io",
+      code: AutotelErrorCodes.E_READ_FAILED,
+      message: `Could not read plan file: ${filePath}`
+    });
+  }
+  try {
+    return parsePlan(JSON.parse(content));
+  } catch (error2) {
+    if (error2 instanceof AutotelError) throw error2;
+    throw new AutotelError({
+      type: "validation",
+      code: AutotelErrorCodes.E_INVALID_PLAN,
+      message: `Plan file is not valid JSON: ${error2.message}`
+    });
+  }
+}
+async function readPlanFromInput(input2) {
+  if (input2 === "-") {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
     }
-  } else {
-    const runtime = await promptRuntime();
-    verbose(`Runtime: ${runtime}`);
-    const backendSlug = await promptBackend(backends);
-    const backendPreset = getPreset("backend", backendSlug);
-    if (backendPreset) {
-      selectedPresets.push(backendPreset);
-    }
-    await promptLogging();
-    const pluginSlugs = await promptDatabases(plugins);
-    for (const slug of pluginSlugs) {
-      const preset = getPreset("plugin", slug);
-      if (preset) selectedPresets.push(preset);
-    }
-    const subscriberSlugs = await promptSubscribers(subscribers);
-    for (const slug of subscriberSlugs) {
-      const preset = getPreset("subscriber", slug);
-      if (preset) selectedPresets.push(preset);
-    }
-    const autoChoice = await promptAutoInstrumentation();
-    if (autoChoice === "none") {
-      autoInstrumentations = "none";
-    } else if (autoChoice === "specific") {
-      autoInstrumentations = "all";
-    }
-    if (runtime === "node") {
-      startupStyle = await promptStartupStyle(project.hasTypeScript);
+    const content = Buffer.concat(chunks).toString("utf8");
+    try {
+      return parsePlan(JSON.parse(content));
+    } catch (error2) {
+      if (error2 instanceof AutotelError) throw error2;
+      throw new AutotelError({
+        type: "validation",
+        code: AutotelErrorCodes.E_INVALID_INPUT,
+        message: `stdin did not contain valid JSON: ${error2.message}`
+      });
     }
   }
+  return readPlanFromFile(input2);
+}
+function planFromQuickPreset(slug, project) {
+  if (project === null) {
+    throw new AutotelError({
+      type: "environment",
+      code: AutotelErrorCodes.E_NO_PACKAGE_JSON,
+      message: "project required"
+    });
+  }
+  const quick = getQuickPreset(slug);
+  if (quick === void 0) {
+    throw new AutotelError({
+      type: "validation",
+      code: AutotelErrorCodes.E_UNKNOWN_PRESET,
+      message: `Unknown preset: ${slug}`,
+      fix: "Run `autotel commands --json` to see available presets"
+    });
+  }
+  const presets = [quick.backend];
+  if (quick.subscribers) presets.push(...quick.subscribers);
+  if (quick.plugins) presets.push(...quick.plugins);
+  const { plan } = buildPlanFromDetection({
+    project,
+    detection: {
+      packages: [],
+      presets,
+      primaryLogger: quick.logging === "pino" ? "pino" : null,
+      autoInstrumentLoggers: [],
+      autoInstrumentedDeps: [],
+      backend: { slug: quick.backend, source: "default" },
+      platform: null
+    }
+  });
+  return plan;
+}
+async function planFromDetection(project, options) {
+  if (project === null) {
+    throw new AutotelError({
+      type: "environment",
+      code: AutotelErrorCodes.E_NO_PACKAGE_JSON,
+      message: "project required"
+    });
+  }
+  let envConsent = options.scanEnv;
+  if (!envConsent && envFilesRequireConsent(project.packageRoot) && !options.yes && !options.noInteractive && !options.json && !isCI()) {
+    envConsent = await promptConfirm(
+      `Found a .env file. Read its keys to help detect the backend? (values are never read)`,
+      false
+    );
+  }
+  const detection = detectInProject({ project, envConsent });
+  const { plan } = buildPlanFromDetection({ project, detection });
+  return plan;
+}
+function applyPlan(args) {
+  const { plan, project, options } = args;
+  const result = {
+    wroteFiles: [],
+    ranInstalls: [],
+    printedInstalls: [],
+    installErrors: []
+  };
+  const presets = [];
+  for (const slug of plan.presets) {
+    const p = resolvePreset(slug);
+    if (p !== null) presets.push(p);
+  }
   const codeFile = createCodeFile();
   addImport(codeFile, { source: "autotel/register", sideEffect: true });
   addImport(codeFile, { source: "autotel", specifiers: ["init"] });
-  for (const preset of selectedPresets) {
+  if (plan.detected?.primaryLogger === "pino") {
+    setPinoLogger(codeFile);
+  }
+  for (const l of plan.detected?.autoInstrumentLoggers ?? []) {
+    addAutoInstrumentationLogger(codeFile, l);
+  }
+  for (const preset of presets) {
     for (const imp of preset.imports) {
       const section = preset.type === "backend" || preset.type === "platform" ? "backend" : preset.type === "plugin" ? "plugin" : preset.type === "subscriber" ? "subscriber" : void 0;
       addImport(codeFile, imp, section);
@@ -2016,130 +2733,143 @@ async function runInit(options) {
       addPluginInit(codeFile, preset.configBlock.code);
     }
   }
-  if (!codeFile.backendConfig) {
+  if (codeFile.backendConfig === null) {
     setBackendConfig(codeFile, "// Local/console mode - no backend configured");
   }
-  const instrumentationContent = renderCodeFile(codeFile);
-  const depPlan = buildDependencyPlan({
-    presets: selectedPresets,
-    autoInstrumentations
-  });
-  const envVars = [];
-  for (const preset of selectedPresets) {
-    envVars.push(...preset.env.required, ...preset.env.optional);
-  }
-  const envExampleContent = generateEnvExample(envVars);
-  const instrumentationPath = getInstrumentationPath(project.packageRoot, project.hasTypeScript);
-  const envExamplePath = path6.join(project.packageRoot, ".env.example");
-  if (options.dryRun) {
-    heading("\nDry run - no files will be written\n");
-    info(`Would write: ${path6.relative(project.cwd, instrumentationPath)}`);
-    console.log("---");
-    console.log(instrumentationContent);
-    console.log("---\n");
-    if (envExampleContent) {
-      info(`Would write: ${path6.relative(project.cwd, envExamplePath)}`);
-      console.log("---");
-      console.log(envExampleContent);
-      console.log("---\n");
-    }
-    const prodPkgs2 = getProdPackages(depPlan);
-    const devPkgs2 = getDevPackages(depPlan);
-    if (prodPkgs2.length > 0) {
-      const cmd = getInstallCommand(project.packageManager, prodPkgs2);
-      info(`Would run: ${cmd}`);
+  const newContent = renderCodeFile(codeFile);
+  const instrumentationPath = resolveInstrumentationPath(project);
+  const envExamplePath = path9.join(project.packageRoot, ".env.example");
+  const existing = readFileSafe(instrumentationPath);
+  if (existing !== null) {
+    const parsed = parseInstrumentation(existing);
+    if (!parsed.cliOwned && !options.force) {
+      throw new AutotelError({
+        type: "conflict",
+        code: AutotelErrorCodes.E_EXISTING_CONFIG,
+        message: `Hand-edited instrumentation file at ${instrumentationPath} (no CLI markers found)`,
+        fix: "Pass --force to overwrite (creates a .bak backup) or remove the file",
+        expected: { path: instrumentationPath }
+      });
     }
-    if (devPkgs2.length > 0) {
-      const cmd = getInstallCommand(project.packageManager, devPkgs2, { dev: true });
-      info(`Would run: ${cmd}`);
+    const addedImports = diffImportSources(
+      parsed,
+      [
+        ...codeFile.imports,
+        ...codeFile.backendImports,
+        ...codeFile.pluginImports,
+        ...codeFile.subscriberImports,
+        ...codeFile.loggerImports
+      ].map((i) => i.source)
+    );
+    const addedAuto = diffAutoInstrumentations(
+      parsed,
+      codeFile.autoInstrumentations
+    );
+    const contentChanged = existing !== newContent;
+    if (addedImports.length === 0 && addedAuto.length === 0 && parsed.cliOwned && !contentChanged) {
+      result.wroteFiles.push(
+        `${path9.relative(project.cwd, instrumentationPath)} (no changes)`
+      );
+    } else {
+      atomicWrite(instrumentationPath, newContent, {
+        root: project.packageRoot,
+        backup: true
+      });
+      result.wroteFiles.push(path9.relative(project.cwd, instrumentationPath));
     }
-    process.exit(0);
+  } else {
+    atomicWrite(instrumentationPath, newContent, {
+      root: project.packageRoot
+    });
+    result.wroteFiles.push(path9.relative(project.cwd, instrumentationPath));
   }
-  spinner.start("Writing instrumentation file...");
-  const { backupPath: instrBackup } = atomicWrite(instrumentationPath, instrumentationContent, {
-    root: project.packageRoot,
-    backup: options.force
-  });
-  if (instrBackup) {
-    verbose(`Backup created: ${instrBackup}`);
-  }
-  spinner.succeed(`Wrote ${path6.relative(project.cwd, instrumentationPath)}`);
-  if (envExampleContent && !fileExists(envExamplePath)) {
-    spinner.start("Writing .env.example...");
-    atomicWrite(envExamplePath, envExampleContent, { root: project.packageRoot });
-    spinner.succeed(`Wrote ${path6.relative(project.cwd, envExamplePath)}`);
-  }
-  const prodPkgs = getProdPackages(depPlan);
-  const devPkgs = getDevPackages(depPlan);
-  if (!options.noInstall && (prodPkgs.length > 0 || devPkgs.length > 0)) {
-    if (prodPkgs.length > 0) {
-      const cmd = getInstallCommand(project.packageManager, prodPkgs);
-      if (options.printInstallCmd) {
-        info(`Install command: ${cmd}`);
-      } else {
-        spinner.start("Installing dependencies...");
+  const envVars = [];
+  for (const p of presets) {
+    envVars.push(...p.env.required, ...p.env.optional);
+  }
+  const envExampleContent = generateEnvExample(envVars);
+  if (envExampleContent.length > 0 && !fileExists(envExamplePath)) {
+    atomicWrite(envExamplePath, envExampleContent, {
+      root: project.packageRoot
+    });
+    result.wroteFiles.push(path9.relative(project.cwd, envExamplePath));
+  }
+  const prod = plan.packagesToInstall.prod;
+  const dev = plan.packagesToInstall.dev;
+  if (prod.length > 0 || dev.length > 0) {
+    if (options.noInstall || options.printInstallCmd) {
+      if (prod.length > 0) {
+        result.printedInstalls.push(
+          getInstallCommand(project.packageManager, prod)
+        );
+      }
+      if (dev.length > 0) {
+        result.printedInstalls.push(
+          getInstallCommand(project.packageManager, dev, { dev: true })
+        );
+      }
+    } else {
+      if (prod.length > 0) {
+        const cmd = getInstallCommand(project.packageManager, prod);
         try {
           execSync(cmd, { cwd: project.packageRoot, stdio: "pipe" });
-          spinner.succeed("Dependencies installed");
+          result.ranInstalls.push(cmd);
         } catch {
-          spinner.fail("Failed to install dependencies");
-          error(`Run manually: ${cmd}`);
+          result.installErrors.push(cmd);
         }
       }
-    }
-    if (devPkgs.length > 0) {
-      const cmd = getInstallCommand(project.packageManager, devPkgs, { dev: true });
-      if (options.printInstallCmd) {
-        info(`Install command (dev): ${cmd}`);
-      } else {
-        spinner.start("Installing dev dependencies...");
+      if (dev.length > 0) {
+        const cmd = getInstallCommand(project.packageManager, dev, {
+          dev: true
+        });
         try {
           execSync(cmd, { cwd: project.packageRoot, stdio: "pipe" });
-          spinner.succeed("Dev dependencies installed");
+          result.ranInstalls.push(cmd);
         } catch {
-          spinner.fail("Failed to install dev dependencies");
-          error(`Run manually: ${cmd}`);
+          result.installErrors.push(cmd);
         }
       }
     }
-  } else if (options.noInstall && (prodPkgs.length > 0 || devPkgs.length > 0)) {
-    info("Skipping installation (--no-install)");
-    if (prodPkgs.length > 0) {
-      const cmd = getInstallCommand(project.packageManager, prodPkgs);
-      dim(`Run: ${cmd}`);
-    }
-    if (devPkgs.length > 0) {
-      const cmd = getInstallCommand(project.packageManager, devPkgs, { dev: true });
-      dim(`Run: ${cmd}`);
-    }
   }
-  const relInstrPath = path6.relative(project.packageRoot, instrumentationPath);
-  let nextStepCmd;
-  switch (startupStyle) {
-    case "tsx":
-      nextStepCmd = `tsx --import ./${relInstrPath} src/index.ts`;
-      break;
-    case "node-esm":
-    default:
-      nextStepCmd = `node --import ./${relInstrPath} dist/index.js`;
+  return result;
+}
+function resolveInstrumentationPath(project) {
+  const srcDir = path9.join(project.packageRoot, "src");
+  const hasSrcDir = fs4.existsSync(srcDir) || fileExists(path9.join(project.packageRoot, "src", "index.ts")) || fileExists(path9.join(project.packageRoot, "src", "index.js"));
+  const dir = hasSrcDir ? srcDir : project.packageRoot;
+  const ext = project.hasTypeScript ? "mts" : "mjs";
+  return path9.join(dir, `instrumentation.${ext}`);
+}
+function resolvePreset(slug) {
+  for (const type of ["backend", "subscriber", "plugin", "platform"]) {
+    const p = getPreset(type, slug);
+    if (p !== void 0) return p;
   }
-  const pmInfo = project.workspace.isMonorepo ? `${project.packageManager} workspace, package root ${project.packageRoot}` : `${project.packageManager}`;
-  const writtenFiles = [path6.relative(project.cwd, instrumentationPath)];
-  if (envExampleContent && !fileExists(envExamplePath)) {
-    writtenFiles.push(".env.example");
+  return null;
+}
+function printApplySummary(args) {
+  const { applied, plan, project } = args;
+  if (applied.wroteFiles.length > 0) {
+    success(`Wrote: ${applied.wroteFiles.join(", ")}`);
   }
-  console.log(formatFooter({
-    detected: pmInfo,
-    wrote: writtenFiles,
-    next: nextStepCmd
-  }));
-  const allNextSteps = selectedPresets.flatMap((p) => p.nextSteps);
-  if (allNextSteps.length > 0) {
+  for (const cmd of applied.ranInstalls) {
+    info(`Installed: ${cmd}`);
+  }
+  for (const cmd of applied.printedInstalls) {
+    dim(`Run: ${cmd}`);
+  }
+  for (const cmd of applied.installErrors) {
+    error(`Install failed \u2014 run manually: ${cmd}`);
+  }
+  if (plan.nextSteps.length > 0) {
     console.log("\nNext steps:");
-    for (const step of allNextSteps) {
+    for (const step of plan.nextSteps) {
       console.log(`  - ${step}`);
     }
   }
+  const pmInfo = project.workspace.isMonorepo ? `${project.packageManager} workspace, package root ${project.packageRoot}` : project.packageManager;
+  console.log(`
+${formatPackageManagerInfo ? formatPackageManagerInfo(project.packageManager, project.lockfilePath) : pmInfo}`);
 }
 
 // src/lib/dependency-auditor.ts
@@ -2181,7 +2911,7 @@ function getAutotelInfo(packageJson) {
 }
 
 // src/lib/esm-checker.ts
-import * as path7 from "path";
+import * as path10 from "path";
 function checkRegisterImportOrder(content) {
   const lines = content.split("\n");
   let registerLine = null;
@@ -2238,7 +2968,7 @@ function checkEsmHook(project) {
     if (result.found && !result.isFirst) {
       return {
         status: "warn",
-        message: `autotel/register import found but not first in ${path7.basename(entrypoint)}:${result.lineNumber}`,
+        message: `autotel/register import found but not first in ${path10.basename(entrypoint)}:${result.lineNumber}`,
         details: [
           "autotel/register must be the first import for instrumentation to work",
           "Move it to the top of the file, before any other imports"
@@ -2248,7 +2978,7 @@ function checkEsmHook(project) {
     if (result.found && result.isFirst) {
       return {
         status: "ok",
-        message: `autotel/register correctly imported first in ${path7.basename(entrypoint)}`
+        message: `autotel/register correctly imported first in ${path10.basename(entrypoint)}`
       };
     }
   }
@@ -2263,8 +2993,8 @@ function checkEsmHook(project) {
 }
 
 // src/lib/logger-checker.ts
-import * as path8 from "path";
-import * as fs2 from "fs";
+import * as path11 from "path";
+import * as fs5 from "fs";
 var LOGGER_INSTRUMENTATION = {
   winston: "@opentelemetry/instrumentation-winston",
   bunyan: "@opentelemetry/instrumentation-bunyan",
@@ -2294,17 +3024,17 @@ function extractAutoInstrumentations(content) {
 }
 function findSourceFiles(packageRoot) {
   const sourceFiles = [];
-  const srcDir = path8.join(packageRoot, "src");
+  const srcDir = path11.join(packageRoot, "src");
   const dirsToCheck = [packageRoot, srcDir].filter(
-    (dir) => fs2.existsSync(dir) && fs2.statSync(dir).isDirectory()
+    (dir) => fs5.existsSync(dir) && fs5.statSync(dir).isDirectory()
   );
   for (const dir of dirsToCheck) {
-    const files = fs2.readdirSync(dir, { recursive: true });
+    const files = fs5.readdirSync(dir, { recursive: true });
     for (const file of files) {
       if (typeof file !== "string") continue;
-      const filePath = path8.join(dir, file);
+      const filePath = path11.join(dir, file);
       try {
-        if (fs2.statSync(filePath).isFile() && /\.(ts|js|mts|mjs|tsx|jsx)$/.test(file)) {
+        if (fs5.statSync(filePath).isFile() && /\.(ts|js|mts|mjs|tsx|jsx)$/.test(file)) {
           sourceFiles.push(filePath);
         }
       } catch {
@@ -3028,11 +3758,11 @@ ${presetType} presets:
 }
 
 // src/commands/codemod-trace.ts
-import * as path10 from "path";
+import * as path13 from "path";
 import { glob as glob2 } from "glob";
 
 // src/lib/codemod-trace.ts
-import * as path9 from "path";
+import * as path12 from "path";
 import { Project, SyntaxKind } from "ts-morph";
 var TRACE_IMPORT_MODULE = "autotel";
 function hasTraceImport(sourceFile) {
@@ -3055,8 +3785,8 @@ function addTraceImport(sourceFile) {
   });
 }
 function expandNamePattern(pattern, name, filePath, cwd) {
-  const file = path9.basename(filePath, path9.extname(filePath));
-  const relPath = path9.relative(cwd, filePath).replaceAll("\\", "/");
+  const file = path12.basename(filePath, path12.extname(filePath));
+  const relPath = path12.relative(cwd, filePath).replaceAll("\\", "/");
   return pattern.replaceAll("{name}", name).replaceAll("{file}", file).replaceAll("{path}", relPath);
 }
 function getSpanName(name, filePath, options) {
@@ -3292,28 +4022,28 @@ var GLOB_META = /[*?[\]]/;
 async function resolveCodemodFiles(pathArg, cwd) {
   const isGlob = GLOB_META.test(pathArg);
   if (!isGlob) {
-    const absolute = path10.isAbsolute(pathArg) ? pathArg : path10.resolve(cwd, pathArg);
+    const absolute = path13.isAbsolute(pathArg) ? pathArg : path13.resolve(cwd, pathArg);
     if (fileExists(absolute)) {
-      const ext = path10.extname(absolute);
+      const ext = path13.extname(absolute);
       if (CODEMOD_EXTENSIONS.has(ext) && !absolute.endsWith(".d.ts")) {
         return [absolute];
       }
       return [];
     }
   }
-  const pattern = path10.isAbsolute(pathArg) ? pathArg : path10.join(cwd, pathArg);
+  const pattern = path13.isAbsolute(pathArg) ? pathArg : path13.join(cwd, pathArg);
   const matches = await glob2(pattern, {
     cwd,
     absolute: true,
     ignore: ["**/node_modules/**", "**/*.d.ts"]
   });
   return matches.filter((f) => {
-    const ext = path10.extname(f);
+    const ext = path13.extname(f);
     return CODEMOD_EXTENSIONS.has(ext) && !f.endsWith(".d.ts");
   });
 }
 async function runCodemodTrace(options) {
-  const { path: pathArg, cwd, dryRun, namePattern, skip, printFiles, verbose: verbose2, quiet } = options;
+  const { path: pathArg, cwd, dryRun, namePattern, skip, printFiles, verbose, quiet } = options;
   const files = await resolveCodemodFiles(pathArg, cwd);
   if (files.length === 0) {
     if (!quiet) {
@@ -3329,7 +4059,7 @@ async function runCodemodTrace(options) {
   for (const filePath of files) {
     const content = readFileSafe(filePath);
     if (content === null) {
-      if (verbose2) dim(`Skip ${filePath} (unreadable)`);
+      if (verbose) dim(`Skip ${filePath} (unreadable)`);
       continue;
     }
     let result;
@@ -3339,17 +4069,17 @@ async function runCodemodTrace(options) {
       if (!quiet) {
         error(`Failed to transform ${filePath}: ${error2 instanceof Error ? error2.message : String(error2)}`);
       }
-      if (verbose2 && error2 instanceof Error && error2.stack) dim(error2.stack);
+      if (verbose && error2 instanceof Error && error2.stack) dim(error2.stack);
       process.exitCode = 1;
       continue;
     }
-    const relativePath = path10.relative(cwd, filePath);
+    const relativePath = path13.relative(cwd, filePath);
     if (result.changed) {
       totalWrapped += result.wrappedCount;
       totalChanged += 1;
       if (!dryRun) {
-        const fs3 = await import("fs");
-        fs3.writeFileSync(filePath, result.modified, "utf8");
+        const fs7 = await import("fs");
+        fs7.writeFileSync(filePath, result.modified, "utf8");
       }
     }
     const showSummary = printFiles || dryRun || result.changed;
@@ -3368,6 +4098,369 @@ async function runCodemodTrace(options) {
   }
 }
 
+// src/commands/schema.ts
+import * as fs6 from "fs";
+import * as path14 from "path";
+import { fileURLToPath } from "url";
+
+// src/lib/manifest.ts
+var GLOBAL_FLAGS = [
+  {
+    name: "--cwd",
+    takesValue: true,
+    description: "Target directory (default: current working directory)"
+  },
+  { name: "--verbose", description: "Show detailed output" },
+  { name: "--quiet", description: "Only show warnings and errors" }
+];
+var AGENT_FLAGS = [
+  {
+    name: "--json",
+    description: "Emit machine-readable JSON instead of human output"
+  },
+  {
+    name: "--output-file",
+    takesValue: true,
+    description: "Persist the first JSON payload to this path"
+  },
+  {
+    name: "--no-secrets-in-output",
+    description: "Redact secret-shaped values (also via AUTOTEL_NO_SECRETS=1 / AGENT_SANDBOX=1)"
+  },
+  {
+    name: "--no-interactive",
+    description: "Never prompt; fail fast if input is required"
+  }
+];
+var COMMANDS = [
+  {
+    name: "init",
+    description: "Initialise autotel in your project",
+    flags: [
+      ...GLOBAL_FLAGS,
+      ...AGENT_FLAGS,
+      { name: "--dry-run", description: "Print what would be done; write nothing" },
+      { name: "--no-install", description: "Generate files only, skip package installation" },
+      { name: "--print-install-cmd", description: "Output install command without running it" },
+      { name: "--yes", alias: "-y", description: "Auto-apply detected items; no prompts" },
+      { name: "--preset", takesValue: true, description: "Use a named quick preset" },
+      { name: "--force", description: "Overwrite existing config (creates backup)" },
+      { name: "--workspace-root", description: "Install at workspace root, not package root" },
+      { name: "--no-detect", description: "Skip auto-detection of installed deps" },
+      { name: "--detect-only", description: "Run detection and print the proposal; write nothing" },
+      { name: "--plan", takesValue: true, description: "Read a pre-built InitPlan JSON from this path and apply it" },
+      { name: "--input", takesValue: true, description: "Read InitPlan JSON from stdin (-) or a file" },
+      { name: "--scan-env", description: "Consent to reading uncommitted .env files for backend detection" }
+    ],
+    mutating: true,
+    network: true,
+    writesFiles: true,
+    supportsDryRun: true,
+    requiresPackageJson: true,
+    mayReadEnv: true,
+    supportsJson: true,
+    examples: [
+      { description: "Interactive setup with detection", command: "autotel init" },
+      { description: "Non-interactive, apply all detected items", command: "autotel init --yes" },
+      { description: "Preview as JSON without writing", command: "autotel init --json --dry-run" },
+      { description: "Detection only", command: "autotel init --detect-only --json" }
+    ]
+  },
+  {
+    name: "doctor",
+    description: "Run diagnostics on your autotel setup",
+    flags: [
+      ...GLOBAL_FLAGS,
+      ...AGENT_FLAGS,
+      { name: "--fix", description: "Auto-fix resolvable issues" },
+      { name: "--list-checks", description: "List all available checks" },
+      { name: "--env-file", takesValue: true, description: "Path to env file to check" }
+    ],
+    mutating: false,
+    network: false,
+    writesFiles: false,
+    supportsDryRun: false,
+    requiresPackageJson: true,
+    mayReadEnv: true,
+    supportsJson: true
+  },
+  {
+    name: "add",
+    description: "Add a backend, subscriber, plugin, or platform incrementally",
+    args: [
+      { name: "type", required: false, description: "Preset type" },
+      { name: "name", required: false, description: "Preset name" }
+    ],
+    flags: [
+      ...GLOBAL_FLAGS,
+      ...AGENT_FLAGS,
+      { name: "--list", description: "List available presets for the given type" },
+      { name: "--dry-run", description: "Print what would be done" },
+      { name: "--no-install", description: "Generate files only" },
+      { name: "--print-install-cmd", description: "Output install command without running" },
+      { name: "--yes", alias: "-y", description: "Accept defaults" },
+      { name: "--force", description: "Overwrite non-CLI-owned config" },
+      { name: "--workspace-root", description: "Install at workspace root" }
+    ],
+    mutating: true,
+    network: true,
+    writesFiles: true,
+    supportsDryRun: true,
+    requiresPackageJson: true,
+    mayReadEnv: false,
+    supportsJson: true
+  },
+  {
+    name: "codemod trace",
+    description: "Wrap functions in trace() with span name from function/variable/method name",
+    args: [{ name: "path", required: true, description: "File path or glob" }],
+    flags: [
+      ...GLOBAL_FLAGS,
+      { name: "--dry-run", description: "Print changes without writing files" },
+      { name: "--name-pattern", takesValue: true, description: "Span name template" },
+      { name: "--skip", takesValue: true, description: "Skip functions whose name matches (repeatable)" },
+      { name: "--print-files", description: "Print per-file summary" }
+    ],
+    mutating: true,
+    network: false,
+    writesFiles: true,
+    supportsDryRun: true,
+    requiresPackageJson: false,
+    mayReadEnv: false,
+    supportsJson: false
+  },
+  {
+    name: "schema",
+    description: "Print the CLI manifest as JSON (agent discovery)",
+    flags: [
+      { name: "--json", description: "Always JSON (this command is JSON-only)" }
+    ],
+    mutating: false,
+    network: false,
+    writesFiles: false,
+    supportsDryRun: false,
+    requiresPackageJson: false,
+    mayReadEnv: false,
+    supportsJson: true
+  },
+  {
+    name: "schema errors",
+    description: "Print error envelope shape + AUTOTEL_E_* enum",
+    flags: [{ name: "--json", description: "Always JSON" }],
+    mutating: false,
+    network: false,
+    writesFiles: false,
+    supportsDryRun: false,
+    requiresPackageJson: false,
+    mayReadEnv: false,
+    supportsJson: true
+  },
+  {
+    name: "schema outputs",
+    description: "Print JSON output shapes per command",
+    flags: [{ name: "--json", description: "Always JSON" }],
+    mutating: false,
+    network: false,
+    writesFiles: false,
+    supportsDryRun: false,
+    requiresPackageJson: false,
+    mayReadEnv: false,
+    supportsJson: true
+  },
+  {
+    name: "commands",
+    description: "Print compact tool-style command listing",
+    flags: [{ name: "--json", description: "Always JSON" }],
+    mutating: false,
+    network: false,
+    writesFiles: false,
+    supportsDryRun: false,
+    requiresPackageJson: false,
+    mayReadEnv: false,
+    supportsJson: true
+  },
+  {
+    name: "examples",
+    description: "Print copy-pasteable examples for a command",
+    args: [
+      { name: "command", required: false, description: "Command name (omit for all)" }
+    ],
+    flags: [{ name: "--json", description: "Emit JSON" }],
+    mutating: false,
+    network: false,
+    writesFiles: false,
+    supportsDryRun: false,
+    requiresPackageJson: false,
+    mayReadEnv: false,
+    supportsJson: true
+  },
+  {
+    name: "version",
+    description: "Print version info",
+    flags: [{ name: "--json", description: "Emit JSON" }],
+    mutating: false,
+    network: false,
+    writesFiles: false,
+    supportsDryRun: false,
+    requiresPackageJson: false,
+    mayReadEnv: false,
+    supportsJson: true
+  }
+];
+function getCommand(name) {
+  return COMMANDS.find((c) => c.name === name);
+}
+var ERROR_CATALOGUE = [
+  { code: AutotelErrorCodes.E_NO_PACKAGE_JSON, type: "environment", description: "No package.json found in cwd or ancestors" },
+  { code: AutotelErrorCodes.E_UNKNOWN_PRESET, type: "validation", description: "Preset slug not in registry" },
+  { code: AutotelErrorCodes.E_INVALID_PLAN, type: "validation", description: "Plan file failed schema validation" },
+  { code: AutotelErrorCodes.E_INVALID_INPUT, type: "validation", description: "Stdin or --input payload invalid" },
+  { code: AutotelErrorCodes.E_INVALID_FLAG, type: "validation", description: "Conflicting or invalid flag combination" },
+  { code: AutotelErrorCodes.E_NO_WORKSPACE_PACKAGES, type: "environment", description: "Workspace root has no detectable packages" },
+  { code: AutotelErrorCodes.E_ENV_CONSENT_REQUIRED, type: "environment", description: ".env file present; consent required (pass --scan-env or run interactively)" },
+  { code: AutotelErrorCodes.E_EXISTING_CONFIG, type: "conflict", description: "Existing instrumentation config; use --force or run with merge" },
+  { code: AutotelErrorCodes.E_AMBIGUOUS_LOGGER, type: "conflict", description: "Multiple loggers detected and selection could not be inferred" },
+  { code: AutotelErrorCodes.E_INSTALL_FAILED, type: "install", description: "Package manager install command failed" },
+  { code: AutotelErrorCodes.E_WRITE_FAILED, type: "io", description: "Failed to write a file" },
+  { code: AutotelErrorCodes.E_READ_FAILED, type: "io", description: "Failed to read a file" },
+  { code: AutotelErrorCodes.E_UNKNOWN, type: "runtime", description: "Unexpected error" }
+];
+
+// src/commands/schema.ts
+function configure(opts) {
+  configureJsonOutput({
+    outputFile: opts.outputFile,
+    noSecrets: opts.noSecrets
+  });
+}
+function readSelfVersion() {
+  try {
+    const here = path14.dirname(fileURLToPath(import.meta.url));
+    let dir = here;
+    for (let i = 0; i < 5; i++) {
+      const candidate = path14.join(dir, "package.json");
+      if (fs6.existsSync(candidate)) {
+        const pkg = JSON.parse(fs6.readFileSync(candidate, "utf8"));
+        if (pkg.name === "autotel-cli") return String(pkg.version ?? "0.0.0");
+      }
+      dir = path14.dirname(dir);
+    }
+  } catch {
+  }
+  return "0.0.0";
+}
+function runSchema(opts) {
+  configure(opts);
+  printJson({
+    ok: true,
+    command: "autotel schema",
+    version: readSelfVersion(),
+    commands: COMMANDS
+  });
+}
+function runSchemaErrors(opts) {
+  configure(opts);
+  printJson({
+    ok: true,
+    command: "autotel schema errors",
+    envelope: {
+      ok: false,
+      command: "<command>",
+      error: {
+        type: "<one of: validation, environment, auth, conflict, install, io, runtime>",
+        code: "<AUTOTEL_E_*>",
+        message: "human-readable message",
+        retryable: false,
+        fix: "optional remediation hint",
+        expected: { "<key>": "<value>" },
+        suggestions: ["optional follow-up commands"]
+      }
+    },
+    codes: ERROR_CATALOGUE,
+    exitCodes: {
+      "0": "success",
+      "1": "runtime / unexpected failure",
+      "2": "validation / conflict / refusal"
+    }
+  });
+}
+function runSchemaOutputs(opts) {
+  configure(opts);
+  printJson({
+    ok: true,
+    command: "autotel schema outputs",
+    outputs: {
+      "autotel init --json": {
+        ok: "boolean",
+        command: "string",
+        detected: {
+          packages: 'array of { name, version, resolution: "target" | "workspace-root" }',
+          logger: '"pino" | "winston" | "bunyan" | null',
+          backend: '{ source: "env" | "wrangler" | "deps" | "prompt" | "default", value: string }',
+          platform: '"cloudflare" | "aws-lambda" | "edge" | null'
+        },
+        plan: {
+          presets: "string[] (slugs)",
+          packagesToInstall: { prod: "string[]", dev: "string[]" },
+          filesToWrite: 'array of { path, action: "create" | "merge" | "skip" }',
+          envVars: "array of { name, sensitive, action }"
+        },
+        nextSteps: "string[]"
+      }
+    }
+  });
+}
+function runCommandsListing(opts) {
+  configure(opts);
+  const compact = COMMANDS.map((c) => ({
+    name: c.name,
+    description: c.description,
+    mutating: c.mutating,
+    network: c.network,
+    writesFiles: c.writesFiles,
+    supportsDryRun: c.supportsDryRun,
+    supportsJson: c.supportsJson
+  }));
+  printJson({ ok: true, command: "autotel commands", commands: compact });
+}
+function runExamples(name, opts) {
+  configure(opts);
+  if (name === void 0) {
+    const all = COMMANDS.filter((c) => c.examples && c.examples.length > 0).map(
+      (c) => ({ command: c.name, examples: c.examples })
+    );
+    printJson({ ok: true, command: "autotel examples", examples: all });
+    return;
+  }
+  const cmd = getCommand(name);
+  if (!cmd) {
+    throw new AutotelError({
+      type: "validation",
+      code: AutotelErrorCodes.E_INVALID_INPUT,
+      message: `Unknown command: ${name}`,
+      expected: { command: COMMANDS.map((c) => c.name) },
+      fix: "Run `autotel commands --json` to see available commands"
+    });
+  }
+  printJson({
+    ok: true,
+    command: "autotel examples",
+    target: cmd.name,
+    examples: cmd.examples ?? []
+  });
+}
+function runVersion(opts) {
+  configure(opts);
+  printJson({
+    ok: true,
+    command: "autotel version",
+    version: readSelfVersion(),
+    node: process.version,
+    platform: process.platform,
+    arch: process.arch
+  });
+}
+
 // src/cli.ts
 function createProgram() {
   const program = new Command();
@@ -3375,18 +4468,27 @@ function createProgram() {
   const addGlobalOptions = (cmd) => {
     return cmd.option("--cwd <path>", "Target directory", process.cwd()).option("--verbose", "Show detailed output").option("--quiet", "Only show warnings and errors");
   };
-  const initCmd = new Command("init").description("Initialize autotel in your project").option("--dry-run", "Skip installation and print what would be done").option("--no-install", "Generate files only, skip package installation").option("--print-install-cmd", "Output the install command without running it").option("-y, --yes", "Accept defaults, non-interactive").option("--preset <name>", "Use a quick preset (e.g., node-datadog-pino)").option("--force", "Overwrite existing config (creates backup first)").option("--workspace-root", "Install at workspace root instead of package root").action(async (opts) => {
+  const initCmd = new Command("init").description("Initialize autotel in your project").option("--dry-run", "Skip installation and print what would be done").option("--no-install", "Generate files only, skip package installation").option("--print-install-cmd", "Output the install command without running it").option("-y, --yes", "Accept defaults, non-interactive").option("--preset <name>", "Use a quick preset (e.g., node-datadog-pino)").option("--force", "Overwrite existing config (creates backup first)").option("--workspace-root", "Install at workspace root instead of package root").option("--no-detect", "Skip auto-detection of installed deps").option("--detect-only", "Run detection, print the plan, write nothing").option("--plan <path>", "Apply a pre-built InitPlan JSON file").option("--input <path>", "Read InitPlan JSON from stdin (-) or a file").option("--scan-env", "Consent to reading .env / .env.local for backend detection").option("--json", "Emit machine-readable JSON").option("--output-file <path>", "Persist JSON output to this file").option("--no-secrets-in-output", "Redact secret-shaped values").option("--no-interactive", "Never prompt; fail if input would be required").action(async (opts) => {
     const options = {
       cwd: opts.cwd ?? process.cwd(),
       dryRun: opts.dryRun ?? false,
-      noInstall: opts.noInstall ?? false,
+      noInstall: opts.install === false,
       printInstallCmd: opts.printInstallCmd ?? false,
       verbose: opts.verbose ?? false,
       quiet: opts.quiet ?? false,
       workspaceRoot: opts.workspaceRoot ?? false,
       yes: opts.yes ?? false,
       preset: opts.preset,
-      force: opts.force ?? false
+      force: opts.force ?? false,
+      noDetect: opts.detect === false,
+      detectOnly: opts.detectOnly ?? false,
+      plan: opts.plan,
+      input: opts.input,
+      scanEnv: opts.scanEnv ?? false,
+      json: opts.json ?? false,
+      outputFile: opts.outputFile,
+      noSecrets: opts.secretsInOutput === false,
+      noInteractive: opts.interactive === false
     };
     if (options.dryRun) {
       options.noInstall = true;
@@ -3457,6 +4559,30 @@ function createProgram() {
   codemodCmd.addCommand(traceCmd);
   addGlobalOptions(codemodCmd);
   program.addCommand(codemodCmd);
+  const schemaCmd = new Command("schema").description("Print the CLI manifest as JSON (agent discovery)").option("--output-file <path>", "Persist JSON to a file").option("--no-secrets-in-output", "Redact secret-shaped values").action((opts) => {
+    runSchema({ outputFile: opts.outputFile, noSecrets: opts.secretsInOutput === false });
+  });
+  const schemaErrorsCmd = new Command("errors").description("Print error envelope shape + AUTOTEL_E_* codes").option("--output-file <path>", "Persist JSON to a file").action((opts) => {
+    runSchemaErrors({ outputFile: opts.outputFile });
+  });
+  const schemaOutputsCmd = new Command("outputs").description("Print JSON output shapes per command").option("--output-file <path>", "Persist JSON to a file").action((opts) => {
+    runSchemaOutputs({ outputFile: opts.outputFile });
+  });
+  schemaCmd.addCommand(schemaErrorsCmd);
+  schemaCmd.addCommand(schemaOutputsCmd);
+  program.addCommand(schemaCmd);
+  const commandsCmd = new Command("commands").description("Print compact tool-style listing of commands").option("--output-file <path>", "Persist JSON to a file").action((opts) => {
+    runCommandsListing({ outputFile: opts.outputFile });
+  });
+  program.addCommand(commandsCmd);
+  const examplesCmd = new Command("examples").description("Print copy-pasteable examples for a command").argument("[command]", "Command name (omit for all)").option("--output-file <path>", "Persist JSON to a file").action((name, opts) => {
+    runExamples(name, { outputFile: opts.outputFile });
+  });
+  program.addCommand(examplesCmd);
+  const versionCmd = new Command("version").description("Print version info as JSON").option("--output-file <path>", "Persist JSON to a file").action((opts) => {
+    runVersion({ outputFile: opts.outputFile });
+  });
+  program.addCommand(versionCmd);
   return program;
 }
 async function run() {
@@ -3465,8 +4591,24 @@ async function run() {
 }
 
 // src/index.ts
+function jsonModeRequested() {
+  return process.argv.includes("--json");
+}
 run().catch((error2) => {
-  console.error("Error:", error2 instanceof Error ? error2.message : error2);
-  process.exit(1);
+  const err = toAutotelError(error2);
+  const isJson = jsonModeRequested() || // schema/commands/examples/version are JSON-only
+  /^(schema|commands|examples|version)\b/.test(
+    process.argv.slice(2).join(" ")
+  );
+  if (isJson) {
+    printJson(err.toEnvelope());
+  } else {
+    process.stderr.write(
+      `Error [${err.code}]: ${err.message}
+` + (err.fix !== void 0 ? `Fix: ${err.fix}
+` : "")
+    );
+  }
+  process.exit(exitCodeForError(err));
 });
 //# sourceMappingURL=index.js.map